> 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/service-domain/guias/authentication.md).

# Autenticação

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

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

### Revisão

| Descrição                                                                                     | Data       | Versão | Classificação |
| --------------------------------------------------------------------------------------------- | ---------- | ------ | ------------- |
| Versão inicial                                                                                | 2026-09-01 | 1.0    | Uso Interno   |
| `client_credentials` como único grant suportado, regras de `username` / `workstation` e erros | 2026-10-14 | 1.1    | Uso Interno   |

***

| Campo                | Valor                                              |
| -------------------- | -------------------------------------------------- |
| Service Domain       | Authentication                                     |
| Operation            | Get Access Token                                   |
| Method               | POST                                               |
| API Name             | Nexus Security - Auth API                          |
| Versão               | v1.1.0                                             |
| Ambiente Documentado | Configurável por cliente e por ambiente (QA & PRD) |

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

A autenticação usa o protocolo **OAuth 2.0**, com o fluxo **Client Credentials** (M2M, machine to machine). **É o único fluxo suportado:** outros grant types não geram tokens válidos para as APIs Nexus.

O cliente integrador pede um `access_token` com o `client_id` e o `client_secret` atribuídos à sua aplicação, no `realm` do ambiente contratado. Pode também indicar o utilizador e a estação de trabalho de onde a operação é feita (`username`, `workstation`).

O acesso de cada aplicação às operações de negócio é configurado pela equipa Nexus Security. A aplicação não precisa de indicar nada sobre isso no pedido de token.

A operação:

* autentica a aplicação de negócio através do grant type `client_credentials`;
* devolve um `access_token` (JWT) de curta duração, que deve ser enviado como Bearer Token em todas as chamadas às APIs protegidas;
* devolve o tempo de expiração do token (`expires_in`), para o cliente o poder gerir e renovar antes de expirar.

| Campo                     | Valor                                                                                        |
| ------------------------- | -------------------------------------------------------------------------------------------- |
| API Name                  | Nexus Security - Auth API                                                                    |
| Versão                    | v1.1.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:** a documentação não fixa nenhum valor (host, realm, `client_id`, `client_secret`). Estes valores variam por cliente e por ambiente (QA & PRD) e são fornecidos pela equipa Nexus Security.

***

## 2. Visão Geral

Este documento descreve a integração das aplicações de negócio com o serviço de autenticação centralizado do Nexus. O serviço segue os padrões OAuth 2.0 e OpenID Connect (OIDC) e emite os Access Tokens usados para consumir as APIs de integração (Core e Middleware).

Serve de referência para os programadores das aplicações de negócio sobre:

* como obter um access token;
* que parâmetros enviar e como são tratados;
* como gerir o ciclo de vida do token (caching, expiração);
* como usar o token nas chamadas aos serviços de integração.

***

## 3. Endpoint de Autenticação

| Campo        | Valor                               |
| ------------ | ----------------------------------- |
| 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}}`          |

### 3.1 Parâmetros Obrigatórios

| Parâmetro       | Tipo   | Descrição                                                                                               |
| --------------- | ------ | ------------------------------------------------------------------------------------------------------- |
| `grant_type`    | String | Tem de ser sempre `client_credentials`. Outros grant types não geram tokens válidos para as APIs Nexus. |
| `client_id`     | String | Identificador único da aplicação de negócio.                                                            |
| `client_secret` | String | Credencial secreta da aplicação de negócio.                                                             |

### 3.2 Parâmetros Opcionais

| Parâmetro     | Tipo   | Descrição                                                                                                                                                         |
| ------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `username`    | String | Identificador/login do utilizador autenticado na aplicação de negócio. Se não for enviado, usa-se o utilizador técnico associado à aplicação, quando este existe. |
| `workstation` | String | Identificador da máquina, terminal ou estação de trabalho do utilizador. Se não for enviado, usa-se a estação de trabalho predefinida da aplicação.               |

> ⚠️ **Regras de validação**
>
> * O modelo de segurança exige rastreabilidade do utilizador final. Quando a aplicação está associada a um utilizador (enviado em `username` ou associado à aplicação), o token passa a identificar esse utilizador e a respetiva estação de trabalho.
> * Nesse caso, a estação de trabalho é **obrigatória**. Se a aplicação não tiver uma estação de trabalho predefinida e o pedido não enviar `workstation`, o pedido é recusado com `400 invalid_request`.
> * Os valores de `username` e `workstation` que vão no token são validados pelos serviços de integração nas chamadas seguintes.

### 3.3 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"
```

