Preparando para fazer uma requisição autenticada à API
Last updated
Last updated
Copyright © 2024 unico. All rights reserved.
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.
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:
O texto base para a assinatura é composto pela seguinte forma:
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:
A representação em Base64url se dá da seguinte forma:
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.
Os campos obrigatórios no JWT são mostrados na tabela abaixo. Eles podem aparecer em qualquer ordem dentro do payload.
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
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:
A representação dos campos JSON obrigatórios no payload do JWT se dá da seguinte forma:
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:
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:
A seguir está um exemplo de token JWT antes da codificação em Base64url:
Abaixo está um exemplo do JWT que foi assinado e está pronto para transmissão:
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.
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:
Os parâmetros abaixo são obrigatórios na requisição POST HTTPS:
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.
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:
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.
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:
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:
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.
Dúvidas?
Não encontrou algo ou ainda precisa de ajuda? Se já é um cliente ou parceiro, pode entrar em contato através da Central de Ajuda.
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:
