> ## Documentation Index
> Fetch the complete documentation index at: https://clickhouse.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Configuração da autenticação JWT

> Como configurar provedores de autenticação JWT (JWKS) para cada serviço do ClickHouse Cloud pelo Console

export const BetaBadge = ({link, galaxyTrack, galaxyEvent}) => {
  if (link) {
    return <a href={link} target="_blank" rel="noopener noreferrer" className="betaBadge" onClick={galaxyTrack && galaxyEvent ? galaxyOnClick(galaxyEvent) : undefined}>
                <span>Beta</span>
            </a>;
  }
  return <a href="https://clickhouse.com/docs/reference/settings/beta-and-experimental-features#beta-features" className="betaBadge">
            <span>Recurso beta</span>
        </a>;
};

export const VersionBadge = ({minVersion}) => <div className="versionBadge">
    <div className="versionIcon" style={{
  marginRight: "8px",
  marginTop: "4px"
}}>
      <svg width="16" height="16" viewBox="0 0 16 16" fill="none" xmlns="http://www.w3.org/2000/svg">
        <path d="M5 14C5.82843 14 6.5 13.3284 6.5 12.5C6.5 11.6716 5.82843 11 5 11C4.17157 11 3.5 11.6716 3.5 12.5C3.5 13.3284 4.17157 14 5 14Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M5 5C5.82843 5 6.5 4.32843 6.5 3.5C6.5 2.67157 5.82843 2 5 2C4.17157 2 3.5 2.67157 3.5 3.5C3.5 4.32843 4.17157 5 5 5Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M13 10.5C13.8284 10.5 14.5 9.82843 14.5 9C14.5 8.17157 13.8284 7.5 13 7.5C12.1716 7.5 11.5 8.17157 11.5 9C11.5 9.82843 12.1716 10.5 13 10.5Z" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
        <path d="M11.5 9H9.5C9.03426 9 8.57493 8.89157 8.15836 8.68328C7.74179 8.475 7.37944 8.17259 7.1 7.8L5 5V11" stroke="currentColor" strokeLinecap="round" strokeLinejoin="round" strokeWidth="1.25" />
      </svg>
    </div>
    Disponível a partir da versão {minVersion}
  </div>;

export const EnterprisePlanFeatureBadge = ({feature = 'Este recurso', support = false, linking_verb_are = false}) => {
  return <div className="enterprisePlanFeatureContainer">
            <div className="enterprisePlanFeatureBadge">
                Recurso do plano Enterprise
            </div>
            <div>
                <p>{feature} {linking_verb_are ? 'estão disponíveis' : 'está disponível'} no plano Enterprise. {support ? `Entre em contato com o suporte para habilitar este recurso.` : 'Para fazer o upgrade, acesse a página de planos no Cloud Console.'}</p>
            </div>
        </div>;
};

export const Image = ({img, alt, size = "lg", background}) => {
  const normalizedSize = ["sm", "md", "lg"].includes(size) ? size : "lg";
  const backgroundColor = background === "white" ? "white" : background === "black" ? "rgb(31 31 28)" : undefined;
  return <div className={`ch-image-${normalizedSize}`}>
      <Frame>
        <img src={img} alt={alt} style={{
    backgroundColor
  }} />
      </Frame>
    </div>;
};

<BetaBadge />

<VersionBadge minVersion="26.4" />

<EnterprisePlanFeatureBadge feature="Autenticação JWT com provedor de identidade personalizado" />

<Tip>
  Este guia aborda a configuração de provedores JWKS no Cloud Console. Para saber como gerar um JWT e como é sua estrutura — as claims obrigatórias, as claims de funções e grants e o funcionamento dos usuários efêmeros — consulte a referência sobre [Autenticação JWT](/docs/pt-BR/concepts/features/security/external-authenticators/jwt).
</Tip>

O ClickHouse Cloud permite autenticar conexões com um serviço usando JSON Web Tokens (JWTs) validados nos seus próprios endpoints de JSON Web Key Set (JWKS). Em vez de gerenciar credenciais de banco de dados, seu provedor de identidade emite tokens de curta duração que o ClickHouse verifica com base nas chaves públicas publicadas em um URL JWKS configurado por você.

Você pode configurar esses provedores JWKS para cada serviço em **Settings → Security** no Cloud Console do ClickHouse.

<div id="before-you-begin">
  ## Antes de começar
</div>

Para configurar provedores JWT para um serviço, você precisa de:

* Uma organização no plano **Enterprise**.
* Um serviço executando o **ClickHouse versão 26.4 ou posterior**.
* Uma função com a permissão `control-plane:service:manage` no serviço (por exemplo, **Admin** ou **Service admin**). Os membros sem essa permissão veem a seção como somente leitura.
* Uma URL JWKS **HTTPS** acessível publicamente que publique pelo menos uma chave **RSA** (`RS256`) ou, para serviços na versão 26.8 ou posterior, uma chave **EC** (`ES256`, `ES384`, `ES512`).

