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 (SAML)

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.

Pré-requisitos

  • Você deve ter um Servidor IdP Keycloak configurado.

  • No Keycloak, crie um novo cliente SAML, com as configurações abaixo. Consulte a documentação do Keycloak para obter ajuda.

    Configuração Valor

    Sign Documents

    ON 1

    Sign Assertions

    ON 1

    Todas as outras ON/OFF Configurações

    OFF

    Client ID

    Ou https://yourRancherHostURL/v1-saml/keycloak/saml/metadata ou o valor configurado no Entry ID Field da configuração do Keycloak do Rancher2

    Client Name

    (ex. rancher)

    Client Protocol

    SAML

    Valid Redirect URI

    https://yourRancherHostURL/v1-saml/keycloak/saml/acs

    1: Opcionalmente, você pode habilitar uma ou ambas essas configurações. 2: Os metadados SAML do Rancher não serão gerados até que um provedor SAML seja configurado e salvo.

    keycloak saml client configuration

  • No novo cliente SAML, crie Mapeadores para expor os campos dos usuários

    • Adicione todos os "Mapeadores de Protocolo Integrados"

      keycloak saml client builtin mappers

    • Crie um novo mapeador "Lista de Grupos" para mapear o atributo de membro para os grupos de um usuário

      keycloak saml client group mapper

Obtendo os Metadados do IdP

  • Keycloak 5 e anteriores

  • Keycloak 6-13

  • Keycloak 14+

Para obter os metadados do IdP, exporte um arquivo metadata.xml do seu cliente Keycloak. Na aba Instalação, escolha a opção de formato Metadados SAML IDPSSODescriptor e baixe seu arquivo.

  1. Na seção Configurar, clique na guia Configurações do Domínio.

  2. Clique na guia Geral.

  3. No campo Pontos de Extremidade, clique em Metadados do Provedor de Identidade SAML 2.0.

Verifique se os metadados do IDP contêm os seguintes atributos:

xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

Alguns navegadores, como o Firefox, podem renderizar/processar o documento de forma que o conteúdo pareça ter sido modificado, e alguns atributos podem parecer estar ausentes. Nessa situação, use os dados da resposta bruta que podem ser encontrados usando seu navegador.

O seguinte é um exemplo de processo para o Firefox, mas pode variar ligeiramente para outros navegadores:

  1. Pressione F12 para acessar o console de desenvolvedor.

  2. Clique na guia Rede.

  3. Na tabela, clique na linha contendo descriptor.

  4. No painel de detalhes, clique na guia Resposta.

  5. Copie os dados da resposta bruta.

O XML obtido contém EntitiesDescriptor como o elemento raiz. O Rancher espera que o elemento raiz seja EntityDescriptor em vez de EntitiesDescriptor. Portanto, antes de passar este XML para o Rancher, siga estas etapas para ajustá-lo:

  1. Copie todos os atributos de EntitiesDescriptor para o EntityDescriptor que não estejam presentes.

  2. Remova a tag <EntitiesDescriptor> do início.

  3. Remova o </EntitiesDescriptor> do final do XML.

Você ficará com algo semelhante ao exemplo abaixo:

<EntityDescriptor xmlns="urn:oasis:names:tc:SAML:2.0:metadata" xmlns:dsig="http://www.w3.org/2000/09/xmldsig#" entityID="https://{KEYCLOAK-URL}/auth/realms/{REALM-NAME}">
....
</EntityDescriptor>

  1. Na seção Configurar, clique na guia Configurações do Domínio.

  2. Clique na guia Geral.

  3. No campo Pontos de Extremidade, clique em Metadados do Provedor de Identidade SAML 2.0.

Verifique se os metadados do IDP contêm os seguintes atributos:

xmlns:md="urn:oasis:names:tc:SAML:2.0:metadata"
xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
xmlns:ds="http://www.w3.org/2000/09/xmldsig#"

Alguns navegadores, como o Firefox, podem renderizar/processar o documento de forma que o conteúdo pareça ter sido modificado, e alguns atributos podem parecer estar ausentes. Nessa situação, use os dados da resposta bruta que podem ser encontrados usando seu navegador.

O seguinte é um exemplo de processo para o Firefox, mas pode variar ligeiramente para outros navegadores:

  1. Pressione F12 para acessar o console de desenvolvedor.

  2. Clique na guia Rede.

  3. Na tabela, clique na linha contendo descriptor.

  4. No painel de detalhes, clique na guia Resposta.

  5. Copie os dados da resposta bruta.

