Autenticar endpoints da API usando JWT no Jitterbit Studio

Introdução

Os endpoints do API Manager aceitam requisições de qualquer chamador que conheça a URL. Para restringir o acesso, você pode exigir que os chamadores se autentiquem com um JSON Web Token (JWT) assinado: um token compacto e seguro para URL que codifica a identidade do chamador e um tempo de expiração.

Este guia cobre o ciclo completo de autenticação usando o conector JWT:

Uma operação de login aceita a identidade do chamador, gera um JWT assinado e o retorna ao chamador.
Operações protegidas validam o token em cada requisição antes do processamento começar.

O conector JWT manipula a geração e validação de tokens localmente. Ele não se conecta a nenhum serviço externo.

Este guia assume o seguinte:

Uma API personalizada está configurada e publicada no API Manager no mesmo ambiente do projeto.
Você está familiarizado com criar endpoints de API personalizada no API Manager.

Parte 1: Criar a conexão JWT

Uma conexão JWT é um endpoint nomeado que oferece acesso aos tipos de atividade Generate Token, Decode Token e Validate Token.

No Studio, abra a paleta de componentes de design e selecione a aba Project endpoints and connectors.
Localize o conector JWT e configure uma nova conexão.
Connection name: Digite um nome (por exemplo, JWT).
Clique em Save Changes.

O endpoint JWT aparece na aba Project endpoints and connectors. Para mais informações, consulte Conexão JWT.

Parte 2: Criar o endpoint de login

O endpoint de login aceita uma requisição POST e retorna um JWT assinado. Os chamadores apresentam este token no cabeçalho Authorization de todas as requisições subsequentes para endpoints protegidos.

Etapa 1: Armazenar o segredo de assinatura

Tanto a atividade Generate Token quanto a Validate Token usam o mesmo segredo de assinatura. Armazene-o como uma variável de projeto para que seu valor não seja codificado e não apareça nos logs de operação. Para as etapas completas e as melhores práticas para gerenciar credenciais como variáveis de projeto ocultas, consulte Gerenciar credenciais de endpoint.

No Studio, abra o menu de ações do projeto e selecione Project Variables.
Adicione uma variável chamada jwt.secret e digite uma string forte e gerada aleatoriamente como seu valor.
Ative Hide value.
Clique em Save.

Etapa 2: Configurar a atividade Generate Token

Na paleta de componentes de design, expanda o endpoint JWT e arraste o tipo de atividade Generate Token para a tela de design.
Name: Digite um nome (por exemplo, Generate Login Token).
JWT type: Selecione JWS.
Signature type: Selecione Symmetric.
Signature algorithms: Selecione HS256.
Secret key: Digite [jwt.secret].
Expanda Optional settings e adicione as seguintes Payload Properties. Estas fazem referência a variáveis de projeto que o script da operação de login define em tempo de execução:

Key Value Data Type

sub [jwt.sub] string

iat [jwt.iat] number

exp [jwt.exp] number
Clique em Finished.

Para descrições de todas as configurações de atividade, consulte Atividade JWT Generate Token.

No API Manager, clique em New API e selecione Custom API.
Digite um API Name (por exemplo, Auth API), um URL Prefix (por exemplo, auth) e uma string de Version.
Ative SSL.
Clique em Save e depois em Add Service.
Method: Selecione POST.
Path: Digite /token.
Operation: Selecione a operação de login. Se a operação ainda não existir, crie um espaço reservado e retorne para atualizar este campo após concluir a Etapa 4.
Response Type: Selecione System Variable.
Clique em Save e depois em Publish.

A operação de login consiste em um script de preparação e uma transformação que executa a atividade Generate Token.

Crie as variáveis de projeto para as reivindicações de token adicionando-as na gaveta Project Variables junto com jwt.secret:

Nome	Descrição
`jwt.sub`	A identidade do chamador (reivindicação de assunto)
`jwt.iat`	Hora de emissão como um timestamp de época Unix
`jwt.exp`	Hora de expiração como um timestamp de época Unix

Adicione um script de preparação como a primeira etapa da operação de login. Este script lê a identidade do chamador do corpo da solicitação e define as variáveis de projeto de reivindicação:
```
<trans>
$body = JSONParser($jitterbit.api.request.body);

// Set the subject claim from the request body
$jwt.sub = Get($body, "userId");

// Set the issue time and expiry as Unix epoch timestamps
// (seconds since 1970-01-01 00:00:00 UTC)
$jwt.iat = Long(Now());
$jwt.exp = $jwt.iat + 3600;  // 1-hour token lifetime
</trans>
```
Long(Now()) converte a data-hora atual para um inteiro de época Unix (segundos desde 1970-01-01 00:00:00 UTC). Ajuste o deslocamento de expiração (3600) de acordo com o tempo de vida do token exigido pela sua política de segurança.
Adicione uma etapa de transformação após o script de preparação, com a atividade Generate Token como seu destino. Na transformação, mapeie cada variável de projeto de reivindicação para o nó de esquema de payload correspondente. A atividade Generate Token lê os valores de reivindicação de [jwt.sub], [jwt.iat] e [jwt.exp], e escreve o JWT assinado em seu esquema de saída.
Defina a resposta da API adicionando uma segunda transformação (usando o padrão de operação de duas transformações) para mapear o token gerado da saída da atividade para $jitterbit.api.response. A atividade Generate Token escreve o JWT assinado em seu esquema de dados de saída, mostrado em Etapa 2: Revisar os esquemas de dados da configuração da atividade:
```
<trans>
$token_response = Dict();
$token_response["token"] = $jwt_generated_token;
$jitterbit.api.response = JSONStringify($token_response);
$jitterbit.api.response.status_code = 200;
</trans>
```
Substitua $jwt_generated_token pela variável ou caminho que mapeia do esquema de saída da atividade Generate Token. O nome exato do campo é mostrado na etapa de revisão do esquema de dados da configuração da atividade.

