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) e o protocolo de gestão que permite ao cliente ler, alterar e eliminar posteriormente o seu próprio registo (RFC 7592).
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.
Os Initial Access Tokens são geridos na Admin Console em Integrações → Aplicações → Registos dinâmicos.
Funcionamento
- Emite um Initial Access Token e entrega-o à entidade que regista o cliente, por exemplo um parceiro ou um pipeline de implementação.
- O cliente envia um pedido de registo para o endpoint de registo, com o Initial Access Token como Bearer token.
- 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.
- 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.
Emitir um Initial Access Token
- Aceda a Integrações → Aplicações e abra o separador Registos dinâmicos.
- Selecione Emitir token.
- 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.
- Defina a Validade em dias (1 a 365). O token expira após este período.
- 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.
- 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
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.
- Aceda a Definições → Avançado.
- No cartão Registo aberto, ative Registo aberto para clientes públicos.
- Em Utilizadores que podem iniciar sessão, selecione os diretórios cujos utilizadores podem utilizar esses clientes.
- 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.
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:
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:
{
"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.
- 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.
Resolução de problemas
invalid_tokenno 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.429num registo anónimo: foi atingido o limite de taxa do registo aberto. Tente novamente mais tarde.invalid_tokenao 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_metadatacom "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. Oerror_descriptionindica 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.