Logon único do Keycloak

Last reviewed 2024-04-29 UTC

Neste guia, mostramos como configurar o logon único (SSO) entre o Keycloak e sua conta do Cloud Identity ou do Google Workspace usando a federação SAML. O documento presume que você tenha instalado e esteja usando o Keycloak.

Objetivos

  • Configure seu servidor Keycloak para que ele possa ser usado como um provedor de identidade (IdP, na sigla em inglês) pelo Cloud Identity ou pelo Google Workspace.
  • Configure sua conta do Cloud Identity ou do Google Workspace para que ele use o Keycloak para SSO.

Antes de começar

  1. Se você não tiver uma conta do Cloud Identity, inscreva-se em uma conta.
  2. Verifique se sua conta do Cloud Identity tem privilégios de superadministrador.
  3. Se seu servidor Keycloak for usado para gerenciar mais de um realm, decida qual deles você quer usar para a federação.
  4. Verifique se você tem acesso de administrador ao realm selecionado.

Criar um perfil SAML

Para configurar o Logon único com o Keycloak, primeiro crie um perfil SAML na sua conta do Cloud Identity ou do Google Workspace. O perfil SAML contém as configurações relacionadas ao servidor Keycloak, incluindo o URL e o certificado de assinatura.

Posteriormente, você atribuirá o perfil SAML a determinados grupos ou unidades organizacionais.

Para criar um novo perfil SAML na sua conta do Cloud Identity ou do Google Workspace, faça o seguinte:

  1. No Admin Console, acesse Segurança > Autenticação > SSO com o IdP de terceiros.

    Acessar SSO com o IdP de terceiros

  2. Clique em Perfis de SSO de terceiros > Adicionar perfil SAML.

  3. Na página SAML SSO profile, digite as seguintes configurações:

    • Name: Keycloak

    • ID da entidade do IdP:

      Keycloak 17 ou mais recente 

      https://KEYCLOAK/realms/REALM

      Keycloak 16 ou anterior 

      https://KEYCLOAK/auth/realms/REALM

    • URL da página de login:

      Keycloak 17 ou mais recente 

      https://KEYCLOAK/realms/REALM/protocol/saml

      Keycloak 16 ou anterior 

      https://KEYCLOAK/auth/realms/REALM/protocol/saml

    • URL da página de logout:

      Keycloak 17 ou mais recente 

      https://KEYCLOAK/realms/REALM/protocol/openid-connect/logout

      Keycloak 16 ou anterior 

      https://KEYCLOAK/auth/realms/REALM/protocol/openid-connect/logout?redirect_uri=https://KEYCLOAK/auth/realms/REALM/account/

    • URL para alteração de senha:

      Keycloak 17 ou mais recente 

      https://KEYCLOAK/realms/REALM/account

      Keycloak 16 ou anterior 

      https://KEYCLOAK/auth/realms/REALM/account

    Em todos os URLs, substitua:

    • KEYCLOAK: o nome de domínio totalmente qualificado do servidor Keycloak
    • REALM: o nome do realm selecionado

    Não faça upload de um certificado de verificação ainda.

  4. Clique em Salvar.

    A página Perfil de SSO SAML contém dois URLs:

    • ID da entidade
    • URL do ACS

    Você vai precisar desses URLs na próxima seção ao configurar o Keycloak.

Configurar o Keycloak

Para configurar o servidor Keycloak, crie um cliente.

Criar um cliente

Crie um novo cliente SAML no Keycloak:

  1. Faça login no Keycloak e abra o console de administração.
  2. Selecione o realm que você quer usar para federação.
  3. No menu, selecione Clientes.
  4. Clique em Criar cliente.

  5. Defina as configurações a seguir para o cliente:

    Keycloak 19 ou versão mais recente

    • Tipo de cliente: SAML
    • ID do cliente: o URL da entidade do seu perfil de SSO.
    • Name: Google Cloud

    Keycloak 16 ou anterior

    • ID do cliente: o URL da entidade do seu perfil de SSO.
    • Protocolo do cliente: saml
    • Endpoint SAML do cliente: deixe em branco

  6. Clique em Salvar.

  7. Especifique os detalhes do cliente definindo as configurações a seguir:

    Keycloak 19 ou versão mais recente

    Na guia Configurações:

    • URIs de redirecionamento válidos: o URL do ACS do seu perfil de SSO
    • Formato de ID de nome: e-mail
    • Forçar formato de ID de nome: ativado
    • Assinar documentos: desativado
    • Declarações de assinatura: ativado

    Na guia Chaves:

    • Assinatura do cliente necessária: desativado

    Keycloak 16 ou anterior

    • Nome: um nome como Google Cloud
    • Declarações de assinatura: ativado
    • Assinatura do cliente necessária: desativado
    • Forçar formato de ID de nome: ativado
    • Formato de ID de nome: e-mail
    • URIs de redirecionamento válidos: o URL do ACS do seu perfil de SSO

    Mantenha os valores padrão para todas as outras configurações.

  8. Clique em Salvar.

