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ê resiliê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 concatenados 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 que NÃO funcionam: inserir uma barra ao final (https://identityhomolog.acesso.io/) ou usar o protocolo HTTP ao invés de HTTPS. |
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. Deve ser numérico — "1524161193" é uma string e não funcionará; 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. Deve ser numérico, mesma regra do exp. |
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,
"iat": 1626293376
}
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, expressado como RS256 no campo alg do cabeçalho 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 concatenados com o caractere de ponto final. O resultado é o JWT.
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. 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=<jwt>
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:
{
"access_token": "<access_token>",
"token_type": "Bearer",
"expires_in": "3600"
}
O token de acesso retornado no campo access_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, consulte o tipo do erro em Erros de autenticação.
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 chamadas à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):
new Date((token.exp - 600) * 1000)
Sendo que token.exp é o timestamp da expiração do token.
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 às 14h42
Solicitar um novo token somente às 15h32, ou seja, 14:42 + (3600 - 600)
Cenário com a duração alterada:
expires_in: 7200 (2h) - Geração do token às 14h42
Solicitar um novo token somente às 16h32, ou seja, 14:42 + (7200 - 600)
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 caractere = que deve ser omitido, e dos caracteres + e / que devem ser substituídos por - e _, respectivamente.
² JSON Web Signature: https://tools.ietf.org/html/rfc7515.