Como usar o Keycloak para login SSO com o Couchbase Capella

Capa de chaveO Keycloak, uma solução de gerenciamento de identidade e logon único (SSO) de código aberto, oferece recursos de integração perfeita com vários aplicativos de clientes. Neste tutorial, exploraremos o processo de integração de um cliente SAML (Security Assertion Markup Language) com o Keycloak, permitindo uma autenticação de usuário conveniente e segura.

É importante observar que o Keycloak não é testado ou validado pelo Couchbase. O Couchbase fornece instruções e suporte para Microsoft Azure AD, Okta, Ping Identity, CyberArk, Google Workspace e OneLogin. 

Demonstraremos como integrar a autenticação SAML usando um provedor SAML genérico, neste caso o Keycloak. Embora qualquer provedor de SAML possa ser utilizado, é altamente recomendável usar um de nossos serviços compatíveis para obter compatibilidade ideal e uma experiência de integração perfeita.

Pré-requisitos

• • Presumo que você tenha uma instância do Keycloak em funcionamento
  • Você tem acesso ao Capella como administrador da organização
  • O SSO foi ativado para seu locatário

Etapa 1: Configurar o Keycloak

Está fora do escopo deste tutorial explicar como implantar o Keycloak como um provedor de identidade. Presumo que você já tenha uma instância do Keycloak em funcionamento e que ela esteja pronta para ser utilizada.

Criar um reino

Crie um novo reino no Keycloak para gerenciar a configuração do seu cliente SAML. Em nosso exemplo, chamaremos esse reino de "acme".

Depois que o realm for criado, precisamos salvar a chave pública. A maneira mais fácil de fazer isso é abrir o ponto de extremidade SAML Metadata. 

Obter a configuração SAML

Clique nas configurações do Realm no lado esquerdo. Isso abrirá a página de configurações do realm. Na parte inferior dessa página, há dois pontos de extremidade de Metadados. 

Você precisa clicar no ícone Metadados do provedor de identidade SAML 2.0 link. O XML contém os metadados SAML de que você precisará ao criar a configuração do Capella SSO. 

Ligação SAML HTTP-POST:

O certificado X.509:

Anote-os, pois precisaremos deles nas próximas etapas.

Etapa 2: criar um domínio no Capella

Nesta etapa, criaremos um Capella realm. Para configurar isso, precisamos copiar o certificado que salvamos na primeira etapa para o diretório Campo Certificado de assinatura SAML. Também temos que copiar o URL de vinculação HTTP_POST para o URL do ponto de extremidade de login campo.

O Algoritmo de assinatura e o Algoritmo de digestão devem ser deixados como padrão.

Certifique-se de que o campo SAML Protocol Binding esteja configurado como HTTP-POST:

Nesse ponto, você está pronto para criar o reino. 

Etapa 3: Criar um cliente SAML Keycloak

Exibir informações do Capella Realm

Neste ponto, criamos o Capella Realm. Agora, estamos prontos para criar um cliente SAML no Keycloak.

Primeiro, precisamos de algumas informações sobre o reino do Capella. Clique no nome do reino recém-criado no Capella para exibir as informações do reino.

Será necessário copiar várias informações dessa tela para o Keycloak durante o processo de criação do cliente. Anote os seguintes campos.

• • Nome do reino
  • ID da entidade
  • URL de retorno de chamada
  • Certificado de assinatura

Criar o cliente SAML do Keycloak

Abra o console de administração do Keycloak e selecione o reino que você criou anteriormente. No lado esquerdo da navegação, clique em Clientes.

Nessa tela, clique em Criar cliente:

Copiar o ID da entidade da Capella e cole-o no campo Client ID do keycloak. Você pode usar qualquer nome que desejar no campo Nome campo. 

Quando estiver pronto, clique no botão Next. Nessa tela, você precisa inserir o URL inicial e os URIs de redirecionamento, conforme mostrado na captura de tela:

O novo cliente SAML será criado no Keycloak quando você clicar no botão Salvar botão.

Configurar o cliente SAML do Keycloak

Você precisa abrir o cliente SAML que criou e clicar no botão Avançado tab. Isso o levará a uma tela como esta:

Nessa tela, você só precisa preencher os campos URL de vinculação POST do serviço de consumidor de asserção. Você precisa copiar o URL de retorno de chamada da página Realm da Capella e inseri-lo nesse campo.

Importar assinaturas de clientes

Por padrão Assinatura do cliente necessária está ativado no Keycloak. Nesse caso, o Keycloak validará a solicitação SAML. Para fazer isso, precisamos salvar a chave pública SAML do Capella e importá-la para o Keycloak. 

Primeiro, precisamos salvar o certificado da Capella. Abra sua página de configurações de SSO no Capella. 

