SSO e SCIM
Ordem de configuração do login com a conta corporativa (IdP) e da sincronização automática de usuários.
Ao conectar o IdP usado pela sua empresa (Okta, Microsoft Entra ID, Google Workspace etc.) ao Keural, os colaboradores fazem login com a conta corporativa e entram automaticamente na organização no primeiro login.
A especificação para o responsável pelo IdP e para desenvolvedores está em Especificação de SSO e SCIM.
Pré-requisitos
| Item | Motivo |
|---|---|
| A conta de proprietário da organização no Keural | Somente o proprietário pode alterar as configurações de SSO. |
| Permissão de administrador no IdP | Necessária para criar um aplicativo do Keural no IdP. |
| Permissão de gerenciamento de DNS do domínio da empresa | A posse do domínio é verificada com um registro TXT. |
Métodos suportados
| Método | Uso |
|---|---|
| OpenID Connect (OIDC) | Login com conta corporativa |
| SAML 2.0 | Login com conta corporativa. As requisições de autenticação usam Redirect e as respostas são recebidas por HTTP-POST. |
| SCIM 2.0 | Reflete automaticamente nas contas do Keural as inclusões e desativações de usuários feitas no IdP |
Escolha OIDC ou SAML. Se o seu IdP oferecer os dois, recomendamos OIDC, pois a configuração é mais simples.
Ordem de configuração
- Verifique o domínio da empresa
- Crie um aplicativo no seu IdP
- Informe os valores no Keural e salve
- Ative o SSO e teste o login
- Conecte o SCIM (opcional)
Todas as configurações são feitas em Gerenciamento da organização → Configurações de SSO.
1. Verifique o domínio da empresa
Primeiro, verifique a posse do domínio de e-mail que será usado no SSO. Um domínio não verificado não é salvo no passo 3.
Digite o domínio da sua empresa (por exemplo, acme.com) em Domínios da organização e clique em Adicionar domínio.
Clique em Verificar na linha do domínio. A janela Verificar domínio exibe o Valor do registro TXT (keural-verify=…). Copie o valor.
Na página de gerenciamento de DNS, adicione um registro TXT a esse domínio e cole o valor copiado. O host (nome) é o próprio domínio (normalmente @).
Volte ao Keural e clique em Confirmar verificação. Quando Verificado for exibido, a verificação está concluída. A propagação do DNS pode levar dezenas de minutos, então, se falhar, aguarde um pouco e clique novamente.
Se você tiver vários domínios da empresa, adicione e verifique cada um. Domínios de e-mail públicos, como gmail.com, não podem ser usados.
2. Crie um aplicativo no seu IdP
No topo de Configurações de SSO, escolha OpenID Connect (OIDC) ou SAML 2.0 em Protocolo. Os valores do Keural que devem ser cadastrados no IdP são exibidos. Informe-os no aplicativo do IdP e copie os valores que o IdP emitir.
| Direção | Item | Detalhes |
|---|---|---|
| Keural → IdP | URI de callback | Informe no URI de redirecionamento do aplicativo no IdP. |
| IdP → Keural | URL do emissor (Issuer URL) | O endereço do emissor do seu IdP. |
| IdP → Keural | Client ID · Client Secret | Valores emitidos ao criar o aplicativo no IdP. |
O login só é concluído se o IdP estiver configurado para enviar o e-mail do usuário.
| IdP | Onde criar | Campo para o URI de callback | URL do emissor |
|---|---|---|---|
| Okta | Applications → Create App Integration → OIDC · Web Application | Sign-in redirect URIs | https://<domínio do Okta> |
| Microsoft Entra ID | App registrations → New registration | Redirect URI (Web) | https://login.microsoftonline.com/<ID do locatário>/v2.0 |
| Google Workspace | Console do Google Cloud → APIs e serviços → Credenciais → ID do cliente OAuth (aplicativo da Web) | URIs de redirecionamento autorizados | https://accounts.google.com |
- Microsoft Entra ID: o Client Secret é o Value de um segredo criado em Certificates & secrets. Em Token configuration, adicione a declaração opcional
emailao ID token. - Okta: em Assignments do aplicativo, indique os usuários ou grupos que vão usar o Keural.
3. Informe os valores no Keural e salve
- Informe os valores do IdP que você recebeu no passo 2.
- Em Domínios de e-mail, informe os domínios verificados no passo 1, separados por vírgula. Quando alguém fizer login com um e-mail desses domínios, será direcionado para a página de login corporativo.
- Defina Criar usuários automaticamente no primeiro login (JIT). Se ativado, os colaboradores sem conta no Keural recebem uma conta no primeiro login por SSO. Se desativado, apenas quem já tem conta consegue fazer login.
- Clique em Salvar.
No OIDC, se o IdP não fornecer os endereços padrão (discovery), informe os endpoints manualmente em Abrir configurações avançadas. Na maioria dos IdPs, deixe em branco.
4. Ative o SSO e teste o login
- Ative Ativar SSO e clique em Salvar.
- Clique em Testar login. A página de login corporativo será aberta em uma nova janela.
- Faça login com a sua conta corporativa e volte ao Keural. Ao retornar ao Keural, a conexão está concluída.
O teste de login só funciona com o SSO ativado. Se houver algum problema, desative Ativar SSO e salve. Enquanto isso, os colaboradores desse domínio fazem login por link enviado por e-mail.
Login dos colaboradores
- Informe o e-mail corporativo na tela de login do Keural. Você será direcionado para a página de login corporativo e, após fazer login, voltará ao Keural.
- No app de desktop, faça login por link enviado por e-mail, em vez da página corporativa.
- Os colaboradores que fazem login por SSO pela primeira vez entram na organização como membros. Os papéis de administrador são definidos em Gerenciamento da organização.
Nos casos abaixo, o login funciona, mas a pessoa não entra automaticamente na organização:
- Todos os assentos adquiridos pela organização estão ocupados
- A conta já pertence a outra organização
5. Conecte o SCIM (opcional)
Ao conectar o SCIM, as inclusões e desativações de usuários feitas no IdP são refletidas imediatamente nas contas do Keural. Configure-o após concluir a conexão do SSO.
Em Provisionamento SCIM, ative Ativar provisionamento SCIM.
Clique em Emitir token e copie o token. Ele é exibido somente nesse momento.
Informe a URL base do SCIM (URL do tenant) e o token nas configurações de provisionamento do IdP. O método de autenticação é token Bearer.
| IdP | Onde informar |
|---|---|
| Okta | Application → Provisioning → SCIM connector base URL; Authentication Mode em HTTP Header |
| Microsoft Entra ID | Enterprise application → Provisioning → Automatic → Tenant URL · Secret Token |
As ações feitas no IdP são refletidas no Keural da seguinte forma:
| No IdP | No Keural |
|---|---|
| Atribuir um usuário | Cria uma conta e a adiciona à organização. O nome de usuário é o e-mail. |
| Desativar um usuário ou remover a atribuição | Suspende a conta e bloqueia o login. Os dados não são apagados. |
| Reativar | Remove a suspensão. |
| Adicionar ou remover do grupo Keural Admins | Promove o usuário a administrador ou o rebaixa a membro. O proprietário não muda. |
Se perder o token, clique em Reemitir token e informe o novo token no IdP. O token anterior fica inválido imediatamente.
Solução de problemas
| Sintoma | Ação |
|---|---|
| Os domínios de e-mail não são salvos | Confirme que concluiu a verificação de domínio do passo 1 e que o domínio não é um domínio de e-mail público. |
| A verificação de domínio falha | Confirme que informou o valor TXT completo, a partir de keural-verify=. Aguarde a propagação do DNS e clique novamente. |
| Ao clicar em Testar login, a página corporativa não abre | Confirme que ativou Ativar SSO e que salvou. |
| Depois de fazer login na empresa, você volta à tela de login do Keural | Em OIDC, revise o URI de callback, a URL do emissor, o Client Secret e a declaração de e-mail. Em SAML, revise o EntityID do SP, a URL do ACS, o certificado e o atributo de e-mail. |
| O login é recusado porque a conta não existe | Criar usuários automaticamente no primeiro login (JIT) está desativado. Ative-o ou convide o colaborador antes. |
| O login funciona, mas o workspace da organização não aparece | Confirme que há assentos disponíveis e que a conta não pertence a outra organização. |
| Ao abrir o aplicativo pelo portal do IdP, o login falha (SAML) | Comece pela tela de login do Keural, informando o e-mail corporativo. |
| O teste de conexão do SCIM falha | Informe novamente a Base URL e o token. Se você reemitiu o token, substitua-o pelo novo. |