### 3.4 Resposta (Response)

Em caso de sucesso (HTTP 200 OK), o serviço devolve um JSON com 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"
}
```

| Campo                | Descrição                                                                               |
| -------------------- | --------------------------------------------------------------------------------------- |
| `access_token`       | Token JWT a enviar no header `Authorization: Bearer {token}`.                           |
| `expires_in`         | Validade do token, em segundos.                                                         |
| `refresh_expires_in` | Sempre `0`. Este fluxo não emite refresh token; quando o token expira, pede-se um novo. |
| `token_type`         | Sempre `Bearer`.                                                                        |
| `scope`              | Informativo; não requer tratamento pela aplicação.                                      |

#### Informação de negócio no token

Quando há um utilizador associado ao pedido, o `access_token` inclui:

| Claim           | Origem                                                                                           |
| --------------- | ------------------------------------------------------------------------------------------------ |
| `backbone_user` | O parâmetro `username`, ou, na ausência dele, o utilizador técnico associado à aplicação.        |
| `workstation`   | O parâmetro `workstation`, ou, na ausência dele, a estação de trabalho predefinida da aplicação. |

Se não houver utilizador associado (sem `username` e sem utilizador técnico configurado), o token é emitido sem estes campos.

### 3.5 Erros Comuns

| HTTP | `error`                                          | Causa                                                                                                                          |
| ---- | ------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------ |
| 401  | `invalid_client`                                 | `client_id` inexistente ou `client_secret` errado.                                                                             |
| 400  | `unsupported_grant_type` / `unauthorized_client` | Grant type diferente de `client_credentials`, desconhecido ou não ativo para a aplicação.                                      |
| 400  | `invalid_request`                                | Há um utilizador associado ao pedido, mas não foi enviado `workstation` e a aplicação não tem estação de trabalho predefinida. |

Os erros seguem o formato OAuth 2.0:

```json
{
  "error": "invalid_request",
  "error_description": "Missing workstation parameter and no default workstation configured"
}
```

***

## 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 cumprir as regras seguintes:

* **Isolamento por sessão:** quando a aplicação envia `username` e `workstation`, o token identifica esse utilizador. Cada utilizador com sessão na aplicação deve ter o seu próprio token, gerado e guardado no contexto da sua sessão. Nunca reutilize o token de um utilizador nas operações de outro.
* **Armazenamento e reutilização (caching):** guarde o token temporariamente (em memória ou na cache da sessão) e reutilize-o enquanto for válido. Não peça um token novo em cada requisição. Antes de chamar um serviço de integração, verifique a validade pelo `expires_in` e peça um token novo apenas quando o atual tiver expirado ou estiver a poucos segundos de expirar.
* **Proteção das credenciais:** o `client_secret` deve ficar guardado do lado do servidor (cofre de segredos ou configuração protegida). Nunca o exponha em frontends, logs ou repositórios de código.

***

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

Depois de obtido, o `access_token` deve ir no header `Authorization` de todas as chamadas HTTP aos serviços de integração (Core ou Middleware), com o esquema `Bearer`.

### Exemplo: requisição da aplicação para a API de negócio

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

> **Nota:** ao receber o pedido, o serviço em `{{Nexus-Core-API}}`:
>
> 1. valida o token (assinatura, emissor e validade);
> 2. confirma que a aplicação tem permissão para a operação pedida;
> 3. extrai o utilizador (`backbone_user`) e a estação de trabalho (`workstation`), quando existem;
> 4. aplica as políticas de autorização antes de processar a operação.

### Permissões e respostas de erro

As operações a que cada aplicação tem acesso são definidas pela equipa Nexus Security no onboarding da aplicação. A aplicação não tem de fazer nada no pedido de token para as obter.

| HTTP | Causa                                                 | Ação da aplicação                                      |
| ---- | ----------------------------------------------------- | ------------------------------------------------------ |
| 401  | Token em falta, expirado ou inválido.                 | Pedir um token novo e repetir a chamada.               |
| 403  | A aplicação não tem permissão para a operação pedida. | Contactar a equipa Nexus Security para pedir o acesso. |