Documentation 2026-10-06 23:59 UTC to 2026-10-07 00:59 UTC

75| - | - |75| - | - |

76| Claude Code v2.1.195 ou posterior | O subcomando `claude gateway` e o fluxo de sign-in do gateway são enviados na v2.1.195. Compilações públicas anteriores não as incluem. Tanto a máquina executando o servidor gateway quanto a máquina de cada desenvolvedor devem estar na v2.1.195 ou posterior; execute `claude update` para obter a versão mais recente. O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |76| Claude Code v2.1.195 ou posterior | O subcomando `claude gateway` e o fluxo de sign-in do gateway são enviados na v2.1.195. Compilações públicas anteriores não as incluem. Tanto a máquina executando o servidor gateway quanto a máquina de cada desenvolvedor devem estar na v2.1.195 ou posterior; execute `claude update` para obter a versão mais recente. O [upstream Claude Platform on AWS](/docs/pt/claude-apps-gateway-config#claude-platform-on-aws) requer Claude Code v2.1.198 ou posterior no servidor gateway. |

77| Provedor de identidade OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex, ou qualquer outro IdP compatível com OIDC, como PingFederate. O gateway executa descoberta OIDC padrão e o fluxo de código de autorização contra ele. SAML e LDAP não são suportados. |77| Provedor de identidade OpenID Connect (OIDC) | Okta, Microsoft Entra ID, Google Workspace, Keycloak ou Dex, ou qualquer outro IdP compatível com OIDC, como PingFederate. O gateway executa descoberta OIDC padrão e o fluxo de código de autorização contra ele. SAML e LDAP não são suportados. |

78| PostgreSQL 14 ou posterior | Faz backup do fluxo de sign-in do dispositivo, onde o callback do navegador escreve e a CLI de polling lê, além de contadores de limite de taxa. Qualquer Postgres gerenciado funciona, incluindo o menor nível. Sem limites de gastos configurados, o gateway armazena alguns KB de estado de autenticação de curta duração; com [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits), também mantém tabelas de gastos, auditoria e identidade duráveis que devem ser feitas backup. TLS via `?sslmode=require` é recomendado. |78| PostgreSQL 11 ou posterior | Dá suporte ao fluxo de sign-in do dispositivo e aos contadores de rate limit. Um serviço PostgreSQL gerenciado funciona, incluindo o menor nível; consulte [quais bancos de dados são suportados](/docs/pt/claude-apps-gateway-deploy#postgres). Com [limites de gastos](/docs/pt/claude-apps-gateway-spend-limits), também mantém tabelas de gastos, auditoria e identidade duráveis que devem ter backup. TLS via `?sslmode=require` é recomendado. PostgreSQL 11, 12 e 13 requerem Claude Code v2.1.290 ou posterior no servidor gateway. O projeto PostgreSQL não mantém mais essas versões, então use uma mais recente sempre que possível. |

79| Upstream de modelo | Credenciais do Amazon Bedrock, credenciais do Claude Platform on AWS, credenciais do Google Cloud, um recurso Microsoft Foundry ou uma chave de API Anthropic. Múltiplos upstreams são suportados com failover. |79| Upstream de modelo | Credenciais do Amazon Bedrock, credenciais do Claude Platform on AWS, credenciais do Google Cloud, um recurso Microsoft Foundry ou uma chave de API Anthropic. Múltiplos upstreams são suportados com failover. |

80| HTTPS | O gateway deve ser acessível via `https://` de laptops de desenvolvedores e de qualquer navegador usado para sign-in; o gateway serve a página de verificação do dispositivo no mesmo listener. Forneça um certificado TLS via `listen.tls` ou execute atrás de um ingress que termina TLS e defina `listen.public_url` para a origem externa em ambos os casos. Uma origem `http://` simples é aceita apenas quando o host do gateway é loopback: `localhost`, `127.0.0.1` ou `::1`. |80| HTTPS | O gateway deve ser acessível via `https://` de laptops de desenvolvedores e de qualquer navegador usado para sign-in; o gateway serve a página de verificação do dispositivo no mesmo listener. Forneça um certificado TLS via `listen.tls` ou execute atrás de um ingress que termina TLS e defina `listen.public_url` para a origem externa em ambos os casos. Em `/login`, Claude Code aceita uma origem `http://` simples apenas quando o host do gateway é loopback: `localhost`, `127.0.0.1` ou `::1`. |

81| Endereço de rede privada | Em `/login`, Claude Code requer que o nome de host ou endereço IP do gateway resolva apenas para endereços privados: RFC 1918, link-local, CGNAT `100.64.0.0/10`, ULA IPv6 `fc00::/7` ou loopback. Para um gateway que você hospeda, qualquer endereço público fora de um bloco que você declara é rejeitado; consulte o [modelo de ameaça](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) no guia de implantação. Se máquinas de desenvolvedores rotear HTTPS através de um proxy corporativo, o sign-in também requer que o host proxy resolva para endereços privados; se não resolver, adicione o host do gateway a `NO_PROXY` para que a CLI se conecte diretamente. Se sua rede interna for numerada a partir do espaço IPv4 público que sua organização possui, [declare esses blocos](#allow-a-gateway-on-public-address-space-you-own) para que `/login` aceite um gateway lá. |81| Endereço de rede privada | Em `/login`, Claude Code requer que o nome de host ou endereço IP do gateway resolva apenas para endereços privados: RFC 1918, link-local, CGNAT `100.64.0.0/10`, ULA IPv6 `fc00::/7` ou loopback. Para um gateway que você hospeda, qualquer endereço público fora de um bloco que você declara é rejeitado; consulte o [modelo de ameaça](/docs/pt/claude-apps-gateway-deploy#threat-model-summary) no guia de implantação. Se máquinas de desenvolvedores rotear HTTPS através de um proxy corporativo, o sign-in também requer que o host proxy resolva para endereços privados; se não resolver, adicione o host do gateway a `NO_PROXY` para que a CLI se conecte diretamente. Se sua rede interna for numerada a partir do espaço IPv4 público que sua organização possui, [declare esses blocos](#allow-a-gateway-on-public-address-space-you-own) para que `/login` aceite um gateway lá. |

82| Runtime Linux | O servidor gateway é executado apenas no binário Linux nativo. macOS funciona para desenvolvimento local. Windows não é suportado como plataforma de servidor. |82| Runtime Linux | O servidor gateway é executado apenas no binário Linux nativo. macOS funciona para desenvolvimento local. Windows não é suportado como plataforma de servidor. |

83 83 

91 </Step>91 </Step>

92 92 

93 <Step title="Provisione um banco de dados PostgreSQL">93 <Step title="Provisione um banco de dados PostgreSQL">

94 Qualquer Postgres 14 ou posterior funciona, incluindo o menor nível gerenciado. O gateway executa suas próprias migrações de esquema na inicialização, então o usuário do banco de dados precisa de direitos para criar e alterar tabelas; consulte [`store`](/docs/pt/claude-apps-gateway-config#store).94 Use PostgreSQL 11 ou posterior. O menor nível gerenciado é suficiente. O gateway executa suas próprias migrações de esquema na inicialização, então a função do banco de dados precisa de direitos para criar e alterar tabelas; consulte [`store`](/docs/pt/claude-apps-gateway-config#store).

95 </Step>95 </Step>

96 96 

97 <Step title="Escreva gateway.yaml">97 <Step title="Escreva gateway.yaml">

132 auto_include_builtin_models: true132 auto_include_builtin_models: true

133 ```133 ```

134 134 

135 Esta configuração é suficiente para um loop de sign-in funcionando com o catálogo de modelos Bedrock padrão. Uma vez em execução, adicione RBAC por grupo e configurações gerenciadas via [`managed.policies`](/docs/pt/claude-apps-gateway-config#managed), fan-out de telemetria via [`telemetry`](/docs/pt/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARNs de throughput provisionado ou regiões não-US via [`models`](/docs/pt/claude-apps-gateway-config#models).135 Esta configuração é suficiente para um loop de sign-in funcionando com o catálogo de modelos Amazon Bedrock padrão. Uma vez em execução, adicione RBAC por grupo e configurações gerenciadas via [`managed.policies`](/docs/pt/claude-apps-gateway-config#managed), fan-out de telemetria via [`telemetry`](/docs/pt/claude-apps-gateway-config#telemetry), e failover multi-upstream, ARNs de throughput provisionado ou regiões não-US via [`models`](/docs/pt/claude-apps-gateway-config#models).

136 136 

137 <Note>137 <Note>

138 O upstream Amazon Bedrock precisa de um principal AWS com `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs `inference-profile/us.anthropic.*` e nos ARNs `foundation-model/anthropic.*` subjacentes. Ele também precisa do formulário de caso de uso único da Anthropic enviado para a conta a partir do catálogo de modelos do console Bedrock.138 O upstream Amazon Bedrock precisa de um principal AWS com `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos ARNs `inference-profile/us.anthropic.*` e nos ARNs `foundation-model/anthropic.*` subjacentes. Ele também precisa do formulário de caso de uso único da Anthropic enviado para a conta a partir do catálogo de modelos do console Bedrock.

172 volumes: { pgdata: }172 volumes: { pgdata: }

173 ```173 ```

174 174 

175 O gateway é um único binário Linux que lê a configuração, se conecta ao Postgres e aplica suas migrações de esquema, executa descoberta OIDC contra seu IdP, constrói clientes upstream e começa a escutar. A inicialização é fail-closed para a configuração, a conexão Postgres, descoberta OIDC e construção de cliente upstream. Se qualquer um desses for inacessível ou mal configurado, o gateway sai com um erro em vez de servir tráfego em um estado degradado.175 O gateway é um único binário Linux que lê a configuração, se conecta ao Postgres e aplica suas migrações de esquema, executa descoberta OIDC contra seu IdP, constrói clientes upstream e começa a escutar.

176 176 

177 Uma inicialização bem-sucedida não valida o caminho de inferência, porque credenciais de instância Bedrock e Agent Platform resolvem na primeira solicitação, não na inicialização.177 A inicialização é fail-closed para a configuração, a conexão Postgres, descoberta OIDC e construção de cliente upstream. Se qualquer um desses for inacessível ou mal configurado, o gateway sai com um erro em vez de servir tráfego em um estado degradado.

178 

179 Uma inicialização bem-sucedida não valida o caminho de inferência, porque credenciais de instância do Amazon Bedrock e da Agent Platform do Google Cloud resolvem na primeira requisição, não na inicialização.

178 180 

179 Observe stderr para a sequência de inicialização. As linhas de log usam o formato `[gateway] <timestamp> <level> <message>`, eventos de auditoria são JSON de linha única com um campo `evt`, e um banner de inicialização, omitido abaixo, é impresso entre as linhas de migração e escuta. Um banco de dados novo imprime uma linha `migration N applied` por migração de esquema; um banco de dados já migrado não imprime nenhuma. Você deve ver, em ordem:181 Observe stderr para a sequência de inicialização. As linhas de log usam o formato `[gateway] <timestamp> <level> <message>`, eventos de auditoria são JSON de linha única com um campo `evt`, e um banner de inicialização, omitido abaixo, é impresso entre as linhas de migração e escuta. Um banco de dados novo imprime uma linha `migration N applied` por migração de esquema; um banco de dados já migrado não imprime nenhuma. Você deve ver, em ordem:

180 182 

206 208 

207 Os exemplos usam a URL pública do gateway; para a configuração local do Compose sem um ingress, substitua `http://localhost:8080` nas duas primeiras verificações. A terceira verificação abre `verification_uri_complete`, que é construída a partir de `public_url`, então para Compose local defina `public_url: http://localhost:8080` em `gateway.yaml` e adicione `http://localhost:8080/oauth/callback` como um segundo URI de redirecionamento no cliente OAuth da etapa 1, porque o gateway constrói o `redirect_uri` do IdP a partir de `public_url`. O link de verificação então abre em seu navegador local.209 Os exemplos usam a URL pública do gateway; para a configuração local do Compose sem um ingress, substitua `http://localhost:8080` nas duas primeiras verificações. A terceira verificação abre `verification_uri_complete`, que é construída a partir de `public_url`, então para Compose local defina `public_url: http://localhost:8080` em `gateway.yaml` e adicione `http://localhost:8080/oauth/callback` como um segundo URI de redirecionamento no cliente OAuth da etapa 1, porque o gateway constrói o `redirect_uri` do IdP a partir de `public_url`. O link de verificação então abre em seu navegador local.

208 210 

209 No Windows PowerShell, execute `curl.exe`; o `curl` simples é um alias para `Invoke-WebRequest` e rejeita esses sinalizadores.211 No Windows PowerShell, execute `curl.exe`; o `curl` simples é um alias para `Invoke-WebRequest` e rejeita essas flags.

210 212 

211 Primeiro, busque o documento de descoberta, que confirma que o gateway está ativo, a configuração é válida e todas as verificações de inicialização passaram:213 Primeiro, busque o documento de descoberta, que confirma que o gateway está ativo, a configuração é válida e todas as verificações de inicialização passaram:

212 214 

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: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 159 

1601. Envie o novo certificado para o IdP junto com o antigo.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.1612. Substitua os arquivos de chave e certificado que o `gateway.yaml` carrega e, em seguida, reinicie o gateway. Se você executa várias réplicas, uma [reinicialização gradual](/docs/pt/claude-apps-gateway-deploy#upgrades) funciona, porque o IdP tem ambos os certificados até que você remova o antigo.

1623. Remova o certificado antigo do IdP.1623. Depois que todas as réplicas tiverem reiniciado, remova o certificado antigo do IdP.

163 163 

164<h4 id="idp-requests-through-a-forward-proxy">164<h4 id="idp-requests-through-a-forward-proxy">

165 Solicitações do IdP através de um proxy de encaminhamento165 Solicitações do IdP através de um proxy de encaminhamento

227 227 

228| Campo | Obrigatório | Descrição |228| Campo | Obrigatório | Descrição |

229| - | - | - |229| - | - | - |

230| `postgres_url` | Sim | URL `postgres://` ou `postgresql://`. Obrigatório: o encontro de concessão de dispositivo, onde o callback do navegador escreve e o CLI de sondagem lê, precisa de estado entre réplicas. O gateway executa suas próprias migrações de esquema na inicialização e na atualização, portanto a função precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte [Atualizações](/docs/pt/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/pt/claude-apps-gateway-deploy#postgres). |230| `postgres_url` | Sim | URL `postgres://` ou `postgresql://` com um único host, não uma lista separada por vírgulas. O gateway executa suas próprias migrações de esquema na inicialização e na atualização, portanto a função precisa de direitos para criar e alterar tabelas no esquema de destino. Consulte [Atualizações](/docs/pt/claude-apps-gateway-deploy#upgrades) e [Postgres](/docs/pt/claude-apps-gateway-deploy#postgres). |

231| `username` | Não | Substitui o usuário em `postgres_url` |231| `username` | Não | Substitui o usuário em `postgres_url` |

232| `password` | Não | Credencial do banco de dados. Defina aqui em vez de em `postgres_url` para que a credencial fique fora da URL. Aceita qualquer caractere e tem precedência sobre credenciais de URL. |232| `password` | Não | Credencial do banco de dados. Defina aqui em vez de em `postgres_url` para que a credencial fique fora da URL. Aceita qualquer caractere e tem precedência sobre credenciais de URL. |

233| `max_connections` | Não | Tamanho do pool de conexão Postgres por réplica. Padrão `5`, que é conservador e amigável para bancos de dados compartilhados. Com [limites de gastos](#admin) habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do `max_connections` do banco de dados. |233| `max_connections` | Não | Tamanho do pool de conexão Postgres por réplica. Padrão `5`, que é conservador e amigável para bancos de dados compartilhados. Com [limites de gastos](#admin) habilitados, o caminho quente faz algumas operações por solicitação de inferência, portanto aumente para um banco de dados dedicado sob carga e mantenha réplicas × isto abaixo do `max_connections` do banco de dados. |

249 Postgres249 Postgres

250</h3>250</h3>

251 251 

252O gateway armazena seu estado em um banco de dados PostgreSQL:

253 

254* **Banco de dados**: o próprio PostgreSQL, auto-hospedado ou gerenciado, na [versão mínima](/docs/pt/claude-apps-gateway#prerequisites) ou posterior. Bancos de dados que apenas implementam o protocolo Postgres, como bancos de dados SQL distribuídos, não são suportados.

255* **Endereço**: `store.postgres_url` aceita um único host. Se o banco de dados tiver vários nós, use o endereço que fica na frente deles, como o endpoint do seu serviço gerenciado, um balanceador de carga ou um IP virtual. Defina um [período de carência de prontidão](#readiness-grace-period) mais longo do que um failover leva.

256 

252O gateway mantém cinco tabelas de dados mais uma tabela `_migrations`, todas criadas por suas migrações de tempo de inicialização:257O gateway mantém cinco tabelas de dados mais uma tabela `_migrations`, todas criadas por suas migrações de tempo de inicialização:

253 258 

254| Tabela | Conteúdo | Retenção |259| Tabela | Conteúdo | Retenção |

396| CLI `/login`: `Could not resolve the configured HTTP proxy` | O nome do host em `HTTPS_PROXY` ou `HTTP_PROXY` não resolve da máquina do desenvolvedor, tipicamente porque não está conectado à rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN e tentar novamente, ou corrija a URL do proxy |401| CLI `/login`: `Could not resolve the configured HTTP proxy` | O nome do host em `HTTPS_PROXY` ou `HTTP_PROXY` não resolve da máquina do desenvolvedor, tipicamente porque não está conectado à rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN e tentar novamente, ou corrija a URL do proxy |

397| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, tipicamente porque não está na rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN, depois execute `/login` novamente |402| CLI `/login`: `Could not resolve gateway host <host>` | A máquina não consegue resolver o nome DNS interno do gateway, tipicamente porque não está na rede corporativa | Peça ao desenvolvedor para conectar à sua rede ou VPN, depois execute `/login` novamente |

398| A inicialização sai com um erro de validação de configuração que nomeia `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um container descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |403| A inicialização sai com um erro de validação de configuração que nomeia `store.postgres_url` | Nenhum Postgres configurado; o gateway requer Postgres | Defina `store.postgres_url`. Para desenvolvimento local, use um container descartável: `docker run --rm -p 5432:5432 -e POSTGRES_HOST_AUTH_METHOD=trust postgres`. |

404| A inicialização sai: `store.postgres_url in <path> is not a URL the gateway can read`, ou, antes da v2.1.290, um simples `Invalid URL` ou `URI error` | A URL não pode ser analisada, por exemplo porque lista mais de um host ou sua senha tem um `/`, `?`, `#` ou `%` não codificado | Nomeie [um host](#postgres), e mova a senha para [`store.password`](/docs/pt/claude-apps-gateway-config#store) |

399| A inicialização sai: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale Claude Code com um dos [métodos de instalação autônomos](/docs/pt/setup) |405| A inicialização sai: `requires the native binary` | Executando sob Node em vez do binário nativo | Instale Claude Code com um dos [métodos de instalação autônomos](/docs/pt/setup) |

400| A inicialização sai com um erro de descoberta OIDC após `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é acessível do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. Se o pod alcança o IdP apenas através de um forward proxy, defina [`oidc.use_proxy: true`](/docs/pt/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); em versões anteriores a v2.1.227, dê ao pod uma rota direta para cada um dos endpoints do IdP em vez disso. Se o pod também não conseguir resolver o nome do host do IdP, ou o proxy recusar `CONNECT` para um endereço IP, veja [Proxy-only egress](/docs/pt/claude-apps-gateway-config#proxy-only-egress), que requer v2.1.277 ou posterior. |406| A inicialização sai com um erro de descoberta OIDC após `config.load` | `oidc.issuer` inacessível, ou cadeia TLS não confiável | Verifique se o emissor é acessível do pod e serve `/.well-known/openid-configuration`. Defina `ca_cert_pem` para PKI privada. Se o pod alcança o IdP apenas através de um forward proxy, defina [`oidc.use_proxy: true`](/docs/pt/claude-apps-gateway-config#idp-requests-through-a-forward-proxy); em versões anteriores a v2.1.227, dê ao pod uma rota direta para cada um dos endpoints do IdP em vez disso. Se o pod também não conseguir resolver o nome do host do IdP, ou o proxy recusar `CONNECT` para um endereço IP, veja [Proxy-only egress](/docs/pt/claude-apps-gateway-config#proxy-only-egress), que requer v2.1.277 ou posterior. |

401| A inicialização sai com um erro de permissão do Postgres | O papel do banco de dados carece de direitos DDL em seu esquema | Conceda ao papel `CREATE` no esquema do gateway para que possa criar e alterar suas tabelas na inicialização |407| A inicialização sai com um erro de permissão do Postgres | O papel do banco de dados carece de direitos DDL em seu esquema | Conceda ao papel `CREATE` no esquema do gateway para que possa criar e alterar suas tabelas na inicialização |

402| Log: `could not connect to Postgres at boot, attempt 1 of 3` | O banco de dados não estava acessível quando o gateway iniciou, por exemplo em uma instância fria cuja rede ainda está se iniciando | Se o gateway então terminar de inicializar, nenhuma ação é necessária. Quando o banco de dados não está acessível, o gateway tenta a conexão três vezes, dois segundos de intervalo, antes de sair. Se sair com `could not connect to Postgres`, verifique `store.postgres_url` e o caminho de rede para o banco de dados. Se as tentativas atingirem o timeout em vez de serem recusadas, aumente [`store.connect_timeout_seconds`](/docs/pt/claude-apps-gateway-config#store) para dar a cada uma mais tempo. |408| Log: `could not connect to Postgres at boot, attempt 1 of 3` | O banco de dados não estava acessível quando o gateway iniciou, por exemplo em uma instância fria cuja rede ainda está se iniciando | Se o gateway então terminar de inicializar, nenhuma ação é necessária. Quando o banco de dados não está acessível, o gateway tenta a conexão três vezes, dois segundos de intervalo, antes de sair. Se sair com `could not connect to Postgres`, verifique `store.postgres_url`, incluindo se ela nomeia um único host, e o caminho de rede para o banco de dados. Se as tentativas atingirem o timeout em vez de serem recusadas, aumente [`store.connect_timeout_seconds`](/docs/pt/claude-apps-gateway-config#store) para dar a cada uma mais tempo. |

403| `/oauth/callback` mostra "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem possibilidade de sobrescrever | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |409| `/oauth/callback` mostra "Sign-in could not be completed" | Domínio de email rejeitado, validação de id\_token falhou, ou `email_verified` é explicitamente `false`, que o gateway sempre rejeita sem possibilidade de sobrescrever | Verifique `allowed_email_domains` e que o IdP retorna uma reivindicação `email` verificada. Para `email_verified: false`, corrija a verificação do lado do IdP. Se seu IdP emite email sob um nome de reivindicação diferente, defina `oidc.email_claim`. |

404| Log: `token exchange failed request_id=<id>: id_token missing email claim` | O IdP não está incluindo `email` no id\_token por padrão. Essa rejeição dispara apenas quando `allowed_email_domains` está definido; sem ele, um email ausente cria uma sessão sem email | Configure o IdP para emitir `email` no id\_token. Okta: adicione `email` às reivindicações de token de ID de um servidor de autorização personalizado. Entra: adicione `email` como uma reivindicação opcional no registro do aplicativo. PingFederate: ative uma Política OpenID Connect que emita `email`. Se o IdP serve `email` do endpoint userinfo mas não o incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |410| Log: `token exchange failed request_id=<id>: id_token missing email claim` | O IdP não está incluindo `email` no id\_token por padrão. Essa rejeição dispara apenas quando `allowed_email_domains` está definido; sem ele, um email ausente cria uma sessão sem email | Configure o IdP para emitir `email` no id\_token. Okta: adicione `email` às reivindicações de token de ID de um servidor de autorização personalizado. Entra: adicione `email` como uma reivindicação opcional no registro do aplicativo. PingFederate: ative uma Política OpenID Connect que emita `email`. Se o IdP serve `email` do endpoint userinfo mas não o incluirá no id\_token, como o servidor de autorização da organização Okta, defina `oidc.userinfo_fallback: true`. |

405| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a requisição de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |411| Log: `refresh failed request_id=<id>: invalid_token (…) (at userinfo_no_id_token, …)`, e desenvolvedores veem `Cloud gateway session expired` a cada `session.ttl_hours` | O IdP aceitou o token de atualização mas não retornou id\_token com ele, então o gateway perguntou ao endpoint userinfo do IdP pelas reivindicações do usuário. O IdP rejeitou o token de acesso atualizado lá. O gateway responde `temporarily_unavailable`, então Claude Code mantém o token de atualização mas não consegue renovar a sessão. Versões do gateway anteriores a v2.1.260 registram a mesma linha sem o detalhe `(at …)`. | Defina [`oidc.scope_on_refresh: true`](/docs/pt/claude-apps-gateway-config#oidc), disponível no gateway v2.1.260 ou posterior, para que a requisição de atualização peça por `openid` novamente. Alguns IdPs, como Okta, retornam um id\_token na atualização apenas quando solicitado. No PingFederate, ative **Return ID Token On Refresh Grant** sob **Applications > OAuth > OpenID Connect Policy Management** em vez disso. A chave não muda o comportamento do PingFederate. Para outros IdPs que ainda o omitem, verifique se o endpoint userinfo aceita tokens de acesso emitidos por uma atualização. Como uma solução temporária, aumente [`session.ttl_hours`](/docs/pt/claude-apps-gateway-config#session). Veja [Identity provider setup](#identity-provider-setup) para o tradeoff de desprovisionamento. |

169 </Step>169 </Step>

170 170 

171 <Step title="Provisione Amazon RDS para PostgreSQL">171 <Step title="Provisione Amazon RDS para PostgreSQL">

172 A instância é executada nas subnets privadas sem endereço público e com criptografia de armazenamento ativada. A versão do mecanismo é fixada em Postgres 16, que satisfaz o piso suportado do gateway de PostgreSQL 14 e garante que a família do grupo de parâmetros abaixo corresponda à instância.172 A instância executa o Postgres 16 nas subnets privadas, sem endereço público e com criptografia de armazenamento ativada.

173 173 

174 Primeiro, crie o grupo de subnets que coloca o banco de dados nas subnets privadas e um grupo de parâmetros com `rds.force_ssl=1` para que o servidor rejeite conexões em texto simples. A versão do mecanismo é fixada uma vez porque a família do grupo de parâmetros deve corresponder à versão principal do mecanismo que a instância executa:174 Primeiro, crie o grupo de subnets que coloca o banco de dados nas subnets privadas e um grupo de parâmetros com `rds.force_ssl=1` para que o servidor rejeite conexões em texto simples. A versão do mecanismo é fixada uma vez porque a família do grupo de parâmetros deve corresponder à versão principal do mecanismo que a instância executa:

175 175