Como configurar o login via SSO com o Keycloak no ONLYOFFICE DocSpace

Introdução

Single Sign-on (SSO) é uma tecnologia que permite aos usuários fazer login apenas uma vez e, em seguida, obter acesso a múltiplas aplicações/serviços sem a necessidade de nova autenticação.

O SSO é sempre garantido pela operação conjunta de duas aplicações: um Provedor de Identidade e um Provedor de Serviço (também chamados de "IdP" e "SP"). O SSO do ONLYOFFICE implementa apenas o SP. Muitos provedores diferentes podem atuar como IdP, mas este artigo considera a implementação do Keycloak.

Criando um IdP no Keycloak

1. Cadastre-se no Keycloak como administrador;
2. Vá para Gerenciar domínios e selecione o domínio onde a conexão será configurada;
3. Vá para Clientes e clique no botão Criar cliente;
4. Na página que se abre, configure o seguinte: No campo Tipo de cliente, selecione SAML, no campo ID do cliente, insira https://meuportal-endereco.com/sso/metadata, substituindo meuportal-endereco.com pelo nome de domínio do seu portal. Nos campos Nome e Descrição, insira qualquer nome e descrição para o cliente.
   
5. Clique no botão Próximo;
6. Preencha os seguintes campos:
   Substitua meuportal-endereco.com pelo nome de domínio do seu portal.

   Detalhes da Aplicação
   URL Raiz	https://meuportal-endereco.com/sso
   URL Inicial	https://meuportal-endereco.com/sso
   URIs de redirecionamento válidos	https://meuportal-endereco.com/sso/slo/callback https://meuportal-endereco.com/sso/acs
   URIs de redirecionamento pós logout válidos	https://meuportal-endereco.com/sso/slo/callback
   URL de Processamento SAML Mestre	https://meuportal-endereco.com/sso/acs

   

   Preencha os seguintes campos na aba Avançado:

   URL de Binding POST do Serviço de Consumidor de Asserção	https://meuportal-endereco.com/sso/acs
   URL de Binding de Redirecionamento do Serviço de Consumidor de Asserção	https://meuportal-endereco.com/sso/acs
   URL de Binding POST do Serviço de Logout	https://meuportal-endereco.com/sso/slo/callback
   URL de Binding de Redirecionamento do Serviço de Logout	https://meuportal-endereco.com/sso/slo/callback

   
7. Clique no botão Salvar;
8. Na seção Capacidades SAML, selecione Formato de ID de Nome como email;
9. Na seção Assinatura e Criptografia, habilite a opção Assinar Asserções e selecione um algoritmo de assinatura: RSA_SHA1, RSA_SHA256 ou RSA_SHA512.
   
10. Clique no botão Salvar;
11. Vá para la seção Escopos do Cliente e clique no link com o nome do seu portal https://meuportal-endereco.com/sso/metadata-dedicated.

    Clique no botão Adicionar mapeadores predefinidos e, na janela pop-up, selecione os seguintes mapeadores:

    • X500 email;
    • X500 givenName;
    • X500 surname.

    Em seguida, clique no botão Adicionar.

    

Configurando ONLYOFFICE SP

1. Certifique-se de que você está logado como Administrador no seu ONLYOFFICE DocSpace e vá para o menu Configurações, selecione a seção Integração e abra a aba Single Sign-On;
2. Habilite o SSO usando o interruptor Habilitar Autenticação Single Sign-on e cole https://<keycloakurl>/realms/<realm_name>/protocol/saml/descriptor no campo URL para o XML de Metadados do IdP. Substitua <keycloakurl> e <realm_name> pelo endereço do seu servidor Keycloak e o nome do domínio onde a conexão foi criada. O link final deve ser acessível a partir de um navegador.
   
3. Pressione o botão com a seta para cima para carregar os metadados do IdP. O formulário de Configurações do ONLYOFFICE SP será automaticamente preenchido com seus dados do Keycloak IdP;
4. Selecione o mesmo Algoritmo de Verificação de Assinatura Padrão que o especificado no Keycloak.
   
5. Altere o Formato de NameId para emailAddress.
   
6. Agora você precisa criar um certificado na seção Certificados SP. Para isso, clique no botão Adicionar certificado na seção correspondente;
7. Na janela modal aberta, clique no link Gerar Novo Certificado Autoassinado e escolha a opção assinar e criptografar na lista Usar para. Antes de salvar o certificado, copie o texto do Certificado Público para a área de transferência e salve-o em um arquivo (será necessário para o Keycloak), em seguida, clique no botão OK.
   
8. Vá para a seção Mapeamento de Atributos e atribua os seguintes valores aos atributos:
   • Primeiro nome: urn:oid:2.5.4.42
   • Sobrenome: urn:oid:2.5.4.4
   • Email: urn:oid:1.2.840.113549.1.9.1
   

   Na seção Configurações Avançadas, você pode marcar a opção Ocultar página de autenticação para ocultar a página de autenticação padrão e redirecionar automaticamente para o serviço SSO.

   Se precisar restaurar a página de autenticação padrão (para poder acessar o portal caso seu servidor IDP falhe), você pode adicionar a chave /login?skipssoredirect=true após o nome de domínio do seu portal na barra de endereços do navegador.

9. Clique no botão Salvar;
10. Retorne ao Keycloak para configurar a criptografia, abra seu cliente e vá para a seção Chaves. Desative a opção Assinatura do cliente necessária e ative Criptografar asserções. Na janela pop-up, selecione Importar, defina o Formato do arquivo para Certificado PEM e clique no botão Procurar. Especifique o caminho para o arquivo de certificado do passo 7 e clique em Confirmar.

Verificando o funcionamento do ONLYOFFICE SP com o Keycloak IdP

1. Vá para a página de Autenticação do ONLYOFFICE DocSpace (por exemplo, https://meuportal-endereco.com/login);
2. Clique no botão Single Sign-on. Se o botão estiver ausente, isso significa que o SSO não está habilitado.
   
3. Se todos os parâmetros do SP e IdP estiverem configurados corretamente, seremos redirecionados para o formulário de login do Keycloak IdP:
   
4. Insira o login e a senha do usuário do Keycloak e clique no botão Entrar;
5. Se as credenciais estiverem corretas, seremos redirecionados para a página principal do portal (o usuário será criado automaticamente se estiver ausente, ou os dados serão atualizados se alterados no IDP).