Este documento foi traduzido usando tecnologia de tradução automática de máquina. Sempre trabalhamos para apresentar traduções precisas, mas não oferecemos nenhuma garantia em relação à integridade, precisão ou confiabilidade do conteúdo traduzido. Em caso de qualquer discrepância, a versão original em inglês prevalecerá e constituirá o texto official.

Configurar Keycloak (OIDC)

Se sua organização usa o Provedor de Identidade Keycloak (IdP) para autenticação de usuários, você pode configurar o Rancher para permitir que seus usuários façam login usando suas credenciais do IdP. O Rancher suporta integração com o Keycloak usando o protocolo OpenID Connect (OIDC) e o protocolo SAML. Ambas as implementações são funcionalmente equivalentes quando usadas com o Rancher. Esta página descreve o processo para configurar o Rancher para trabalhar com o Keycloak usando o protocolo OIDC.

Se você preferir usar o Keycloak com o protocolo SAML, consulte esta página.

Se você tiver uma configuração existente usando o protocolo SAML e quiser mudar para o protocolo OIDC, consulte esta seção.

Pré-requisitos

  • No Rancher, o Keycloak (SAML) está desativado.

  • Você deve ter um servidor Keycloak IdP configurado.

  • Siga a documentação do Keycloak para criar um novo cliente OIDC com as configurações abaixo.

    Configuração Valor

    Client ID

    <client-id> (ex. rancher)

    Name

    <client-name> (ex. rancher)

    Client type

    OpenID Connect

    Client authentication

    ON

    Valid Redirect URI

    https://yourRancherHostURL/verify-auth

  • No novo cliente OIDC, crie Mappers para expor os campos dos usuários.

    1. No menu de navegação, clique em Clientes.

    2. Clique na aba Lista de Clientes.

    3. Encontre e clique no cliente que você criou.

    4. Clique na aba Escopos do Cliente.

    5. Encontre e clique no link rotulado como <client-name>-dedicated. Por exemplo, se você nomeou seu cliente como rancher, procure o link chamado rancher-dedicated.

    6. Clique na aba Mappers.

    7. Clique em Configurar um novo mapper. Se você já tiver mappers existentes configurados, clique na seta ao lado de Adicionar mapper e selecione Por configuração. Repita este processo e crie estes mappers:

      • Na tabela de mapeamentos, selecione Associação ao Grupo e configure um novo "Mapper de Grupos" com as configurações abaixo. Para configurações que não são mencionadas, use o valor padrão.

        Configuração Valor

        Name

        Groups Mapper

        Mapper Type

        Group Membership

        Token Claim Name

        groups

        Full group path

        OFF

        Add to ID token

        OFF

        Add to access token

        OFF

        Add to user info

        ON

      • Na tabela de mapeamentos, selecione Público e configure um novo "Público do Cliente" com as configurações abaixo. Para configurações que não são mencionadas, use o valor padrão.

        Configuração Valor

        Name

        Client Audience

        Mapper Type

        Audience

        Included Client Audience

        <client-name>

        Add to ID token

        OFF

        Add to access token

        ON

      • Na tabela de mapeamentos, selecione Associação ao Grupo e configure um novo "Caminho de Grupos" com as configurações abaixo. Para configurações que não são mencionadas, use o valor padrão.

        Configuração Valor

        Name

        Group Path

        Mapper Type

        Group Membership

        Token Claim Name

        full_group_path

        Full group path

        ON

        Add to ID token

        ON

        Add to access token

        ON

        Add to user info

        ON

  • Adicione os seguintes mapeamentos de função a todos os usuários ou grupos que precisam consultar os usuários do Keycloak.

    • Usuários

    • Grupos

    1. No menu de navegação, clique em Usuários.

    2. Clique no usuário ao qual você deseja adicionar mapeamentos de função.

    3. Clique na aba Mapeamento de função.

    4. Clique em Designar função.

    5. Selecione as seguintes funções:

      • consultar-usuários

      • query-groups

      • ver-usuários

    6. Clique em Designar.

    1. No menu de navegação, clique em Grupos.

    2. Clique no grupo ao qual você deseja adicionar mapeamentos de função.

    3. Clique na aba Mapeamento de função.

    4. Clique em Designar função.

    5. Selecione as seguintes funções:

      • consultar-usuários

      • query-groups

      • ver-usuários

    6. Clique em Designar.

