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 OIDC Genérico

O OpenID Connect (OIDC) genérico permite que os usuários façam login no Rancher usando suas credenciais de sua conta existente em um Provedor de Identidade (IdP) OIDC. O Rancher suporta integração com o protocolo OIDC e o protocolo SAML. Ambas as implementações são funcionalmente equivalentes quando usadas com o Rancher. As seguintes instruções descrevem como criar um cliente OIDC e configurar o Rancher para trabalhar com seu provedor de autenticação. Os usuários podem então fazer login no Rancher usando o login do OIDC IdP.

Pré-requisitos

Provedor de Identidade

No Rancher, o OIDC genérico está desativado.

Consulte a documentação do seu IdP específico para completar os pré-requisitos listados.

Cliente OIDC

No seu IdP, crie um novo cliente com as configurações abaixo:

Configuração Valor

Client ID

(ex. rancher)

Name

(ex. rancher)

Client Protocol

openid-connect

Access Type

confidential

Valid Redirect URI

https://yourRancherHostURL/verify-auth

No novo cliente OIDC, crie mapeadores para expor os campos do usuário.

As declarações groups e full_group_path geradas pelos mapeadores de Grupos e Caminho de Grupo, que você cria dentro do cliente OIDC no seu Provedor de Identidade, devem ser arrays JSON, ex. "groups":["admins","devs","qa"] e "full_group_path":["/admins","/devs","/qa"].

  1. Crie um novo Groups Mapper com as configurações abaixo:

    Configuração Valor

    Name

    Groups Mapper

    Mapper Type

    Group Membership

    Token Claim Name

    groups

    Add to ID token

    OFF

    Add to access token

    OFF

    Add to user info

    ON

  2. Crie um novo Client Audience com as configurações abaixo:

    Configuração Valor

    Name

    Client Audience

    Mapper Type

    Audience

    Included Client Audience

    Add to access token

    ON

  3. Crie um novo Groups Path com as configurações abaixo.

    Configuração Valor

    Name

    Group Path

    Mapper Type

    Group Membership

    Token Claim Name

    full_group_path

    Full group path

    ON

    Add to user info

    ON

O Rancher usa o valor recebido na declaração "sub" para formar o PrincipalID, que é o identificador único no Rancher. É importante que este seja um valor único e imutável.

Configurando OIDC Genérico no Rancher

  1. No canto superior esquerdo da 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 OIDC Genérico.

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

  5. Clique em Habilitar.

    O Rancher irá redirecioná-lo para a página de login do IdP. Insira suas credenciais do IdP 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 seu provedor usando o protocolo OIDC. Seus usuários agora podem fazer login no Rancher usando o login do IdP.

Mapeamento de Reivindicações Personalizadas

O mapeamento de reivindicações personalizadas dentro da configuração OIDC Genérico é suportado para name, email e groups. Isso permite que você mapeie manualmente essas reivindicações OIDC quando seu IdP não usa nomes padrão nos tokens.

Como Funciona uma Reivindicação de Grupos Personalizados

Uma reivindicação de grupos personalizados influencia como os grupos de usuários funcionam:

  • Se tanto a reivindicação padrão OIDC groups quanto a reivindicação de grupos personalizados estiverem presentes no token do usuário, a reivindicação personalizada complementa a lista de grupos fornecida pela reivindicação padrão.

  • Se não houver uma reivindicação de grupos padrão no token, os grupos listados na reivindicação personalizada formarão os únicos grupos do usuário.

Não há funcionalidade de busca disponível para grupos provenientes de uma reivindicação personalizada. Para atribuir um papel a um desses grupos, você deve inserir manualmente o nome exato do grupo no campo RBAC.

Configurando Reivindicações Personalizadas

Quando estiver no formulário Configurar uma conta OIDC:

  1. Selecione Adicionar reivindicações personalizadas.

  2. Adicione suas reivindicações personalizadas name, email ou groups ao campo apropriado Reivindicações Personalizadas.

Por exemplo, se seu IdP enviar groups em uma reivindicação chamada custom_roles, insira custom_roles no campo Reivindicação de Grupos Personalizados. O Rancher então complementa a reivindicação padrão OIDC groups ou procura essa reivindicação específica ao processar o token do usuário.

Referência de configuração

Campo Descrição

ID do cliente

O ID do Cliente do seu cliente OIDC.

Segredo do Cliente

O segredo gerado para o seu cliente OIDC.

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 OIDC.

seguros

Escolha se deseja usar os valores gerados para os campos URL do Rancher, Emissão e Endpoint de Autenticação ou fornecer substituições manuais se estiverem incorretos.

URL do Rancher

A URL do seu Servidor Rancher.

Emissor

A URL do seu IdP. Se seu provedor tiver a descoberta habilitada, o Rancher usa a URL do Emissor para buscar todas as URLs necessárias.

Endpoint de Autenticação

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

Reivindicações Personalizadas

Campo de Reivindicação Personalizada Reivindicação OIDC Padrão Descrição da Reivindicação Personalizada

Reivindicação de Nome Personalizada

name

O nome da reivindicação no token OIDC que contém o nome completo ou o nome de exibição do usuário.

Reivindicação de Email Personalizada

email

O nome da reivindicação no token OIDC que contém o endereço de email do usuário.

Reivindicação de Grupos Personalizada

groups

O nome da reivindicação no token OIDC que contém as associações de grupos do usuário (usado para RBAC).

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.

Solução de problemas

Se você estiver enfrentando problemas ao testar a conexão com o servidor OIDC, 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 OIDC Genérico são precedidas por [generic oidc] ou [oidc].

Você não é redirecionado para seu provedor de autenticação

Se você preencher o formulário Configurar uma conta OIDC Genérica e clicar em Ativar, e não for redirecionado para seu IdP, verifique a configuração do seu cliente OIDC.

Os Issuer e Auth Endpoint gerados estão incorretos

Se os Issuer e Auth Endpoint forem gerados incorretamente, abra o formulário Configurar uma conta OIDC, mude Endpoints para Specify (advanced) e substitua o valor de Issuer.

Erro: "Invalid grant_type"

Em alguns casos, a mensagem de erro "grant_type inválido" pode ser enganosa e é, na verdade, causada pela configuração incorreta do Valid Redirect URI.

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'