Configurar o login com Keycloak (SSO)
Caminho: Opa! Store → Keycloak → Instalar
Visão geral
O app Keycloak permite que os usuários entrem no Opa! Suite com as credenciais do Keycloak da empresa, sem digitar a senha do Opa! Suite. Esse tipo de acesso é chamado de login único, ou SSO (Single Sign-On).
Além do login, o Keycloak pode definir o grupo de permissões de cada usuário no Opa! Suite, a partir dos grupos ou funções que o usuário tem no Keycloak. Se você quiser, o Opa! Suite também cria automaticamente o usuário no primeiro login.
Pré-requisitos
- Permissão para visualizar o Opa! Store no seu grupo de permissões.
- Acesso de administrador ao Keycloak da empresa.
- Grupos de permissões do tipo sistema já criados no Opa! Suite, para o mapeamento. Veja Grupo de permissões.
- Nenhum outro app de SSO instalado. O Opa! Suite aceita um app de SSO por vez.
Passo a passo
1. Criar o cliente no Keycloak
- No console de administração do Keycloak, no realm da empresa, acesse Clients e clique em Create client.
- Escolha o tipo OpenID Connect e informe um Client ID (ex.: "opa-suite").
- Ative Client authentication e deixe marcado o Standard flow.
- Em Valid redirect URIs, informe o endereço abaixo, trocando pelo endereço do seu Opa! Suite:
https://endereco-do-seu-opa-suite/auth/login/sso/callback/keycloak - Salve e copie o segredo do cliente na aba Credentials.
- Se for mapear permissões, configure no cliente um mapeador que envie os grupos ou funções do usuário nas informações do usuário (userinfo). É o nome desse dado que vai no campo Claim name.
As URLs do realm seguem este padrão (documentação do Keycloak):
| URL | Endereço |
|---|---|
| Autenticação | https://seu-keycloak/realms/seu-realm/protocol/openid-connect/auth |
| Token | https://seu-keycloak/realms/seu-realm/protocol/openid-connect/token |
| Recursos (dados do usuário) | https://seu-keycloak/realms/seu-realm/protocol/openid-connect/userinfo |
Em versões antigas, os endereços podem ter /auth antes de /realms. Confira o endereço do seu servidor.
2. Instalar o app no Opa! Suite
- Acesse Opa! Store e abra o app Keycloak, na categoria SSO.
- Clique em Instalar. A janela Instalar Keycloak abre com quatro etapas.
- Na etapa Credenciais do cliente OAuth, preencha ID do cliente e Chave secreta do cliente. Clique em Continuar.
- Na etapa Configure as URLs do seu servidor, preencha URL de autenticação, URL de token e URL de recursos. Clique em Continuar.
- Na etapa Campos de identificação, preencha:
- Campo de identificação do usuário: o dado que identifica o usuário na resposta do Keycloak. Use
email, porque o Opa! Suite procura o usuário pelo e-mail. - Scopes: as permissões pedidas ao Keycloak no login (ex.:
openid profile email). - Claim name (opcional): o caminho dos grupos ou funções na resposta do Keycloak. Use pontos para níveis aninhados (ex.:
roles.domain.teams).
- Campo de identificação do usuário: o dado que identifica o usuário na resposta do Keycloak. Use
- Clique em Continuar.
- Na etapa Mapeamento de permissões, configure:
- Criar usuário automaticamente se não existir: ative para o Opa! Suite criar o usuário no primeiro login.
- Grupo de permissões padrão: o grupo usado quando o usuário não tem nenhuma permissão mapeada. Obrigatório quando a criação automática está ativa.
- Pares de Permissão Keycloak e Grupo de permissões: escreva o nome do grupo ou função como vem do Keycloak e escolha o grupo de permissões correspondente no Opa! Suite. Adicione quantos pares precisar.
- Clique em Instalar SSO Keycloak.
Resultado esperado
O app aparece como instalado e o Opa! Suite abre a tela de ajustes, com as seções Dados de integração e Mapeamento de permissões.
Na tela de login do Opa! Suite passa a aparecer, abaixo de Entrar, o texto ou entre com e o botão SSO. Ao clicar, o usuário é levado para o login do Keycloak e, depois de autenticado, volta ao Opa! Suite já conectado.
A cada login pelo Keycloak, o Opa! Suite:
- Procura o usuário pelo e-mail.
- Define o grupo de permissões pelo primeiro grupo do usuário no Keycloak que tenha correspondência no mapeamento. Sem correspondência, usa o Grupo de permissões padrão.
- Atualiza o nome do usuário com o nome que vem do Keycloak e deixa o usuário ativo.
- Se o usuário não existir e a criação automática estiver ativa, cria o usuário, desde que haja licença de usuário livre.
O login com Keycloak também segue as regras de segurança do login comum: autenticação em dois fatores, limite de usuários conectados e restrição de acesso por IP.
O grupo de permissões definido pelo mapeamento substitui o que estiver no cadastro do usuário no Opa! Suite. Para mudar a permissão de alguém, altere o grupo no Keycloak ou o mapeamento.
Configurações disponíveis
Para alterar, acesse Opa! Store → Keycloak → Acessar.
| Seção | Campos |
|---|---|
| Dados de integração | Client ID, Client Secret, URL de autenticação, URL de token, URL de recursos, Campo de identificação do usuário, Scopes e Claim name. |
| Mapeamento de permissões | Criar usuário automaticamente se não existir, Grupo de permissões padrão e os pares Permissão Keycloak e Grupo de permissões. |
Para remover o login com Keycloak, clique em Desinstalar App e confirme em Desinstalar.
Problemas comuns
| Sintoma ou mensagem | O que verificar |
|---|---|
| "Não foi possível criar seu usuário. Entre em contato com um administrador do sistema." | O Opa! Suite não encontrou grupo de permissões para o usuário. Confira o Claim name, os pares do mapeamento e o Grupo de permissões padrão. |
| "Seu usuário não foi encontrado. Entre em contato com um administrador do sistema." | O usuário não existe no Opa! Suite e a criação automática está desativada. |
| "Quantidade de usuários ultrapassou o limite contratado!" | Não há licença livre para criar o usuário, ou o limite de usuários conectados foi atingido. |
| "Não foi possível realizar o login com este provedor. Entre em contato com o administrador do sistema." | A resposta do Keycloak não trouxe o Campo de identificação do usuário configurado. Confira o campo e os Scopes. |
| "Houve um erro ao coletar os dados do seu usuário. Tente novamente mais tarde." | O Keycloak recusou a troca de dados. Confira o ID do cliente, a Chave secreta do cliente e as URLs. |
| A página do app mostra "Um app desta categoria já está instalado" | Já existe outro app de SSO instalado. Desinstale-o antes de instalar o Keycloak. |
Boas práticas
- Use um Grupo de permissões padrão com o mínimo de acesso, para quem ainda não tem grupo mapeado.
- Mapeie todos os grupos do Keycloak que precisam de acesso diferente, para ninguém cair no grupo padrão por engano.
- Teste o login com um usuário de cada grupo antes de liberar para a equipe.