Configurando o Keycloak no Rancher

  1. Na interface do Rancher, clique em ☰ > Usuários e Autenticação.

  2. Na barra de navegação à esquerda, clique em Provedor de Autenticação.

  3. Selecione Keycloak (OIDC).

  4. Preencha o formulário Configurar uma conta OIDC do Keycloak. Para ajuda com o preenchimento do formulário, consulte a referência de configuração.

    Ao configurar a seção Pontos de Extremidade usando a opção Gerar, o Rancher inclui /auth como parte do caminho de contexto nos campos Emissor e Endpoint de Autenticação, que é válido apenas para o Keycloak 16 ou anterior. Você deve configurar os pontos de extremidade usando a opção Especificar para Keycloak 17 e versões mais novas, que migraram para o Quarkus.

  5. Após completar o formulário Configurar uma conta OIDC do Keycloak, clique em Habilitar.

    O Rancher redireciona você para a página de login do IdP. Insira as credenciais que autenticam com o IdP Keycloak para validar sua configuração do Keycloak no Rancher.

    Você pode precisar desativar seu bloqueador de pop-ups para ver a página de login do IdP.

Resultado: O Rancher está configurado para trabalhar com o Keycloak usando o protocolo OIDC. Seus usuários agora podem fazer login no Rancher usando suas credenciais do Keycloak.

Referência de configuração

Campo Descrição

ID do cliente

O Client ID do seu cliente Keycloak.

Segredo do Cliente

O Secret gerado do seu cliente Keycloak. No console do Keycloak, selecione Clientes, selecione o cliente que você criou, selecione a aba Credenciais e copie o valor do campo Secret.

Chave Privada / Certificado

Um par chave/certificado para criar um shell seguro entre o Rancher e seu IdP. Necessário se HTTPS/SSL estiver habilitado em seu servidor Keycloak.

seguros

Escolha se deseja usar os valores gerados para os campos Rancher URL, Issue e Auth Endpoint ou fornecer substituições manuais se estiverem incorretos.

URL do Keycloak

A URL do seu servidor Keycloak.

Domínio do Keycloak

O nome do domínio em que o cliente Keycloak foi criado.

URL do Rancher

A URL do seu Servidor Rancher.

Emissor

A URL do seu IdP.

Endpoint de Autenticação

A URL para onde os usuários são redirecionados para autenticação.

Migrando de SAML para OIDC

Esta seção descreve o processo de transição de usar o Rancher com Keycloak (SAML) para Keycloak (OIDC).

  1. Reconfigurar o Keycloak.

    1. Configure um novo OpenID Connect cliente de acordo com os Pré-requisitos. Certifique-se de que os mesmos Valid Redirect URIs estão configurados.

    2. Configure mapeadores para o novo cliente de acordo com os Pré-requisitos.

  2. Antes de configurar o Rancher para usar o Keycloak (OIDC), o Keycloak (SAML) deve ser desabilitado primeiro.

    1. Na interface do Rancher, clique em ☰ > Usuários e Autenticação.

    2. Na barra de navegação à esquerda, clique em Provedor de Autenticação.

    3. Selecione Keycloak (SAML).

    4. Clique em Desabilitar.

  3. Siga os passos em Configurando o Keycloak no Rancher.

    Após a configuração ser concluída, as permissões de usuário do Rancher precisam ser reaplicadas, pois não são migradas automaticamente.

Suporte OIDC para Extensão PKCE

Rancher supports the Proof Key for Code Exchange (PKCE) extension (RFC 7636) for OIDC authentication providers. SHA-256 (S256) is the only supported PKCE verification method. To enable this feature, your authentication provider must use PKCE with S256 for authorization requests.

You can enable this feature by selecting Enable PKCE (S256) in your authentication provider configuration in Rancher. Enabling S256 PKCE token verification allows you to mitigate authorization code interception attacks during OIDC authentication flows.

Anexo: Solução de problemas

