79| Campo | Obrigatório | Descrição |79| Campo | Obrigatório | Descrição |
80| - | - | - |80| - | - | - |
81| `issuer` | Sim | Base de descoberta OIDC. Deve servir descoberta em `/.well-known/openid-configuration`. Use HTTPS em produção; o gateway aceita um emissor `http://`. Um emissor de loopback como `http://localhost:8081` é rejeitado pela [proteção SSRF](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esteja definido no ambiente do gateway. |81| `issuer` | Sim | Base de descoberta OIDC. Deve servir descoberta em `/.well-known/openid-configuration`. Use HTTPS em produção; o gateway aceita um emissor `http://`. Um emissor de loopback como `http://localhost:8081` é rejeitado pela [proteção SSRF](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) a menos que `CLAUDE_GATEWAY_ALLOW_LOOPBACK=1` esteja definido no ambiente do gateway. |
82| `client_id` / `client_secret` | Sim | Do seu registro de cliente OAuth |82| `client_id` | Sim | Do seu registro de cliente OAuth |
83| `client_secret` | A menos que `token_endpoint_auth_method` seja `private_key_jwt` | Do seu registro de cliente OAuth. Omita-o quando você usar [autenticação de cliente por certificado](#certificate-client-authentication). |
83| `allowed_email_domains` | Não | Rejeite id\_tokens cuja declaração `email` não esteja em um desses domínios, insensível a maiúsculas/minúsculas. Defesa em profundidade contra configuração incorreta de IdP multi-tenant. Independentemente dessa configuração, um id\_token cuja declaração `email_verified` é explicitamente `false` é sempre rejeitado. |84| `allowed_email_domains` | Não | Rejeite id\_tokens cuja declaração `email` não esteja em um desses domínios, insensível a maiúsculas/minúsculas. Defesa em profundidade contra configuração incorreta de IdP multi-tenant. Independentemente dessa configuração, um id\_token cuja declaração `email_verified` é explicitamente `false` é sempre rejeitado. |
84| `allowed_groups` | Não | Restrinja o login a membros desses grupos IdP, comparados com `groups_claim`. Um usuário em um domínio de email permitido mas em nenhum desses grupos é rejeitado. Requer que o IdP emita a declaração de grupos. A correspondência é uma comparação de string exata e sensível a maiúsculas/minúsculas contra os valores nessa declaração, e o gateway não expande grupos aninhados: para admitir membros de um subgrupo, liste o subgrupo aqui ou configure o IdP para emitir associação achatada. |85| `allowed_groups` | Não | Restrinja o login a membros desses grupos IdP, comparados com `groups_claim`. Um usuário em um domínio de email permitido mas em nenhum desses grupos é rejeitado. Requer que o IdP emita a declaração de grupos. A correspondência é uma comparação de string exata e sensível a maiúsculas/minúsculas contra os valores nessa declaração, e o gateway não expande grupos aninhados: para admitir membros de um subgrupo, liste o subgrupo aqui ou configure o IdP para emitir associação achatada. |
85| `groups_claim` | Não | Qual declaração id\_token carrega associação de grupo. Padrão `groups`. Microsoft Entra emite funções de aplicativo sob `roles`. Aceita uma chave simples ou um JSON Pointer RFC 6901 como `/resource_access/gateway/roles` para declarações aninhadas. |86| `groups_claim` | Não | Qual declaração id\_token carrega associação de grupo. Padrão `groups`. Microsoft Entra emite funções de aplicativo sob `roles`. Aceita uma chave simples ou um JSON Pointer RFC 6901 como `/resource_access/gateway/roles` para declarações aninhadas. |
91| `userinfo_fallback` | Não | Quando o id\_token omite email ou grupos, busque-os em `/userinfo`. Necessário para tokens de acesso leve do Keycloak, o servidor org do Okta e tokens mínimos do ADFS. O id\_token permanece autoritário; userinfo apenas preenche lacunas. Padrão `false`. |92| `userinfo_fallback` | Não | Quando o id\_token omite email ou grupos, busque-os em `/userinfo`. Necessário para tokens de acesso leve do Keycloak, o servidor org do Okta e tokens mínimos do ADFS. O id\_token permanece autoritário; userinfo apenas preenche lacunas. Padrão `false`. |
92| `use_pkce` | Não | Envie um desafio PKCE (S256) na solicitação de autorização. Padrão `true`. Defina `false` apenas se seu IdP rejeitar PKCE para este cliente confidencial. |93| `use_pkce` | Não | Envie um desafio PKCE (S256) na solicitação de autorização. Padrão `true`. Defina `false` apenas se seu IdP rejeitar PKCE para este cliente confidencial. |
93| `clock_skew_seconds` | Não | Tolere desvio de relógio ao validar declarações de tempo id\_token. Padrão `0`, que é rigoroso. Aumente se você vir erros "token expirado / ainda não válido" logo após o login devido a desvio de relógio host/IdP. |94| `clock_skew_seconds` | Não | Tolere desvio de relógio ao validar declarações de tempo id\_token. Padrão `0`, que é rigoroso. Aumente se você vir erros "token expirado / ainda não válido" logo após o login devido a desvio de relógio host/IdP. |
94| `token_endpoint_auth_method` | Não | Substitua o método de autenticação do endpoint de token. Aceita `client_secret_basic` ou `client_secret_post`. Negociado automaticamente por padrão. |95| `token_endpoint_auth_method` | Não | Como o gateway se autentica no endpoint de token do IdP: `client_secret_basic`, `client_secret_post` ou `private_key_jwt` para [autenticação de cliente por certificado](#certificate-client-authentication). Por padrão, o gateway escolhe um dos dois métodos `client_secret` com base no que o IdP anuncia. |
96| `client_assertion` | Com `private_key_jwt` | Um bloco com `private_key_pem` e `certificate_pem`: a chave privada e o certificado para [autenticação de cliente por certificado](#certificate-client-authentication). Requer v2.1.284 ou posterior. |
95| `id_token_signed_response_alg` | Não | Algoritmo de assinatura id\_token esperado. Padrão `RS256`. Defina para IdPs que assinam com ES256, PS256 ou EdDSA. |97| `id_token_signed_response_alg` | Não | Algoritmo de assinatura id\_token esperado. Padrão `RS256`. Defina para IdPs que assinam com ES256, PS256 ou EdDSA. |
96| `additional_authorized_parties` | Não | Valores `azp` extras para aceitar além de `client_id`, para fluxos de broker e troca de token do Keycloak |98| `additional_authorized_parties` | Não | Valores `azp` extras para aceitar além de `client_id`, para fluxos de broker e troca de token do Keycloak |
97| `discovery_url` | Não | Busque o documento de descoberta desta URL em vez de derivá-lo de `issuer`, para IdPs atrás de um proxy que reescreve o host do emissor. O caminho deve conter `/.well-known/`. |99| `discovery_url` | Não | Busque o documento de descoberta desta URL em vez de derivá-lo de `issuer`, para IdPs atrás de um proxy que reescreve o host do emissor. O caminho deve conter `/.well-known/`. |
99| `form_action_origins` | Não | Origens adicionais para a diretiva `Content-Security-Policy: form-action` da página `/device`. O gateway já permite `'self'` e a origem `authorization_endpoint` descoberta, mas o Chrome impõe `form-action` contra toda a cadeia de redirecionamento. Se seu IdP redireciona através de um segundo host, como Azure AD federado para ADFS, Okta hub-spoke ou um interceptador SSO corporativo, liste cada origem pela qual a solicitação de autorização pode redirecionar. |101| `form_action_origins` | Não | Origens adicionais para a diretiva `Content-Security-Policy: form-action` da página `/device`. O gateway já permite `'self'` e a origem `authorization_endpoint` descoberta, mas o Chrome impõe `form-action` contra toda a cadeia de redirecionamento. Se seu IdP redireciona através de um segundo host, como Azure AD federado para ADFS, Okta hub-spoke ou um interceptador SSO corporativo, liste cada origem pela qual a solicitação de autorização pode redirecionar. |
100| `ca_cert_pem` | Não | O certificado CA codificado em PEM em si, não um caminho para um arquivo. Ele substitui o armazenamento de confiança do sistema apenas para solicitações do IdP. Para carregar um arquivo montado, escreva `${file:/etc/gateway/idp-ca.pem}`. Use para Keycloak ou Dex atrás de PKI corporativa. |102| `ca_cert_pem` | Não | O certificado CA codificado em PEM em si, não um caminho para um arquivo. Ele substitui o armazenamento de confiança do sistema apenas para solicitações do IdP. Para carregar um arquivo montado, escreva `${file:/etc/gateway/idp-ca.pem}`. Use para Keycloak ou Dex atrás de PKI corporativa. |
101 103
104<h4 id="certificate-client-authentication">
105 Autenticação de cliente por certificado
106</h4>
107
108Se o seu provedor de identidade autentica clientes OAuth com um certificado em vez de um segredo de cliente, como o Microsoft Entra faz com credenciais de certificado, defina `token_endpoint_auth_method: private_key_jwt`. Requer Claude Code v2.1.284 ou posterior no servidor gateway.
109
110Com essa configuração, o gateway não envia nenhum segredo. Ele se autentica no endpoint de token do IdP com um JWT de curta duração assinado com a chave privada do certificado quando um desenvolvedor faz login e cada vez que o gateway atualiza a sessão dele. O JWT é assinado com RS256 e identifica o certificado pelos cabeçalhos de thumbprint `x5t` e `x5t#S256` em vez de um `kid`. Seu IdP deve ser capaz de encontrar o certificado registrado pelo thumbprint.
111
112<Steps>
113 <Step title="Crie a chave e o certificado">
114 Crie uma chave privada RSA não criptografada de pelo menos 2048 bits, em formato PEM PKCS#8 ou PKCS#1, e um certificado para ela. O gateway se recusa a iniciar com qualquer chave que não atenda a essas condições. Este comando `openssl` cria uma chave desse tipo com um certificado autoassinado válido por um ano:
115
116 ```bash theme={null}
117 openssl req -x509 -newkey rsa:2048 -nodes -keyout idp-client.key -out idp-client.crt -days 365 -subj "/CN=claude-gateway"
118 ```
119
120 Ele grava `idp-client.key` e `idp-client.crt` no diretório atual. Copie ou monte ambos os arquivos onde o gateway possa lê-los. O exemplo na etapa 3 usa `/etc/gateway/`.
121 </Step>
122
123 <Step title="Envie o certificado para o IdP">
124 Envie o certificado, não a chave privada, para o registro de aplicativo do gateway no IdP.
125 </Step>
126
127 <Step title="Adicione a chave e o certificado ao gateway.yaml">
128 Forneça ao gateway a chave privada e o certificado em um bloco `client_assertion`. Omita `client_secret`, porque o gateway se recusa a iniciar quando ele está definido junto com `private_key_jwt`. Este bloco `oidc` autentica o gateway em um tenant do Microsoft Entra com um certificado:
129
130 ```yaml theme={null}
131 oidc:
132 issuer: https://login.microsoftonline.com/<tenant-id>/v2.0
133 client_id: <application-id>
134 token_endpoint_auth_method: private_key_jwt
135 client_assertion:
136 private_key_pem: ${file:/etc/gateway/idp-client.key}
137 certificate_pem: ${file:/etc/gateway/idp-client.crt}
138 ```
139
140 Ambos os valores são o conteúdo PEM, não caminhos de arquivo, portanto carregue arquivos montados com `${file:/path}` como o exemplo faz. O gateway se recusa a iniciar a menos que `certificate_pem` seja um único certificado PEM, sem o restante de sua cadeia, cuja chave pública corresponda a `private_key_pem`.
141 </Step>
142
143 <Step title="Reinicie o gateway e verifique o log de inicialização">
144 Reinicie o gateway e encontre esta linha no log de inicialização:
145
146 ```text theme={null}
147 [gateway] 2026-10-01T23:07:40.512Z info oidc: client authentication private_key_jwt; certificate CN=claude-gateway, SHA-1 thumbprint DE92821854EE8BAA1D98C758FAA04AABE80B9F57, expires Oct 1 23:07:31 2027 GMT
148 ```
149
150 Compare o thumbprint SHA-1 com o que o IdP mostra para o certificado que você enviou. Se o certificado tiver expirado ou ainda não for válido, o gateway ainda inicia, mas registra um aviso de que logins e atualizações falharão até que você o substitua. Para confirmar que o IdP aceita o certificado, peça a um desenvolvedor que faça login através do gateway.
151 </Step>
152</Steps>
153
154<h4 id="rotate-the-client-certificate">
155 Rotacionar o certificado do cliente
156</h4>
157
158O gateway lê a chave e o certificado uma vez na inicialização, portanto um arquivo alterado só tem efeito após uma reinicialização. Faça a rotação nesta ordem para que nenhuma requisição de token apresente um certificado que o IdP não tenha:
159
1601. Envie o novo certificado para o IdP junto com o antigo.
1612. Substitua os arquivos de chave e certificado que o `gateway.yaml` carrega e, em seguida, reinicie o gateway.
1623. Remova o certificado antigo do IdP.
163
102<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">
103 Solicitações do IdP através de um proxy de encaminhamento165 Solicitações do IdP através de um proxy de encaminhamento
104</h4>166</h4>
