> For the complete documentation index, see [llms.txt](https://selenium-4.gitbook.io/nexus-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://selenium-4.gitbook.io/nexus-docs/docs/guides/authentication.md).

# authentication

## Documentação Técnica de Integração

**OAuth2 · OpenID Connect · Client Credentials Grant**

### Revisão

| Descrição                                  | Data       | Versão | Classificação |
| ------------------------------------------ | ---------- | ------ | ------------- |
| Adicionada a tabela de estados dos cartões | 2026-09-01 | 1.0    | Uso Interno   |

***

| Campo                | Valor                                              |
| -------------------- | -------------------------------------------------- |
| Service Domain       | Authentication                                     |
| Operation            | Get Access Token                                   |
| Method               | POST                                               |
| API Name             | Nexus Security - Auth API                          |
| Versão               | v1.0.0                                             |
| Ambiente Documentado | Configurável via variáveis de ambiente por cliente |

## 1. Descrição da Operação

A autenticação é feita através do protocolo **OAuth 2.0**, utilizando o fluxo **Client Credentials** (M2M - machine to machine).

O cliente integrador deve solicitar um `access_token`, informando o `client_id` e `client_secret` atribuídos ao seu cliente, dentro do `realm` correspondente ao ambiente contratado. O token devolvido deve ser enviado em todos os pedidos subsequentes às APIs protegidas, no header `Authorization: Bearer {token}`.

A operação:

* Autentica o cliente integrador através do grant type `client_credentials`.
* Devolve um `access_token` de curta duração (JWT), a ser usado como Bearer Token nas chamadas às restantes APIs.
* Devolve também o tempo de expiração do token (`expires_in`), permitindo ao cliente geri-lo e renová-lo antecipadamente.

| Campo                     | Valor                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| API Name                  | Nexus Security - Auth API                                                                    |
| Versão                    | v1.0.0                                                                                       |
| Endpoint para Obter Token | `POST {{Nexus-Security-Auth}}/realms/{{Nexus-Security-Realm}}/protocol/openid-connect/token` |
| Autenticação              | OAuth 2.0 - Client Credentials Grant                                                         |

> **Nota:** Nenhum valor (host, realm, client\_id, client\_secret) será fixado na documentação, os valores variam por cliente e por ambiente (QA & PRD).

***

## 2. Visão Geral

Este documento detalha o processo de integração com o serviço de autenticação centralizado para aplicações de negócio. O serviço é baseado nos padrões OAuth 2.0 e OpenID Connect (OIDC), garantindo a emissão de Access Tokens seguros para o consumo de APIs e serviços de integração subsequentes.

O objectivo é fornecer aos programadores das aplicações de negócio uma referência clara sobre:

* Como obter tokens de acesso (access tokens)
* Como gerir o ciclo de vida dos tokens (caching, expiração)
* Como utilizar os tokens nas chamadas aos serviços de integração posteriores
* Quais os campos personalizados disponíveis e as suas implicações

***

## 3. Endpoint de Autenticação

A obtenção do token de acesso é feita através do endpoint de token do realm configurado para o cliente.

* **Host:** `{{Nexus-Security-Auth}}`
* **Protocolo:** `https`
* **Método HTTP:** `POST`
* **Content-Type:** `application/x-www-form-urlencoded`
* **Grant Type:** `client_credentials`
* **Realm:** `{{Nexus-Security-Realm}}`

### Parâmetros da Requisição (Request)

Para as aplicações de negócio operarem neste fluxo, o tipo de concessão (Grant Type) utilizado é exclusivamente o `client_credentials`.

#### Parâmetros Obrigatórios (Padrão OAuth 2.0)

| Parâmetro       | Tipo   | Descrição                                          |
| --------------- | ------ | -------------------------------------------------- |
| `grant_type`    | String | Deve ser sempre `client_credentials`.              |
| `client_id`     | String | O identificador único da sua aplicação de negócio. |
| `client_secret` | String | A credencial de segurança da sua aplicação.        |

#### Parâmetros Personalizados (Específicos do Ambiente)

> ⚠️ **Atenção - Regra de Validação Rigorosa**
>
> Embora o fluxo seja `client_credentials` (focado na aplicação), o modelo de segurança exige rastreabilidade das ações do utilizador final. Os campos abaixo são opcionais na chamada ao serviço de autenticação, mas se enviados, serão rigorosamente validados pelos serviços de integração nas chamadas subsequentes.

| Parâmetro     | Tipo   | Descrição                                                                                                  |
| ------------- | ------ | ---------------------------------------------------------------------------------------------------------- |
| `username`    | String | (Opcional) O identificador/login do utilizador que está autenticado na aplicação de negócio.               |
| `workstation` | String | (Opcional) O identificador da máquina, terminal ou estação de trabalho de onde o utilizador está a operar. |

### Exemplo de Requisição (cURL)

```bash
curl -X POST https://{{Nexus-Security-Auth}}/realms/{{Nexus-Security-Realm}}/protocol/openid-connect/token \
  -H "Content-Type: application/x-www-form-urlencoded" \
  -d "grant_type=client_credentials" \
  -d "client_id=application_id" \
  -d "client_secret=******" \
  -d "username=saco003" \
  -d "workstation=WSLDN045"
```

### Resposta (Response)

Em caso de sucesso (HTTP 200 OK), o serviço retornará um payload JSON contendo o token de acesso.

```json
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCIg...",
  "expires_in": 300,
  "refresh_expires_in": 0,
  "token_type": "Bearer",
  "not-before-policy": 0,
  "scope": "profile email"
}
```

***

## 4. Boas Práticas e Ciclo de Vida do Token (Requisitos Obrigatórios)

Para garantir a performance da rede e a segurança do ecossistema, as aplicações de negócio devem implementar as seguintes regras de gestão de estado e sessão:

* **Isolamento por Sessão:** O Access Token deve ser gerado e mantido no contexto de cada utilizador logado na aplicação. Não utilize o mesmo token globalmente para toda a aplicação de negócio se estiver a repassar o `username` e a `workstation`.
* **Armazenamento e Reutilização (Caching):** É estritamente recomendado armazenar o token temporariamente (em memória ou cache da sessão). Não gere um novo token a cada requisição. Antes de chamar um serviço de integração, verifique se o token atual ainda é válido (observando o tempo de vida retornado no campo `expires_in`). Só solicite um novo token quando o atual expirar ou estiver a segundos de expirar.

***

## 5. Utilização em Serviços de Integração (Downstream)

Todas as aplicações de negócio utilizam o grant type `client_credentials`. Neste fluxo, a aplicação autentica-se directamente com as suas próprias credenciais (sem redireccionamento de utilizador), adequado para comunicação máquina-a-máquina (M2M).

Uma vez obtido, o `access_token` deve ser injetado no cabeçalho `Authorization` de todas as chamadas HTTP direcionadas aos serviços de integração (Core ou Middleware). O esquema de autenticação a ser utilizado é o `Bearer`.

### Exemplo de Uso: Requisição da Aplicação para a API de Negócio

```http
GET /v1/term-deposits/TD-987654321/retrieve HTTP/1.1
Host: {{Nexus-Core-API}}
Authorization: Bearer eyJhbGciOiJSUzI1NiIsInR5cCIg...
Accept: application/json
```

> **Nota:** Ao receber esta requisição, o serviço em `{{Nexus-Core-API}}` irá interceptar o token de acesso, extrair as informações (incluindo as personalizadas como `username` e `workstation` se foram injetadas no momento da geração) e aplicar as políticas de autorização necessárias antes de processar a operação.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## 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 following URL with the `ask` and `goal` query parameters:

```
GET https://selenium-4.gitbook.io/nexus-docs/docs/guides/authentication.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `build a script that syncs our docs to a CMS` lets GitBook tailor the answer to that use case.

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.