Parte 3: Validar o token em endpoints protegidos

Cada operação protegida deve verificar o JWT do chamador antes de processar a solicitação. Adicione uma operação de validação que seja executada antes da operação protegida e retorne uma resposta 401 se o token estiver ausente ou inválido.

Etapa 1: Configurar a atividade Validate Token

Na paleta de componentes de design, expanda o endpoint JWT e arraste o tipo de atividade Validate Token para a tela de design.
Name: Digite um nome (por exemplo, Validate Login Token).
JWT token: Digite [jwt.incoming_token]. Isso faz referência a uma variável de projeto que o script de validação define a partir do cabeçalho Authorization.
JWT type: Selecione JWS.
Secret key: Digite [jwt.secret].
Clique em Finished.

Para descrições de todas as configurações de atividade, consulte JWT Validate Token activity.

Adicione uma variável de projeto chamada jwt.incoming_token na gaveta Project Variables.

Etapa 2: Criar a operação de validação

Crie uma nova operação de script para atuar como gateway do seu endpoint protegido. Esta operação extrai o token, executa a atividade Validate Token e passa o controle para a operação protegida se a validação for bem-sucedida.

Adicione um script de extração como a primeira etapa da operação de validação. Este script lê o cabeçalho Authorization, verifica o prefixo Bearer e define jwt.incoming_token:

<trans>
$auth_header = $jitterbit.api.request.headers.Authorization;

If(Left($auth_header, 7) != "Bearer ",
  $jitterbit.api.response.status_code = 401;
  $err_response = Dict();
  $err_response["error"] = "Missing or malformed Authorization header";
  $jitterbit.api.response = JSONStringify($err_response);
  RaiseError("Unauthorized");
);

$jwt.incoming_token = Mid($auth_header, 8);
</trans>

Left verifica os primeiros sete caracteres do cabeçalho. Mid extrai tudo após o prefixo Bearer. RaiseError interrompe a operação imediatamente e dispara a ação de erro configurada.

Adicione uma transformação de validação com a atividade Validate Token como alvo. A atividade lê o token de [jwt.incoming_token] e verifica sua assinatura contra [jwt.secret]. Se o token for inválido, expirado ou tiver sido alterado, a atividade gera um erro.

Etapa 3: Configure ações de erro e sucesso na operação de validação

Abra as configurações da operação de validação e selecione a aba Actions.

Em caso de falha (token inválido):

Condição: Selecione On Fail.
Ação: Selecione Run Operation.

Operação: Selecione ou crie uma operação de script que retorne uma resposta 401:

<trans>
$jitterbit.api.response.status_code = 401;
$err_response = Dict();
$err_response["error"] = "Invalid or expired token";
$jitterbit.api.response = JSONStringify($err_response);
</trans>

Clique em Add Action.

Em caso de sucesso (token válido):

Condição: Selecione On Success.
Ação: Selecione Run Operation.
Operação: Selecione a operação protegida.
Clique em Add Action.

Salve as configurações. A operação de validação agora funciona como um gateway: se o token for válido, encadeia para a operação protegida; se for inválido ou estiver ausente, retorna 401 e para.

No API Manager, atualize o campo Operation do endpoint protegido para apontar para a operação de validação em vez de apontar diretamente para a operação protegida. A operação de validação encadeia para a operação protegida em caso de sucesso.

Verifique a integração

Implante o projeto e confirme que o endpoint de login e o endpoint protegido estão publicados no API Manager.
Envie uma solicitação POST para o endpoint /auth/token com um corpo JSON contendo um campo userId:
```
{"userId": "user123"}
```
Confirme que o corpo da resposta contém um campo token.
Envie uma solicitação para o endpoint protegido com o token no cabeçalho Authorization:
```
Authorization: Bearer <token>
```
Confirme que a operação é concluída com sucesso.
Envie uma solicitação para o endpoint protegido sem um cabeçalho Authorization. Confirme que o endpoint retorna uma resposta 401.
Modifique a string do token (por exemplo, altere o último caractere) e envie-a. Confirme que o endpoint retorna uma resposta 401.
Se alguma etapa falhar, abra os logs de operação no Studio para verificar se há erros.

Key	Value	Data Type
`sub`	`[jwt.sub]`	`string`
`iat`	`[jwt.iat]`	`number`
`exp`	`[jwt.exp]`	`number`