# Registo dinâmico de clientes

As aplicações cliente registam-se a si próprias via OAuth 2.0 Dynamic Client Registration, com Initial Access Tokens.

> **Nota:** Disponível com as subscrições Advanced e Pro. O registo aberto para agentes de IA requer Pro.

Com o **registo dinâmico de clientes**, uma aplicação cliente regista-se a si própria em vez de ser criada manualmente na Admin Console. Envia os seus metadados (nome, URIs de redirecionamento, autenticação do cliente) para o endpoint de registo e recebe em troca um ID de cliente e, no caso de clientes confidenciais, um client secret. A plataforma implementa o OAuth 2.0 Dynamic Client Registration ([RFC 7591](https://www.rfc-editor.org/rfc/rfc7591)) e o protocolo de gestão que permite ao cliente ler, alterar e eliminar posteriormente o seu próprio registo ([RFC 7592](https://www.rfc-editor.org/rfc/rfc7592)).

Por predefinição, cada registo requer um **Initial Access Token** emitido por si, pelo que é o administrador quem decide quem pode registar clientes e com que frequência. Para agentes de IA e outros clientes públicos, pode adicionalmente permitir o [registo aberto](#open-registration-for-ai-agents).

Os Initial Access Tokens são geridos na Admin Console em **Integrações → Aplicações → Registos dinâmicos**.

## Funcionamento

1. Emite um **Initial Access Token** e entrega-o à entidade que regista o cliente, por exemplo um parceiro ou um pipeline de implementação.
2. O cliente envia um pedido de registo para o endpoint de registo, com o Initial Access Token como Bearer token.
3. A plataforma verifica os metadados de acordo com as regras abaixo, cria a aplicação e responde com as credenciais do cliente, um **Registration Access Token** e o URL de gestão próprio do cliente.
4. Com o Registration Access Token, o cliente pode ler, alterar ou eliminar o seu registo. Cada alteração emite um novo Registration Access Token e invalida o anterior.

O cliente registado é apresentado no separador **Registos dinâmicos** em **Aplicações registadas**, juntamente com a forma como se registou e a data da última utilização. A sua página de detalhe é igual à de qualquer outra aplicação, assinalada como **Registada dinamicamente**. Ainda ninguém consegue iniciar sessão nela: tal como em qualquer nova aplicação, o acesso tem primeiro de ser [atribuído](https://dts-identity.com/pt/docs/integrations/applications.md#assigning-applications-to-users).

## Emitir um Initial Access Token

1. Aceda a **Integrações → Aplicações** e abra o separador **Registos dinâmicos**.
2. Selecione **Emitir token**.
3. Introduza um **Nome**, por exemplo o parceiro ou o sistema a que o token se destina. O nome aparece na lista e no registo de auditoria.
4. Defina a **Validade em dias** (1 a 365). O token expira após este período.
5. Mantenha **Utilização única** selecionado se o token deve permitir exatamente um registo. Desmarque a opção para permitir um número ilimitado de registos até o token expirar.
6. Selecione **Emitir token** e copie o token. É apresentado apenas uma vez e não pode ser obtido posteriormente.

A página mostra também o **Endpoint de registo**, que deve ser transmitido juntamente com o token. É igualmente publicado como `registration_endpoint` no documento de discovery do OpenID Connect.

A lista mostra, para cada token, o tipo de utilização, o número de registos efetuados com ele, a data de expiração e quem o emitiu. **Revogar** impede que um token seja utilizado para novos registos. As aplicações já registadas com ele não são afetadas. Os tokens expirados são removidos automaticamente.

## Registo aberto para agentes de IA [#open-registration-for-ai-agents]

> **Nota:** Disponível com a subscrição Pro.

Os agentes de IA, por exemplo clientes do Model Context Protocol (MCP), e as ferramentas de linha de comandos registam-se a si próprios no momento em que um utilizador os liga, sem que ninguém entregue um token. Normalmente, cada instalação regista o seu próprio cliente. O registo aberto permite exatamente isso para **clientes públicos**, que não têm client secret e autenticam os utilizadores com o fluxo authorization code e PKCE.

1. Aceda a **Definições → Avançado**.
2. No cartão **Registo aberto**, ative **Registo aberto para clientes públicos**.
3. Em **Utilizadores que podem iniciar sessão**, selecione os diretórios cujos utilizadores podem utilizar esses clientes.
4. Selecione **Guardar alterações**.

Para clientes registados de forma aberta aplica-se o seguinte:

- **Apenas são aceites clientes públicos.** Um registo sem Initial Access Token tem de enviar `"token_endpoint_auth_method": "none"`, e o cliente permanece público: uma alteração posterior não pode adicionar um client secret. Os clientes confidenciais continuam a precisar de um Initial Access Token.
- **O acesso resulta dos diretórios.** Os utilizadores dos diretórios selecionados podem iniciar sessão depois de darem o seu consentimento, sem atribuição por aplicação. A seleção aplica-se a novos registos; as aplicações já registadas mantêm os diretórios com que foram registadas.
- **Os registos têm limitação de taxa** de 10 por hora por endereço IP do cliente e 200 por hora no total (20 durante o período experimental).
- **Os registos não utilizados são removidos.** Um cliente em que ninguém iniciou sessão é eliminado após 24 horas, e um cliente sem inícios de sessão nem pedidos de token durante 90 dias também. Cada remoção fica registada no registo de auditoria.
- **Não existe proprietário.** As aplicações registadas de forma aberta não estão associadas a nenhum administrador.

O endpoint de registo é anunciado no documento de discovery, disponibilizado em `/.well-known/openid-configuration` e, para clientes OAuth que o procuram aí, em `/.well-known/oauth-authorization-server`. Se um agente pedir um access token para um recurso específico, como um servidor MCP, registe esse recurso como [API](https://dts-identity.com/pt/docs/integrations/apis.md).

Desativar o registo aberto impede novos registos anónimos. Os clientes já registados continuam a funcionar e podem continuar a gerir o seu registo. Sem a subscrição Pro, os utilizadores dos diretórios deixam de obter automaticamente acesso aos clientes registados de forma aberta: atribua-os explicitamente, caso contrário os clientes não utilizados são removidos após 90 dias.

## Registar um cliente

O cliente envia os seus metadados como pedido `POST` em JSON:

```bash
curl -X POST https://id.example.com/oidc/register \
  -H "Authorization: Bearer <initial access token>" \
  -H "Content-Type: application/json" \
  -d '{
    "client_name": "Partner Portal",
    "redirect_uris": ["https://portal.partner.example/callback"],
    "post_logout_redirect_uris": ["https://portal.partner.example/"],
    "grant_types": ["authorization_code", "refresh_token"],
    "token_endpoint_auth_method": "client_secret_basic"
  }'
```

Um registo bem-sucedido responde com `201 Created`:

```json
{
  "client_id": "V1StGXR8_Z5jdHi6B-myT",
  "client_secret": "...",
  "client_name": "Partner Portal",
  "redirect_uris": ["https://portal.partner.example/callback"],
  "grant_types": ["authorization_code", "refresh_token"],
  "response_types": ["code"],
  "token_endpoint_auth_method": "client_secret_basic",
  "registration_client_uri": "https://id.example.com/oidc/register/V1StGXR8_Z5jdHi6B-myT",
  "registration_access_token": "..."
}
```

O cliente guarda `client_secret` e `registration_access_token` em segurança. Nenhum dos dois pode ser obtido novamente.

## Gerir o registo

O cliente gere o seu registo em `registration_client_uri`, autenticado com o seu Registration Access Token atual:

| Pedido | Efeito |
|---|---|
| `GET` | Devolve o registo atual. |
| `PUT` | Substitui o registo pelos metadados enviados. O corpo tem de conter `client_id`; um campo omitido é removido. A resposta contém um novo Registration Access Token. |
| `DELETE` | Elimina a aplicação. Os seus utilizadores deixam de poder iniciar sessão nela. |

Um administrador pode editar ou eliminar uma aplicação registada dinamicamente na Admin Console como qualquer outra. Tenha em conta que o `PUT` seguinte do cliente substitui os campos que lhe pertencem (nome, URIs de redirecionamento, grant types, autenticação do cliente, URI do cliente e chaves do cliente). As atribuições, políticas, proprietários e a definição de consentimento mantêm-se tal como o administrador as definiu.

## O que um cliente registado pode ser

| Metadados | Regra |
|---|---|
| `token_endpoint_auth_method` | `client_secret_basic` (predefinição), `client_secret_post`, `private_key_jwt` ou `none`. |
| Tipo de aplicação | Resulta da autenticação do cliente: `none` cria uma aplicação de página única, ou uma aplicação nativa quando é enviado `"application_type": "native"` ou quando cada URI de redirecionamento é um endereço de loopback (`http://127.0.0.1`, `http://[::1]`, `http://localhost`) ou um esquema próprio da aplicação. Um redirecionamento de loopback nativo corresponde a qualquer porta. Qualquer outro método cria uma aplicação web. Um cliente nativo tem de utilizar `none`. |
| `grant_types` | Tem de conter `authorization_code` e pode acrescentar `refresh_token`. Os grants implicit, client credentials, device e token exchange são rejeitados. |
| `response_types` | Apenas `code`. |
| `redirect_uris`, `post_logout_redirect_uris` | Sem wildcards, sem URIs no próprio domínio do fornecedor de identidade. |
| `client_uri` | Tem de utilizar `https`. |
| `jwks` | Apenas chaves públicas, RSA com pelo menos 2048 bits ou EC na curva P-256. Necessário para `private_key_jwt`. |
| `jwks_uri`, `sector_identifier_uri`, `backchannel_logout_uri`, `request_uris` | Rejeitados, porque a própria plataforma teria de chamar estes URLs. Um administrador pode definir posteriormente as opções correspondentes na aplicação. |
| `client_name` | Opcional. Sem nome, a aplicação chama-se "Dynamic client" seguido do seu ID de cliente. A um nome já utilizado é acrescentada uma parte do ID de cliente. |
| `default_max_age` | Aceite. |

Quaisquer outros metadados são ignorados e não fazem parte da resposta.

Algumas definições são sempre decididas pela plataforma, independentemente do conteúdo do pedido:

- **Exigir consentimento do utilizador** está ativado. Os utilizadores confirmam o acesso pedido no primeiro início de sessão, e os refresh tokens só são emitidos quando o cliente pede o scope `offline_access`.
- Não é aplicado nenhum perfil de segurança. Um administrador pode definir um posteriormente, consulte [Financial-grade API security](https://dts-identity.com/pt/docs/integrations/applications.md#financial-grade-api-security).
- A aplicação não é apresentada no portal de aplicações dos utilizadores.
- O administrador que emitiu o Initial Access Token torna-se proprietário da aplicação. As aplicações registadas de forma aberta não têm proprietário.

Os registos contam para o limite de aplicações da sua subscrição.

## Registo de auditoria

| Evento | Registado quando |
|---|---|
| `INITIAL_ACCESS_TOKEN_CREATED` | Um administrador emite um Initial Access Token. |
| `INITIAL_ACCESS_TOKEN_REVOKED` | Um administrador revoga um Initial Access Token. |
| `CONFIGURATION_UPDATED` | Um administrador ativa ou desativa o registo aberto ou altera os respetivos diretórios. |
| `APPLICATION_REGISTERED` | Um cliente regista-se. O cliente que efetua o registo é registado como ator. |
| `APPLICATION_UPDATED` | Um cliente altera o seu registo. |
| `APPLICATION_DEREGISTERED` | Um cliente elimina o seu registo, um administrador elimina a aplicação ou um registo aberto não utilizado é removido. |

A lista completa encontra-se em [Tipos de eventos de auditoria](https://dts-identity.com/pt/docs/reference/audit-event-types.md).

## Resolução de problemas

- **`invalid_token` no registo:** o Initial Access Token é desconhecido, expirou, foi revogado, ou um token de utilização única já foi utilizado. Emita um novo. Sem token, o registo aberto está desativado.
- **`429` num registo anónimo:** foi atingido o limite de taxa do registo aberto. Tente novamente mais tarde.
- **`invalid_token` ao ler, alterar ou eliminar:** o Registration Access Token foi substituído por um mais recente na última alteração, ou a aplicação foi eliminada.
- **`invalid_client_metadata` com "dynamic client registration is not available":** a subscrição não inclui a funcionalidade. Os registos e as alterações são rejeitados; a leitura e a eliminação de um registo existente continuam a funcionar.
- **`invalid_client_metadata`:** os metadados violam uma das regras acima. O `error_description` indica o campo. Um pedido rejeitado não consome um token de utilização única.
- **Os utilizadores não conseguem iniciar sessão após o registo:** a aplicação ainda não tem atribuições. Atribua utilizadores, grupos ou diretórios no separador **Atribuições** da aplicação. No caso de um cliente registado de forma aberta, verifique se o utilizador pertence a um dos seus diretórios.

## Consulte também

- [Aplicações](https://dts-identity.com/pt/docs/integrations/applications.md)
- [APIs](https://dts-identity.com/pt/docs/integrations/apis.md)
- [Tipos de eventos de auditoria](https://dts-identity.com/pt/docs/reference/audit-event-types.md)
