# 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.
## 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: ```json {Cabeçalho em Base64url}.{Payload em Base64url}.{Assinatura em Base64url} ``` O texto base para a assinatura é composto pela seguinte forma: ```json {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: ```json {"alg":"RS256","typ":"JWT"} ``` A representação em Base64url se dá da seguinte forma: ```json 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 .

Casos recorrentes que NÃO funcionam:

- Inserção de uma barra ao final do endereço:

- Uso do 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. 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: ```json exp = iat + 3600 ``` A representação dos campos JSON obrigatórios no payload do JWT se dá da seguinte forma: ```json { "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: ```json {"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: ```json 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](https://jwt.io/). ## 2 - Fazendo a requisição de um token de acesso[​](https://developers.unico.io/docs/you/identity/service-account-integration/get-token#2---fazendo-a-requisi%C3%A7%C3%A3o-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. | ```javascript 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[​](https://developers.unico.io/docs/you/identity/service-account-integration/get-token#3---tratando-a-resposta-da-plataforma-de-autentica%C3%A7%C3%A3o) *** 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: ```json { "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 seção "Erros de autenticação". ### 4 - Duração do token de acesso[​](https://developers.unico.io/docs/you/identity/service-account-integration/get-token#4---dura%C3%A7%C3%A3o-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: ```json token decodificado: new Date(token.exp - 600) ``` 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 as 14h42 Solicitar um novo token somente as 15h32 ou seja, 14:42 + (3600 - 600) ``` ``` Cenário com a duração alterada: 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](https://tools.ietf.org/html/rfc7515).