# 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 <a href="#solicitacao-da-conta-de-servico" id="solicitacao-da-conta-de-servico"></a>

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.
  * O celular deve ser Brasileiro, Americano ou Mexicano.

{% hint style="warning" %}
Homologação e Produção requerem contas distintas.
{% endhint %}

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.*

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

{% hint style="success" %}
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
```

{% endhint %}

## Fluxo de Autenticação <a href="#fluxo-de-autenticacao" id="fluxo-de-autenticacao"></a>

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 <a href="#criando-o-jwt" id="criando-o-jwt"></a>

#### 1.1 Estrutura

Um JWT possui 3 partes concatenadas por `.`:

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

#### 1.2 Cabeçalho

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

Base64url:

```
eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9
```

#### 1.3 Payload&#x20;

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

<table><thead><tr><th width="172.6666259765625">Campo</th><th>Descrição</th></tr></thead><tbody><tr><td><code>iss</code></td><td>Identificador da conta de serviço (<em>Service Account</em>). O padrão é: <code>nome da conta</code> + <code>@</code> + <code>Tenant ID</code> + <code>iam.acesso.io</code>. (<em>ex:</em> <em>"<code>service_account_name@tenant_id.iam.acesso.io</code>"</em>).</td></tr><tr><td><code>scope</code></td><td>Permissões solicitadas. Use <code>"*"</code> para todas.</td></tr><tr><td><code>aud</code></td><td>Sempre <code>https://identityhomolog.acesso.io</code> (<em>⚠️ sem barra no final</em> e <em>sempre com HTTPS</em>).</td></tr><tr><td><code>iat</code></td><td>Momento da emissão do JWT, em <strong>segundos</strong> (<em>no padrão Unix Timestamp</em>).</td></tr><tr><td><code>exp</code></td><td>Expiração do token em <strong>segundos</strong> (<em>máx. +3600s em relação ao <code>iat</code></em>). 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.</td></tr></tbody></table>

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:

```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]
```

### 2. Solicitando o Token de Acesso <a href="#solicitando-o-token-de-acesso" id="solicitando-o-token-de-acesso"></a>

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:**

<table><thead><tr><th width="160.666748046875">Nome</th><th>Descrição</th></tr></thead><tbody><tr><td>grant_type</td><td>Utilize o seguinte texto, URL-encoded se necessário: <strong>urn:ietf:params:oauth:grant-type:jwt-bearer.</strong></td></tr><tr><td>assertion</td><td>O JWT, incluindo a assinatura.</td></tr></tbody></table>

```x-www-form-urlencoded
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer
assertion=<JWT_assinado>
```

Exemplo de requisição:

```http
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 <a href="#tratando-a-resposta" id="tratando-a-resposta"></a>

Exemplo de resposta da plataforma:

```json
{
  "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 <a href="#validade-do-token-de-acesso" id="validade-do-token-de-acesso"></a>

* 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)
```

{% hint style="warning" %}
Um novo token de acesso pode ser solicitado quando faltar 10 minutos pra expirar.
{% endhint %}

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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://devcenter.unico.io/unico-idcloud/by-client-integration/pt/autenticacao/obtendo-credenciais.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.