Skip to main content

Preparando para fazer uma requisição autenticada à API

Após a criação e configuração de uma conta de serviço, sua aplicação precisa completar as seguintes etapas:

  1. Criar um JSON Web Token (JWT), que inclui cabeçalho, payload e assinatura;
  2. Requisitar um token de acesso (AccessToken) da plataforma de autenticação OAuth2;
  3. Tratar a resposta JSON que a plataforma de autenticação retornará.

Se na resposta estiver incluso um token de acesso, você poderá usá-lo para fazer requisições às APIs dos produtos da unico para os quais a conta de serviço possui permissão de acesso. (Se na resposta não estiver incluso um token de acesso, seu JWT e requisição de obtenção do token podem estar incorretos ou a conta de serviço pode não ter as permissões necessárias para acessar os recursos solicitados.)

O token de acesso gerado na requisição mencionada acima tem validade padrão de 3600 segundos, podendo variar de acordo com a configuração de segurança estabelecida para sua empresa. Quando o token de acesso expirar, sua aplicação deverá gerar um novo JWT, fazer a assinatura e requisitar um novo token de acesso na plataforma de autenticação.

Captura Manual

1 - Criando o JWT

Um JWT é composto por três partes: um cabeçalho, um payload e uma assinatura. O cabeçalho e o payload são objetos JSON. Esses objetos JSON são serializados em UTF-8 e então codificados usando codificação Base64url¹. Esta codificação provê resliência contra alterações de codificação em casos de repetidas operações de codificação. O cabeçalho, o payload e a assinatura são concatenadas com um caractere de ponto final ..

Um JWT é composto da seguinte forma:

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

O texto base para a assinatura é composto pela seguinte forma:

{Cabeçalho em Base64url}.{Payload em Base64url}

1.1 - Formando o cabeçalho JWT

O cabeçalho consiste em dois campos que indicam o algorítimo de assinatura e o formato do token. Ambos os campos são obrigatórios e cada campo possui apenas um valor. Contas de serviço dependem do algorítimo RSA SHA-256 e do formato de token JWT. Como resultado, a representação JSON do cabeçalho se dá da seguinte forma:

{"alg":"RS256","typ":"JWT"}

A representação em Base64url se dá da seguinte forma:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.2 - Formando o payload JWT

O payload JWT contém informações sobre o JWT, incluindo as permissões sendo requisitadas (scopes), a conta solicitando acesso, o emissor, o momento em que o token foi emitido e o tempo de vida do token. A maioria dos campos são obrigatórios. Assim como o cabeçalho JWT, o payload é um objeto JSON e é usado na composição da assinatura.

1.3 - Campos Obrigatórios

Os campos obrigatórios no JWT são mostrados na tabela abaixo. Eles podem aparecer em qualquer ordem dentro do payload.

NomeDescrição
issO identificador da conta de serviço na empresa.
scopeUma lista delimitada por espaços ou pelo sinal de positivo + das permissões que a aplicação está requisitando. Se todas as permissões da conta forem necessárias, utilizar o sinal de asterisco * para tal.
audEndereço da plataforma de autenticação que faz a emissão de tokens de acesso. Este valor deverá ser sempre e exatamente https://identityhomolog.acesso.io
Casos recorrentes que NÃO funcionam:
- Inserção de uma barra ao final do endereço: https://identityhomolog.acesso.io/
- Uso do protocolo HTTP ao invés de HTTPS: http://identityhomolog.acesso.io
expO tempo de expiração do token, especificado em segundos desde 00:00:00 UTC, 1 de Janeiro de 1970. Este valor tem um tempo máximo de 1 hora após o momento da emissão do JWT. Este valor deve ser numérico.
Casos recorrentes que NÃO funcionam:
- Uso de aspas na delimitação do valor. Ex.: “1524161193” é uma string e não funcionará. Já 1524161193 é um número e funcionará.
iatO momento da emissão do JWT, especificado em segundos desde 00:00:00 UTC, 1 de Janeiro de 1970. Este valor deve ser numérico.
- Uso de aspas na delimitação do valor. Ex.: “1524161193” é uma string e não funcionará. Já 1524161193 é um número e funcionará.