Abra a URL mostrada como Certificado de assinatura https://couchbase-capella.us.auth0.com/pem?cert=connection em uma nova guia. Isso acionará um download. O arquivo será chamado couchbase-capella.pem. Esse certificado é usado para verificar a assinatura na asserção SAML que é enviada ao Keycloak. Ele não é o mesmo que o certificado de segurança do banco de dados do Couchbase.

Agora você precisa fazer login novamente no Keycloak e abrir o cliente que criou anteriormente. Vá para a seção Chaves guia. 

• • Clique em o Chave de importação botão.
  • Selecione Certificado PEM na seção Formato de arquivo lista suspensa. 
  • Clique em browse para selecionar o arquivo e localize o arquivo que você acabou de salvar do Capella

• • Clique em Importar para carregar o certificado da Capella no Keycloak

Etapa 4: Configurar mapeadores SAML

Agora o cliente SAML está pronto. Na próxima etapa, configuraremos os mapeadores SAML necessários que permitirão que o Capella leia os detalhes do usuário a partir da asserção quando o usuário estiver fazendo login.

Abra o cliente SAML que acabamos de criar e clique no botão Escopos do cliente guia:

Você deverá ver um escopo de cliente com o nome do seu ID de cliente e um traço e um dedicado. Você precisa clicar nesse link para adicionar mapeadores personalizados.

Depois de clicar nesse botão, você verá a tela a seguir:

Adicionar o mapeador de sobrenome

• • Clique em adicionar configurar um novo mapeador botão
  • Selecione Propriedade do usuário na lista de mapeadores.

• • Preencha o formulário usando os seguintes valores:
    Nome: Sobrenome X500
    Propriedade: lastName
    Nome amigável: sobrenome
    Nome do atributo SAML: family_name
    SAML Attribute NameFormat (Formato de nome de atributo SAML):  Não especificado
    

Clique em salvar. Depois de ver a mensagem de confirmação, você precisa clicar no botão Escopos dedicados para adicionar o próximo mapeador.

Agora estamos prontos para adicionar o próximo mapeador.

Adicionar o mapeador firstName

• • Clique no botão Adicionar mapeador  e selecione Por configuração. 
  • Selecione Propriedade do usuário na lista de mapeadores.

• • Preencha o formulário usando os seguintes valores:
    Nome: X500 givenName
    Propriedade: firstName
    Nome amigável: givenName
    Nome do atributo SAML: given_name
    SAML Attribute NameFormat (Formato de nome de atributo SAML):  Não especificado
    

Clique em salvar. Depois de ver a mensagem de confirmação (Mapeamento criado com sucesso), você precisa clicar no botão Escopos dedicados para adicionar o próximo mapeador.

Agora estamos prontos para adicionar o mapeador final.

Adicionar o mapeador de e-mail

• • Clique no botão Adicionar mapeador  e selecione Por configuração. 
  • Selecione Propriedade do usuário na lista de mapeadores.

• • Preencha o formulário usando os seguintes valores:
    Nome: E-mail X500
    Propriedade: e-mail
    Nome amigável: e-mail
    Nome do atributo SAML: e-mail
    SAML Attribute NameFormat (Formato de nome de atributo SAML):  Não especificado

Clique em salvar. Depois de ver a mensagem de confirmação, você precisa clicar no botão Escopos dedicados para ver a lista completa de mapeadores. Nesse momento, você deverá ver todos os três.

Etapa 5: Testar a integração

Para começar a testar, você precisa de pelo menos um usuário em seu domínio. Você pode usar usuários existentes ou criar um usuário apenas para testar a integração. Além disso, certifique-se de estar desconectado da Capella antes de iniciar o teste.

• • Aberto https://cloud.couchbase.com 

• • Clique em Usar Logon único
  • Digite seu nome de domínio Capella SSO

Depois de inserir o nome do locatário, você será encaminhado para o Keycloak. Você precisará usar seu usuário de teste e credencial para fazer login. No final do fluxo de login, você será conectado ao Capella. 

Observação: a Capella utiliza o provisionamento de usuários JIT. A Capella criará um usuário automaticamente na primeira vez em que você fizer login com um usuário por meio de seu provedor de identidade.

Conclusão

A integração de um cliente SAML com o Keycloak permite que você aproveite os poderosos recursos de gerenciamento de identidade do Keycloak, possibilitando uma funcionalidade perfeita de logon único no Capella. Seguindo o guia passo a passo fornecido neste blog, agora você deve ter o conhecimento e as ferramentas necessárias para integrar com sucesso o Capella ao Keycloak, garantindo a autenticação segura do usuário e uma experiência de usuário simplificada.