Se você estiver enfrentando problemas ao testar a conexão com o servidor Keycloak, primeiro verifique as opções de configuração do seu cliente OIDC. Você também pode inspecionar os logs do Rancher para ajudar a identificar o que está causando os problemas. Os logs de depuração podem conter informações mais detalhadas sobre o erro. Por favor, consulte Como posso habilitar o registro de depuração nesta documentação.

Todas as entradas de log relacionadas ao Keycloak são precedidas por [generic oidc] ou [keycloak oidc].

Você não é redirecionado para o Keycloak.

Quando você preenche o formulário Configurar uma conta OIDC do Keycloak e clica em Habilitar, você não é redirecionado para seu IdP.

Verifique a configuração do seu cliente Keycloak.

Os Issuer e Auth Endpoint gerados estão incorretos

No formulário Configurar uma conta OIDC do Keycloak, altere Endpoints para Specify (advanced) e substitua os valores de Issuer e Auth Endpoint. Para encontrar os valores, vá para o console do Keycloak e selecione Configurações do Domínio, selecione a aba Geral e clique em Configuração do Endpoint OpenID. A saída JSON exibe valores para issuer e authorization_endpoint.

Erro do Keycloak: "Invalid grant_type"

Em alguns casos, esta mensagem de erro pode ser enganosa e é causada por configurar o Valid Redirect URI incorretamente.

Não é possível ver grupos ao atribuir funções globais.

Se você usar um usuário que não faz parte de nenhum grupo para a configuração inicial, então não poderá pesquisar grupos ao tentar atribuir uma função global. Para resolver isso, você pode:

  1. Editar manualmente o objeto authconfig/keycloakoidc para habilitar a pesquisa de grupos.

    1. No servidor Rancher:

        kubectl edit authconfigs.management.cattle.io keycloakoidc

    2. Defina groupSearchEnabled: true.

    3. Grave as mudanças feitas.

  2. Reconfigure sua configuração do Keycloak OIDC usando um usuário que esteja atribuído a pelo menos um grupo no Keycloak.

Configurando o logout único OIDC (SLO)

Rancher supports the ability to configure OIDC Single Logout (SLO). Options include logging out of the Rancher application only, logging out of Rancher and registered applications tied to the external authentication provider, or a prompt asking the user to choose between the previous options.

Prerequisites

Before configuring OIDC SLO, ensure the following is set up on your IdP:

  • SLO Support: The Log Out behavior configuration section only appears if your OIDC IdP allows for OIDC SLO.

  • Post-Logout Redirect URI: Your Rancher Server URL must be configured as an authorized post-logout redirect URI in your IdP’s OIDC client settings. This URL is used by the IdP to redirect a user back to Rancher after a successful external logout.

OIDC SLO Configuration

Configure the SLO settings when setting up or editing your OIDC authentication provider.

  1. Sign in to Rancher using a standard user or an administrator role.

  2. In the top left corner, select ☰ > Users & Authentication.

  3. In the left navigation menu, select Auth Provider.

  4. Under the section Log Out behavior, choose the appropriate SLO setting as described below:

    Setting Description

    Log out of Rancher and not authentication provider

    Choosing this option will only logout the Rancher application and not external authentication providers.

    Log out of Rancher and authentication provider (includes all other applications registered with authentication provider)

    Choosing this option will logout Rancher and all external authentication providers along with any registered applications linked to the provider.

    Allow the user to choose one of the above in an additional log out step

    Choosing this option presents users with a choice of logout method as described above.

  5. If you choose to log out of your IdP, provide an End Session Endpoint. Rancher uses this URL to initiate the external logout.

How to get the End Session Endpoint

The end_session_endpoint is one of the specific URLs published within a standardized JSON object containing the IdP’s metadata and is retrieved from the OIDC Discovery URL. To get the end_session_endpoint from the OIDC Discovery URL, follow these steps:

  1. Obtain the Discovery URL by appending the IdP Issuer URL with the well-known path (.well-known/openid-configuration).

  2. Send an HTTP GET request to the Discovery URL.

  3. In the JSON object, look for the key named end_session_endpoint and retrieve the URL.

    You can also use a curl command to retrieve end_session_endpoint:

    curl -s <ISSUER_URL>/.well-known/openid-configuration | jq '.end_session_endpoint'