Token exchange
O agente troca o token do sujeito por um token Xokepoint curto, que carrega o sujeito e o agente.
Esta página é o modo headless. No modo interativo, um harness de código obtém o mesmo tipo de token por um login authorization code e um refresh token (Conectar um harness de código); a tabela do token abaixo vale para os dois modos.
O agente nunca chama tools com o token que o IdP emitiu para o usuário. Ele leva esse token ao authorization server (AS) do Xokepoint e o troca por outro, emitido pelo Xokepoint, que carrega o sujeito e o agente. A troca segue o OAuth 2.0 Token Exchange (RFC 8693).
Três verificações acontecem antes de qualquer token sair: o agente é quem diz ser (client assertion com private_key_jwt), o token do usuário é válido (a mesma identity connection que o PEP usa) e o usuário delegou para esse agente (OpenFGA). Se qualquer uma falha, o AS responde com um erro do RFC 6749 §5.2 e não emite nada. O error_description traz só o código Reference da recusa, nunca o motivo (Quick incident). Se a instância pediu limites, o AS também confere o formato e se o agente pode chamar cada tool; se não, responde invalid_authorization_details.
O token emitido
O token segue o perfil de JWT access token do RFC 9068:
| Claim | Valor |
|---|---|
header typ | at+jwt, assinado com ES256 |
iss | O AS do Xokepoint, um issuer por workspace e ambiente: <origin>/as/<workspace>/<ambiente> |
aud | O ingress MCP desse ambiente: <origin>/api/v1/mcp/<workspace>/<ambiente> |
sub | O sujeito |
act.sub | O agente |
chokepoint_subject | A identity connection e o tipo (person ou service) do sujeito, e presence: headless num token exchange, interactive num harness login |
chokepoint_subject.grant_id | Só no interativo: o grant da máquina que entrou, para que uma máquina possa ser revogada sozinha |
cnf.jkt | Só no interativo, quando o harness usou DPoP: o thumbprint da chave dele (RFC 9449) |
exp | No máximo 5 minutos, nunca depois do fim da delegação ou do consentimento |
authorization_details | Os limites da instância, quando ela pediu (RFC 9396) |
A audience é o ingress de um ambiente, não "o Xokepoint" em geral. Então um token emitido para staging é recusado em produção antes mesmo de a assinatura ser conferida.
Instâncias do mesmo agente rodam ao mesmo tempo, e cada uma faz a sua troca. Uma instância pode pedir os próprios limites, por exemplo max_amount = 100 em refund_payment. Eles só estreitam o acesso, e o token assinado impede que sejam adulterados. Limites da instância cobre o formato, as regras e como uma condição de chamada os lê.
A vida curta é uma decisão de design, não uma limitação. O Xokepoint não sincroniza o ciclo de vida dos usuários com o IdP. Um usuário desabilitado no IdP não consegue um novo token, então a próxima troca falha e o agente fica sem token em poucos minutos. No modo interativo, o refresh não passa pelo IdP, então valem outros limites. Revogação detalha os dois caminhos.
O que a troca não aceita
O modo headless usa um grant: a token exchange do RFC 8693, autenticada com private_key_jwt. Os grants interativos (authorization_code e refresh_token) são para harnesses e usam uma URL de client metadata em vez de chave. Alguns parâmetros padrão do grant de token exchange são recusados de propósito, e uma integração que os envia recebe um erro em vez de um token diferente sem aviso:
| Parâmetro | Resposta | Por quê |
|---|---|---|
actor_token, actor_token_type | invalid_request | A delegação provada pelo IdP (Entra On-Behalf-Of, Okta Cross App Access com um ID-JAG, o claim act no Keycloak) ainda não é suportada. O agente sempre se prova com a própria chave. |
audience, resource | invalid_target | O token é sempre para o ingress MCP do ambiente. Os tokens para servidores do cliente são emitidos pelo próprio Xokepoint depois do ALLOW (Autenticação upstream). |
scope | invalid_scope | O acesso é decidido por relações e regras em cada chamada, não por scopes no token (Por que ReBAC). |
Quando a delegação provada pelo IdP chegar, a conferência no OpenFGA continua valendo: o IdP prova que a pessoa delegou, e o Xokepoint ainda decide se essa delegação é permitida pela política do cliente.
O AS publica os metadados (RFC 8414) em <origin>/.well-known/oauth-authorization-server/as/<workspace>/<ambiente>, com o token endpoint, a URI do JWKS e authorization_details_types_supported. Para o modo interativo, ele acrescenta o authorization endpoint (<issuer>/authorize), os grants authorization_code e refresh_token, code_challenge_methods_supported: ["S256"], client_id_metadata_document_supported: true e dpop_signing_alg_values_supported.