Exportar o certificado de assinatura

Depois que o Keycloak autentica um usuário, ele passa uma declaração SAML para o Cloud Identity ou o Google Workspace. Para permitir que o Cloud Identity e o Google Workspace verifiquem a integridade e a autenticação dessa declaração, o Keycloak assina a declaração com uma chave de assinatura de token especial e fornece um certificado que ativa o Cloud Identity ou o Google Workspace para verificar a assinatura.

Agora, exporte o certificado de assinatura do Keycloak:

  1. No menu, selecione Configurações do realm.
  2. Selecione a guia Chaves.

  3. Encontre a linha de Algoritmo: RS256. Se tiver mais de uma linha, use aquela com Use: SIG. Em seguida, selecione Certificado.

    Será exibida uma caixa de diálogo com um certificado codificado em base64.

  4. Copie o valor do certificado codificado em base64 para a área de transferência.

Antes de usar o certificado de assinatura, você precisa convertê-lo no formato PEM ao adicionar um cabeçalho e um rodapé.

  1. Abra um editor de texto, como o Bloco de Notas ou o vim.

  2. Cole o seguinte cabeçalho, seguido por uma nova linha:

    -----BEGIN CERTIFICATE-----

  3. Cole o certificado codificado em base64 da área de transferência.

  4. Adicione uma nova linha e cole o seguinte rodapé:

    -----END CERTIFICATE-----

    Após a mudança, o arquivo vai ficar parecido com este:

    -----BEGIN CERTIFICATE-----
MIICmzCCAYMCBgF7v8/V1TANBgkq...
-----END CERTIFICATE-----

  5. Salve o arquivo em um local temporário no seu computador.

Completar o perfil de SAML

Use o certificado de assinatura para concluir a configuração do seu perfil SAML:

  1. Volte ao Admin Console e acesse Segurança > Autenticação > SSO com o IdP de terceiros.

    Acessar o SSO com o IdP de terceiros

  2. Abra o perfil SAML Keycloak que você criou anteriormente.

  3. Clique na seção Detalhes do IdP para editar as configurações.

  4. Clique em Fazer upload do certificado e escolha o certificado de assinatura de token que você salvou anteriormente.

  5. Clique em Salvar.

Seu perfil SAML está concluído, mas você ainda precisa atribuí-lo.

Atribuir o perfil SAML

Selecione os usuários a que o novo perfil SAML deve ser aplicado:

  1. No Admin Console, na página SSO com IdPs de terceiros, clique em Gerenciar atribuições do perfil de SSO > Gerenciar.

    Acessar "Gerenciar atribuições do perfil de SSO"

  2. No painel esquerdo, selecione o grupo ou a unidade organizacional em que você quer aplicar o perfil de SSO. Para aplicar o perfil a todos os usuários, selecione a unidade organizacional raiz.

  3. No painel à direita, selecione Outro perfil de SSO.

  4. No menu, selecione o perfil de SSO Keycloak - SAML criado anteriormente.

  5. Clique em Salvar.

Repita as etapas para atribuir o perfil SAML a outro grupo ou unidade organizacional.

Testar Logon único

