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:

Criar um JSON Web Token (JWT), que inclui cabeçalho, payload e assinatura;
Requisitar um token de acesso (AccessToken) da plataforma de autenticação OAuth2;
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.

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.

Nome	Descrição
iss	O identificador da conta de serviço na empresa.
scope	Uma 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.
aud	Endereç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
exp	O 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á.
iat	O 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:

Nome	Descrição
grant_type	Utilize o seguinte texto, URL-encoded se necessário: urn:ietf:params:oauth:grant-type:jwt-bearer
assertion	O 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

1 - Criando o JWT​

1.1 - Formando o cabeçalho JWT​

1.2 - Formando o payload JWT​

1.3 - Campos Obrigatórios​

1.4 -Calculando a assinatura​

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

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

4 - Duração do token de acesso​