> 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/documentation/guias/readme.md). # Autenticação | 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. Cabeçalhos HTTP | Header | Obrigatório | Notas | | ------------------------------------------------- | ----------- | ------------------------------------------------------------------------------- | | `Content-Type: application/x-www-form-urlencoded` | Sim | Corpo do pedido enviado como form-urlencoded, conforme especificação OAuth 2.0. | | `Accept: application/json` | Sim | - | ### 3. Variáveis Utilizadas Os valores abaixo não são path variables da API — são variáveis de ambiente/colecção, substituídas na URL do pedido antes do envio. | Variável | Obrigatório | Descrição | | -------------------------- | ----------- | ---------------------------------------------------------------------- | | `{{Nexus-Security-Auth}}` | Sim | Base URL do servidor de autenticação, específica por ambiente/cliente. | | `{{Nexus-Security-Realm}}` | Sim | Nome do realm associado ao cliente/ambiente. | ### 4. Payload de Pedido (Request - form-urlencoded) ``` grant_type=client_credentials client_id={{Nexus-Security-ClientID}} client_secret={{Nexus-Security-ClientSecret}} ``` | Campo | Tipo | Obrigatório | Descrição | | --------------- | ------ | ----------- | ------------------------------------------------------------------------------------------------ | | `grant_type` | string | Sim | Fixo: `client_credentials`. | | `client_id` | string | Sim | Identificador do cliente. Gerido via variável de ambiente. | | `client_secret` | string | Sim | Segredo do cliente. Gerido via variável de ambiente/secret, nunca em texto plano no repositório. | | `workstation` | string | Não | Identificador da estação/origem do pedido. | | `username` | string | Não | Utilizador final. | | `password` | string | Não | Password do utilizador final. | ### 5. Payload de Resposta (Response 200) ```json { "access_token": "string", "expires_in": 0, "refresh_expires_in": 0, "token_type": "Bearer", "not-before-policy": 0, "scope": "string" } ``` | Campo | Tipo | Descrição | | -------------------- | ------------ | ----------------------------------------------------------------------------- | | `access_token` | string (JWT) | Token de acesso a utilizar como Bearer Token nas chamadas às APIs protegidas. | | `expires_in` | integer | Tempo de vida do `access_token`, em segundos. | | `refresh_expires_in` | integer | Tempo de vida associado a renovação, quando aplicável ao grant type. | | `token_type` | string | Tipo do token. Fixo: `Bearer`. | | `not-before-policy` | integer | Política de validade mínima definida no servidor de autenticação. | | `scope` | string | Scopes associados ao token emitido. | ### 6. Uso do Token nas Chamadas Subsequentes Após obtido, o `access_token` deve ser enviado no header `Authorization` de todos os pedidos às APIs protegidas: ``` Authorization: Bearer {{access_token}} ``` ### 7. Códigos HTTP de Resposta | Código | Estado | Descrição | | ------ | --------------------- | ----------------------------------------------- | | 200 | OK | Token emitido com sucesso. | | 400 | Bad Request | Parâmetros em falta ou grant\_type inválido. | | 401 | Unauthorized | `client_id` ou `client_secret` inválidos. | | 403 | Forbidden | Cliente desactivado ou sem permissões no realm. | | 404 | Not Found | `realm` informado não existe. | | 500 | Internal Server Error | Erro inesperado no servidor de autenticação. | ### 8. Regras de Negócio | # | Regra | Detalhe | | - | -------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | 1 | Renovação de Token | O cliente integrador deve renovar o `access_token` antes do fim de `expires_in`, evitando pedidos com token expirado (401). | | 2 | Segredo do Cliente | `client_secret` nunca deve ser exposto em logs, repositórios de código ou documentação - apenas em variáveis de ambiente/secret manager. | | 3 | Isolamento por Realm | Cada cliente/ambiente opera dentro do seu próprio `realm`, não sendo possível usar credenciais de um realm noutro. | ### 9. Requisitos Não-Funcionais | Requisito | Detalhe | | ---------------------------- | ---------------------------------------------------------------------------------------------------------------- | | HTTPS / TLS | Obrigatório TLS 1.2 ou superior em todas as comunicações. | | Armazenamento de Credenciais | `client_id` e `client_secret` geridos via variáveis de ambiente por cliente, nunca em texto plano versionado. | | Auditoria | Registo persistente de emissões de token (log estruturado), sem registar o valor do token ou do `client_secret`. | | Configuração por Ambiente | `Nexus-Security-Auth` e `Nexus-Security-Realm` geridos via variáveis de ambiente por cliente/ambiente. | --- # 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 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/documentation/guias/readme.md?ask=&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 `automate deployments from our CI pipeline` 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.