Obtendo credenciais

A autenticação na plataforma Unico IDCloud utiliza o protocolo OAuth2, no modelo Two-Legged OAuth (2LO).

• É feita por meio de uma conta de serviço, vinculada à aplicação (não a um usuário).

• A aplicação chama as APIs da Unico em nome da conta de serviço.

• Cenário ideal para interações server-to-server.

Solicitação da Conta de Serviço

Para criar a conta de serviço, envie ao gerente de projetos da sua empresa:

• Nome da conta de serviço que será criada (até 12 caracteres);

• Nome, e-mail e celular do responsável pela conta de serviço.

Homologação e Produção requerem contas distintas.

Após o envio dos dados a conta de serviço será criada e você receberá um e-mail para gerar a chave privada (.PEM). A conta de serviço inclui:

• Nome único da conta.

• Tenant ID (identificador da empresa).

• O payload base para montar o JWT

• Chave privada (.PEM) - o navegador fará o download automaticamente ao final da geração da conta de serviço, que ficará disponível na pasta downloads do seu computador.

💡Verifique sua caixa de SPAM caso não encontre o e-mail para geração da conta de serviço.

Se precisar da chave pública, solicite ao gerente de projetos ou gere via OpenSSL:

openssl req -x509 -new -nodes -sha256 -days 720 \
-key fileName.key.pem -out fileName.cert.pem

Fluxo de Autenticação

Sua aplicação deve seguir 4 etapas:

1. Criar o JWT (cabeçalho + payload + assinatura).

2. Requisitar o token de acesso (access-token) na plataforma de autenticação.

3. Tratar a resposta (armazenar e usar o access-token nas chamadas de API).

4. Validade do token de acesso.

1. Criando o JWT

1.1 Estrutura

Um JWT possui 3 partes concatenadas por .:

{Header Base64url}.{Payload Base64url}.{Signature Base64url}

1.2 Cabeçalho

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

Base64url:

eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9

1.3 Payload

{
  "iss": "service_account_name@tenant_id.iam.acesso.io",
  "aud": "https://identityhomolog.acesso.io",
  "scope": "*",
  "iat": 1626293376,
  "exp": 1626296976
}

Campo	Descrição
iss	Identificador da conta de serviço (Service Account). O padrão é: nome da conta + @ + Tenant ID + iam.acesso.io. (ex: "service_account_name@tenant_id.iam.acesso.io").
scope	Permissões solicitadas. Use "*" para todas.
aud	Sempre https://identityhomolog.acesso.io (⚠️ sem barra no final e sempre com HTTPS).
iat	Momento da emissão do JWT, em segundos (no padrão Unix Timestamp).
exp	Expiração do token em segundos (máx. +3600s em relação ao iat). Este valor não pode ser fixo e tem um tempo máximo de 1 hora após o momento de emissão do JWT.

Exemplo de cálculo:

exp = iat + 3600

1.4 Assinatura

• Algoritmo: RS256 (RSA + SHA-256).

• Entrada: {Header Base64url}.{Payload Base64url}.

• Assinatura feita com a chave privada (.key.pem).

• Resultado final:

{Header Base64url}.{Payload Base64url}.{Signature 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]

2. Solicitando o Token de Acesso

Enviar o JWT assinado para a plataforma:

Endpoint POST:

• UAT: https://identityhomolog.acesso.io/oauth2/token;

• PROD: https://identity.acesso.io/oauth2/token.

Headers:

Content-Type: application/x-www-form-urlencoded

Body:

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.

grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<JWT_assinado>

Exemplo de requisição:

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

Exemplo de resposta da plataforma:

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

• Use o access_token em todas as chamadas às APIs da Unico.

• Caso retorne erro, valide:

  • JWT formado corretamente.

  • Tempo definido no iat e exp;

  • Conta de serviço com permissões necessárias.

4. Validade do Token de Acesso

• O tempo é informado em expires_in (segundos).

• Padrão: 3600s (1 hora).

• Renove o token quando faltar 10 minutos para expirar.

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)

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

• ¹ 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.