Você concluiu a configuração do logon único. Agora, é possível verificar se o SSO está funcionando corretamente.

  1. Escolha um usuário do Keycloak que atenda aos seguintes critérios:

    • O usuário tem um endereço de e-mail.
    • O endereço de e-mail corresponde ao endereço de e-mail principal de um usuário atual em sua conta do Cloud Identity ou do Google Workspace.

    • O usuário do Cloud Identity não tem privilégios de superadministrador.

      As contas de usuário que têm privilégios de superadministrador precisam sempre fazer login usando as credenciais do Google. Por esse motivo, não são adequadas para o teste de logon único.

  2. Abra uma nova janela do navegador e acesse o Console do Google Cloud.

  3. Na página de login do Google, insira o endereço de e-mail da conta de usuário e clique em Próxima.

    Página de login do Google.

    Você será redirecionado para o Keycloak.

  4. Insira suas credenciais do Keycloak e clique em Fazer login.

    Após a autenticação, o Keycloak redireciona você de volta para o Console do Cloud. Como esse é o primeiro login desse usuário, é solicitado que você aceite os Termos de Serviço e a Política de Privacidade do Google.

  5. Se você concordar, clique em Aceitar.

  6. Você será redirecionado para o Console do Google Cloud, que solicitará a confirmação das preferências e a aceitação dos Termos de Serviço do Google Cloud. Se você concordar, clique em Sim e, em seguida, clique em Concordar e continuar.

  7. Clique no ícone do avatar e em Sair.

    Você será redirecionado para o Keycloak.

Se você tiver problemas para fazer login, lembre-se de que as contas de usuário com privilégios de superadministrador podem ignorar o SSO. Assim, você ainda poderá usar o Admin Console para verificar ou alterar as configurações.

Opcional: configurar redirecionamentos para URLs de serviço específicos do domínio

Ao criar links para o console do Google Cloud em portais ou documentos internos, é possível melhorar a experiência do usuário usando URLs de serviço específicos do domínio.

Ao contrário dos URLs de serviço comuns, como https://console.cloud.google.com/, os URLs de serviço específico de domínio incluem o nome do seu domínio principal. Os usuários não autenticados que clicam em um link para um URL de serviço específico do domínio são redirecionados imediatamente para o Keycloak em vez de ver uma página de login do Google primeiro.

Confira a seguir alguns exemplos de URLs de serviço específicos do domínio:

Serviço do Google URL Logotipo
Console do Google Cloud https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://console.cloud.google.com Logotipo do Google Cloud
Documentos Google https://docs.google.com/a/DOMAIN Logotipo do Google Docs
Planilhas Google https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://sheets.google.com Logotipo do app Planilhas Google
Google Sites https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://slides.google.com Logotipo do Google Sites
Google Drive https://drive.google.com/a/DOMAIN Logotipo do Google Drive
Gmail https://mail.google.com/a/DOMAIN Logotipo do Gmail
Grupos do Google https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://groups.google.com Logotipo dos Grupos do Google
Google Keep https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://keep.google.com Logotipo de Google Keep
Looker Studio https://www.google.com/a/DOMAIN/ServiceLogin?continue=https://lookerstudio.google.com Logotipo do Looker Studio

Para configurar URLs de serviço específicos do domínio para que redirecionem para o Keycloak, faça o seguinte:

  1. No Admin Console, na página SSO com IdPs de terceiros, clique em URLs de serviço específicos do domínio > Editar.

    Acessar URLs de serviço específicos do domínio

  2. Defina Redirecionar automaticamente os usuários para o IdP de terceiros no seguinte perfil de SSO como ativado.

  3. Defina o Perfil de SSO como Keycloak.

  4. Clique em Salvar.

Opcional: configurar desafios de login

O Login do Google pode solicitar outras verificações quando eles fizerem login em dispositivos desconhecidos ou quando a tentativa de login parecer suspeita por outros motivos. Esses desafios de login ajudam a melhorar a segurança. Recomendamos que eles fiquem ativados.

Se você achar que os desafios de login causam muito atrito, desative os desafios de login da seguinte maneira:

  1. No Admin Console, acesse Segurança > Autenticação > Desafios de login.
  2. No painel esquerdo, selecione uma unidade organizacional para desativar os desafios de login. Para desativar os desafios de login para todos os usuários, selecione a unidade organizacional raiz.
  3. Em Configurações para usuários que fazem login usando outros perfis de SSO, selecione Não solicitar verificações adicionais do Google aos usuários.
  4. Clique em Salvar.

A seguir