<Note>
  Provedores baseados em JWKS aceitam chaves **RSA** e, a partir da versão 26.8, chaves **EC** nas curvas P-256, P-384 e P-521. Um documento JWKS pode conter outros tipos de chave, mas deve haver pelo menos uma chave utilizável.
</Note>

<div id="how-it-works">
  ## Como funciona
</div>

O cliente (seu provedor de identidade ou aplicação) gera um JWT e o assina com sua **chave privada**. O token deve seguir o [formato de token](/docs/pt-BR/concepts/features/security/external-authenticators/jwt#token-claims) esperado. Em seguida, o ClickHouse o verifica usando as chaves **públicas** publicadas no URL do seu JWKS:

1. O ClickHouse lê o cabeçalho `kid` (ID da chave) do token e seleciona a chave correspondente no documento JWKS.
2. Ele verifica a assinatura do token usando essa chave pública e valida as claims `iss` (emissor) e `aud` (audiência) em relação à configuração do seu provedor.
3. Em caso de sucesso, a conexão é estabelecida como um usuário efêmero, cujos direitos de acesso são derivados das claims `clickhouse:grants` e `clickhouse:roles` do token, limitados pelo limite de permissões (o usuário `default`). Consulte [Direitos de acesso](/docs/pt-BR/concepts/features/security/external-authenticators/jwt#access-rights) para obter detalhes.

O ClickHouse valida e busca o URL JWKS quando você adiciona ou atualiza um provedor. Assim, um URL configurado incorretamente ou inacessível é rejeitado imediatamente.

<div id="add-a-jwt-provider">
  ## Adicionar um provedor JWT
</div>

<Steps>
  <Step title="Abra as configurações de segurança do serviço" id="open-security-settings">
    Acesse o serviço, abra **Settings** e role até a seção **Security**. Localize o cartão **JWT authentication**.

    <Image img="https://mintcdn.com/private-7c7dfe99/-6hzQ2QWO_HW75mL/images/cloud/security/jwt/jwt-section.png?fit=max&auto=format&n=-6hzQ2QWO_HW75mL&q=85&s=79179b401f3a527316bffe67be424977" size="lg" alt="Seção de autenticação JWT nas configurações de segurança do serviço" force width="1850" height="422" data-path="images/cloud/security/jwt/jwt-section.png" />
  </Step>

  <Step title="Abra o painel de provedores" id="open-flyout">
    Selecione **Set up JWT providers** (ou **Manage JWT providers**, caso já tenha algum configurado). O painel será aberto com um formulário para um novo provedor pronto para preenchimento.
  </Step>

  <Step title="Preencha os detalhes do provedor" id="fill-provider-details">
    Preencha o formulário do provedor e selecione **Save**.

    | Campo                      | Descrição                                                                                                                                                                                          |
    | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Name**                   | Um nome único para este provedor no serviço. Não pode ser alterado após a criação.                                                                                                                 |
    | **Issuer**                 | A claim `iss` esperada nos tokens recebidos.                                                                                                                                                       |
    | **Audience**               | A claim `aud` esperada nos tokens recebidos.                                                                                                                                                       |
    | **JWKS URL**               | A URL HTTPS pública que disponibiliza as chaves públicas usadas para verificar assinaturas de tokens.                                                                                              |
    | **Roles claim** (opcional) | A claim do token da qual as funções do ClickHouse serão lidas. Deixe em branco para usar o nome de claim padrão `clickhouse:roles`. As funções especificadas no token já devem existir no serviço. |
  </Step>

  <Step title="Adicione mais provedores, se necessário" id="add-more-providers">
    Use **Add another provider** para configurar provedores adicionais. Um serviço pode ter no máximo cinco provedores JWT.
  </Step>
</Steps>

<Warning>
  Excluir um provedor JWT interrompe imediatamente a aceitação de tokens emitidos por ele, e quaisquer workloads que ainda se autentiquem com esses tokens deixarão de funcionar.
</Warning>

<div id="limits">
  ## Limites
</div>

* No máximo **cinco** provedores JWT por serviço.
* Provedores JWKS aceitam chaves **RSA** (`RS256`) e, a partir da versão 26.8, chaves **EC** (`ES256`, `ES384`, `ES512`).
* A URL JWKS deve ser um endpoint HTTPS público. Endereços privados, internos ou de link local são rejeitados.

<div id="related">
  ## Conteúdo relacionado
</div>

* [Autenticação JWT](/docs/pt-BR/concepts/features/security/external-authenticators/jwt) — claims de tokens, usuários efêmeros e uso do cliente.