Entenda como funciona a conversão para os campos de emissão (iat) e expiração (exp) do jwt, e veja também exemplos de utilização dos valores dos campos aqui. Além disso, o campo “iat” deve ser o horário atual no formato exigido e o “exp” deve respeitar a conta abaixo:

exp = iat + 3600

A representação dos campos JSON obrigatórios no payload do JWT se dá da seguinte forma:

{
"iss": "service_account_name@tenant_id.iam.acesso.io",
"aud": "https://identityhomolog.acesso.io",
"scope": "*",
"exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
"iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}

1.4 -Calculando a assinatura

A especificação JSON Web Signature (JWS)² é a mecânica que guia o cálculo da assinatura para um JWT. O conteúdo de entrada para o cálculo da assinatura é o byte array do seguinte conteúdo:

{Cabeçalho em Base64url}.{Payload em Base64url}

O mesmo algoritmo sinalizado no cabeçalho do JWT precisa ser utilizado para o cálculo da assinatura. O único algorítimo de assinatura suportado pela plataforma de autenticação OAuth2 é o RSA usando SHA-256. Ele é expressado como RS256 no campo alg do cabeçaho do JWT.

Assine a representação UTF-8 do conteúdo de entrada utilizando SHA256withRSA (também conhecido como RSASSA-PKCS1-V1_5-SIGN com o hash SHA-256) com a chave privada que foi criada e associada à conta de serviço (arquivo .key.pem gerado pela solicitação recebida por e-mail). O conteúdo de saída será um byte array.

A assinatura precisará ser então codificada em Base64url. O cabeçalho, o payload e a assinatura deverão ser concatenadas com o caractere de ponto final .. O resultado é o JWT. Ele deve ser da seguinte forma:

{Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url}

A seguir está um exemplo de token JWT antes da codificação em Base64url:

{"alg":"RS256","typ":"JWT"}.
{
"iss": "service_account_name@tenant_id.iam.acesso.io",
"aud": "https://identityhomolog.acesso.io",
"scope": "*",
"exp": 1626296976, // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
"iat": 1626293376 // Este é apenas um exemplo. Utilize aqui o valor atual gerado.
}.
[byte array da assinatura]

Abaixo está um exemplo do JWT que foi assinado e está pronto para transmissão:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY291bnRf
bmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb
3BlIjoiKiIsImV4cCI6MTYyNjI5Njk3NiwiaWF0IjoxNjI2MjkzMzc2fQ.JsymP3NZdgCSqeNlgsOM2
-AQ7M450NxFnZnnaKSu4Q8g12QGEIvvM4EhCokUHfwk5s7pOpm2UD_Ng3Hb5g_wgrjfiVSLWH5Q2wYg1AvfLqo
YSoJWaMHm9KL0kpv32XdDD8TZVR-MVd2VBHmCMVbV6gvk8buUoK1HZDN7g84PaY3bfgcB3RKU-
H55lR8yyJjZxToIv17-wfla2G99uaMEFNGX0ZSE7ETn5Z8-WypmFrNAK0TM58upzvfVI6_-
gY4cj4iQvmRbuvxsAaGiHA2xd0RVm2Mrx-gQtdPqtbZPuQcH7k64Z_EOQBgiGTgVjucyHD6zBijr_P-
2mhIxuecNSw

Também é possível utilizar bibliotecas previamente estabelecidas para realizar a criação do JWT. Como referência, é possível encontrar uma lista de bibliotecas no site jwt.io.

2 - Fazendo a requisição de um token de acesso

Após a geração do JWT assinado, uma aplicação pode utilizá-lo para requisitar um token de acesso (Access Token). A requisição do token de acesso é uma requisição POST HTTPS e o corpo deve ser URL encoded. A URL é a mostrada abaixo:

https://identityhomolog.acesso.io/oauth2/token

Os parâmetros abaixo são obrigatórios na requisição POST HTTPS:

NomeDescrição
grant_typeUtilize o seguinte texto, URL-encoded se necessário: urn:ietf:params:oauth:grant-type:jwt-bearer
assertionO JWT, incluindo a assinatura.
POST /oauth2/token HTTP/1.1
Host: identityhomolog.acesso.io
Content-Type: application/x-www-form-urlencoded

grant_type=urn%3Aietf%3Aparams%3Aoauth%3Agrant-type%3Ajwt-
bearer&assertion=eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzZXJ2aWNlX2FjY
291bnRfbmFtZUB0ZW5hbnRfaWQuaWFtLmFjZXNzby5pbyIsInN1YiI6InVzZXJfaWRlbnRpZmllciIs
ImF1ZCI6Imh0dHBzOi8vaWRlbnRpdHlob21vbG9nLmFjZXNzby5pbyIsInNjb3BlIjoiKiIsImV4cCI
6MTMyODU1NDM4NSwiaWF0IjoxMzI4NTUwNzg1fQ.TjH-mTtwP6tBB93O1sDPaAA6yUF7N2-HZDlpIPz
bf_dxO8A6KZuRWG8ZnICrxX56qj0HREiMlYy27XJgxowrUa0JHvbqc8HJkT7-6Mh7J67UnubZKG1-hi
6jDtkC9BIXBcOhtkNUfZvZetXjLzsRsSDkqxdMtzYZwkRlocvaxL5QXiQhweeEwK_Ux81Adh3z0EIhT
yl7CKJLJ69PuHS7s9IdrjUl79owipp4LF1FvtMhoe7YIL69ohPgFqSv_-Y9qpPdW6be3OEAyKlOM08S
ZBbHBwW4XMvw3uZjTY1sgJ4cBoxrftDpjYOw34oPOKxirqc5-90uOCYe1O1hRtG45w

3 - Tratando a resposta da plataforma de autenticação

Se o JWT e a requisição do token de acesso foram formados apropriadamente e a conta de serviço tem as permissões necessárias, então a resposta da plataforma de autenticação retorna um objeto JSON contendo um token de acesso. Segue um exemplo de resposta da plataforma:

{
"access_token": "<access_token>",
"token_type": "Bearer",
"expires_in": "3600"
}

O token de acesso retornado no campo “acess_token” do objeto JSON também é um token JWT que deverá ser utilizado nas APIs dos Produtos da unico. Caso retorne um erro na requisição, é possível consultar o tipo do erro na tabela de erros clicando aqui.

4 - Duração do token de acesso

A duração do token de acesso é variável. Sua duração é especificada no campo “expires_in”, retornado juntamente com o token de acesso. Deve-se utilizar o mesmo token de acesso durante a sua validade para todas as chamdas às APIs dos produtos.

Não solicite um novo token de acesso até que a validade do token atual esteja chegando ao fim. Sugerimos uma margem de 600 segundos (10 minutos). Para isso execute o cálculo:

token decodificado:
new Date(token.exp - 600)

Sendo que token.exp é o timestamp da expiração do token.

Dica

Por padrão, o token enviado para a empresa tem duração de 1h, mas pode ser alterado. A sugestão é sempre usar o expires_in como base e subtrair 600s dele para pedir um novo token.

Exemplos:

Cenário padrão:
expires_in: 3600 (1h) - Geração do token as 14h42

Solicitar um novo token somente as 15h32 ou seja, 14:42 + (3600 - 600)
Cenário com a duração alterda:
expires_in: 7200 (2h) - Geração do token as 14h42

Solicitar um novo token somente as 16h32 ou seja, 14:42 + (7200 - 600)

Um novo token de acesso pode ser solicitado quando faltar 10 minutos pra expirar.

Não utilize um tempo fixo para a obtenção de um novo token, pois o tempo de duração do token recebido pode ser menor que o tempo estabelecido, o que ocasionará falha na utilização dos serviços.

  • ¹ De acordo com o RFC 4648 de codificação BaseN, o formato Base64url é similar ao formato Base64, com exceção do caracter = que deve ser omitido, e dos caracteres + e / que devem ser substituídospor - e _, respectivamente.
  • ² JSON Web Signature: https://tools.ietf.org/html/rfc7515