Configurando o Keycloak no Rancher

  1. No canto superior esquerdo, clique em ☰ > Usuários e Autenticação.

  2. No menu de navegação à esquerda, clique em Provedor de Autenticação.

  3. Clique em Keycloak SAML.

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

  5. Após completar o formulário Configurar uma Conta 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 a 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 Keycloak. Seus usuários agora podem fazer login no Rancher usando seus logins do Keycloak.

Advertências do Provedor SAML

  • Usuários e grupos não são validados quando você atribui permissões a eles no Rancher.

  • Ao adicionar usuários, os IDs exatos dos usuários (ou seja, UID Field) devem ser inseridos corretamente. Enquanto você digita o ID do usuário, não haverá busca por outros IDs de usuários que possam corresponder.

  • Ao adicionar grupos, você deve selecionar o grupo no menu suspenso ao lado da caixa de texto. O Rancher assume que qualquer entrada da caixa de texto é um usuário.

  • O menu suspenso de grupos mostra apenas os grupos dos quais você é membro. No entanto, se você tiver permissões de Administrador ou permissões de Administrador restritas, poderá ingressar em um grupo do qual não é membro.

Referência de configuração

Campo Descrição

Campo Nome de Exibição

O atributo que contém o nome de exibição dos usuários.

Exemplo: givenName

Campo Nome de Usuário

O atributo que contém o nome de usuário/nome dado.

Exemplo: email

Campo UID

Um atributo que é único para cada usuário.

Exemplo: email

Campo Grupos

Faça entradas para gerenciar associações a grupos.

Exemplo: member

Campo de ID da Entidade

O ID que precisa ser configurado como um ID de cliente no cliente Keycloak.

Padrão: https://yourRancherHostURL/v1-saml/keycloak/saml/metadata

Host da API do Rancher

A URL do seu Servidor Rancher.

Chave Privada / Certificado

Um par chave/certificado para criar um shell seguro entre o Rancher e seu IdP.

IDP-metadata

O arquivo metadata.xml que você exportou do seu servidor IdP.

Você pode gerar um par chave/certificado usando um comando openssl. Por exemplo:

openssl req -x509 -sha256 -nodes -days 365 -newkey rsa:2048 -keyout myservice.key -out myservice.cert

Anexo: Solução de problemas

Se você estiver enfrentando problemas ao testar a conexão com o servidor Keycloak, verifique primeiro a opção de configuração do seu cliente SAML. Você também pode inspecionar os logs do Rancher para ajudar a identificar a causa do problema. 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.

Você não é redirecionado para o Keycloak

Quando você clica em Autenticar com o Keycloak, você não é redirecionado para o seu IdP.

  • Verifique a configuração do seu cliente Keycloak.

  • Certifique-se de que Force Post Binding esteja definido como OFF.

Mensagem de acesso negado exibida após o login no IdP

Você é redirecionado corretamente para a página de login do seu IdP e consegue inserir suas credenciais, no entanto, você recebe uma mensagem Forbidden em seguida.

  • Verifique o log de depuração do Rancher.

  • Se o log exibir ERROR: either the Response or Assertion must be signed, certifique-se de que Sign Documents ou Sign assertions esteja definido como ON no seu cliente Keycloak.

HTTP 502 ao tentar acessar /v1-saml/keycloak/saml/metadata

Isso geralmente se deve ao fato de que os metadados não são criados até que um provedor SAML seja configurado. Tente configurar e salvar o Keycloak como seu provedor SAML e, em seguida, acessar os metadados.

Erro do Keycloak: "Desculpe, falha ao processar resposta"

  • Verifique o log do seu Keycloak.

  • Se o log exibir failed: org.keycloak.common.VerificationException: Client does not have a public key, defina Encrypt Assertions como OFF no seu cliente Keycloak.

Erro do Keycloak: "Desculpe, solicitante inválido"

  • Verifique o log do seu Keycloak.

  • Se o log exibir request validation failed: org.keycloak.common.VerificationException: SigAlg was null, defina Client Signature Required como OFF no seu cliente Keycloak.

Popularidade da Comunidade CNI

Configurando o Logout Único SAML (SLO)

Rancher supports the ability to configure SAML 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. The steps below outline configuration from the application GUI:

The Log Out behavior configuration section only appears if the SAML authentication provider allows for SAML SLO.

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

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

  3. In the left navigation menu, click 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.

Permissões de Grupo SAML e OpenLDAP

When you configure a SAML authentication provider backed by OpenLDAP, the SAML response might return only a subset of the groups that a user belongs to. The exact groups returned depend on the configuration of your external authentication provider.

Rancher assigns user permissions based strictly on the groups provided in the SAML response.

Even if you can search for and view specific OpenLDAP groups in the Rancher UI, you cannot use them to assign permissions if they are missing from the SAML response.

To assign permissions successfully, verify that your SAML authentication provider is configured to return all necessary OpenLDAP groups.