Login único (SSO) com SAML

Visão geral

O login único (SSO) com SAML permite que os agentes entrem na ConversaLabs usando o provedor de identidade (IdP) da sua empresa — como Okta, Azure AD / Microsoft Entra ou Google Workspace. Em vez de cada pessoa manter uma senha separada na plataforma, a autenticação é delegada ao IdP: quem controla quem entra, e quem desliga acessos, é o seu diretório corporativo.

É um recurso premium (liberado por plano e por tipo de instalação — Cloud ou Enterprise) e fica em Configurações > Segurança.

Pré-requisitos

• Perfil de Administrador para configurar o SSO.
• Plano com o recurso SAML habilitado para a conta (premium/opcional). Se ele não estiver ativo, a área de Segurança mostra um aviso de indisponibilidade ou uma tela de upgrade.
• Tipo de instalação Cloud ou Enterprise (o SSO com SAML não aparece em outros tipos).
• O método de login SAML liberado para a conta (faz parte da configuração da plataforma).
• Um IdP compatível com SAML 2.0 (Okta, Azure AD / Entra, Google Workspace ou equivalente) onde você possa cadastrar a ConversaLabs como aplicação de serviço.

Passo a passo

1. Abra Configurações > Segurança.
2. Ative o SSO com SAML no interruptor da seção (o recurso vem como Beta).
3. Preencha os campos com os dados do seu IdP:
   • SSO URL — a URL de login (Sign-on URL) do IdP.
   • Entity ID do IdP — o identificador (Entity ID / Issuer) do seu provedor.
   • Certificado — o certificado público X.509 do IdP (cole o conteúdo no campo).
4. Salve. A plataforma valida os dados e passa a exibir os valores do lado do serviço (veja Valores do provedor de serviço (SP) abaixo).
5. No seu IdP, cadastre a ConversaLabs como aplicação usando a ACS URL e o SP Entity ID exibidos na tela e libere os agentes que devem ter acesso.

Fluxo de login (como os agentes entram via IdP)

Com o SSO ativo, a tela de login passa a oferecer a entrada via SAML. Ao escolher essa opção, o agente é levado ao IdP, autentica lá (com as políticas e o segundo fator da empresa) e retorna autenticado à plataforma. Na primeira entrada de um agente novo, a conta é provisionada automaticamente a partir dos atributos enviados pelo IdP.

Configurações & opções

• Interruptor de ativação — liga ou desliga o SSO com SAML. Desligar (ou limpar os campos e salvar) remove a configuração SAML da conta.
• SSO URL, Entity ID do IdP e Certificado — os três campos obrigatórios que descrevem o seu provedor de identidade.

Mapeamento de atributos e papéis

Para provisionar o agente corretamente, o IdP precisa enviar os atributos esperados pela plataforma:

• email
• first_name
• last_name

A seção Mapeamento de atributos (recolhível) na tela de Segurança lista esses atributos. Configure o seu IdP para enviá-los na asserção SAML. A associação de papéis/funções (qual papel o agente recebe ao entrar) é tratada pela governança de acesso da conta — combine o SSO com papéis bem definidos para controlar o que cada pessoa pode ver e fazer.

Um usuário só pode pertencer a uma conta

Com o SAML ativo, a plataforma exige que cada pessoa exista em uma única conta. A regra vale nos dois sentidos:

• No convite. Convidar um e-mail que já pertence a outra conta é recusado com a mensagem "Usuários associados a outra conta não podem ser adicionados enquanto o SAML estiver habilitado". O agente não é criado.
• No login. Se a pessoa pertence a esta conta e também a outra, a entrada via IdP falha com "Falha na autenticação. Por favor, verifique suas credenciais e tente novamente."

O motivo é a identidade: uma pessoa em várias contas teria um único registro de login, e o método de autenticação é gravado nesse registro — não dá para ele ser SAML numa conta e senha em outra ao mesmo tempo.

Pela mesma razão, ao ativar o SAML a plataforma converte para o método SAML apenas os usuários que pertencem somente a esta conta; quem também está em outra conta permanece com login por e-mail e senha. Ao remover a configuração SAML, o caminho de volta é simétrico: o método volta para e-mail, exceto para quem ainda tem SAML ativo em outra conta. Um agente criado enquanto o SAML está ativo já nasce no método SAML.

Mapeamento de grupos para funções (role_mappings)

Além dos três atributos de identidade, a configuração aceita um mapa de grupo do IdP → função. Os grupos são lidos da asserção nos atributos groups, Group ou memberOf — o primeiro que existir. O primeiro grupo com mapeamento definido vence, e ele pode apontar para:

• uma função padrão (administrator ou agent); ou
• um custom role — mas esse ramo só é aplicado se a funcionalidade Custom Roles estiver habilitada na conta (veja Funções & Acessos e governança).

Sem mapa, ou sem grupo correspondente, o agente entra como Agente.

O mapa não tem campo próprio na tela de Segurança — ele é gravado pela API, no campo role_mappings das configurações de SAML:

{ "Administrators": { "role": "administrator" }, "Suporte": { "custom_role_id": 7 } }

Atenção: o formulário da tela de Segurança envia role_mappings vazio toda vez que alguém salva. Se você configurou o mapa pela API e depois alguém salvar a configuração pela tela, o mapa é apagado — reaplique-o pela API.

Valores do provedor de serviço (SP)

Depois de salvar, a plataforma exibe os valores do lado do serviço (Service Provider) que você informa ao seu IdP:

• ACS URL — o endereço para onde o IdP envia a resposta SAML, no formato https://<endereço da plataforma>/omniauth/saml/callback?account_id=<id da conta>. É exibida sempre.
• SP Entity ID — o identificador da ConversaLabs como aplicação no seu IdP.
• Fingerprint — a impressão digital SHA-1 do certificado, útil para conferência.

Duas chaves de disponibilidade

O formulário só aparece quando as duas estão liberadas, e cada uma tem a sua própria mensagem:

• Funcionalidade saml na conta — sem ela, a API responde 403 com "SAML não está habilitado para esta conta".
• SSO via SAML na instalação (ENABLE_SAML_SSO_LOGIN, ligado por padrão) — desligado, a API responde 403 com "O SSO via SAML não está habilitado para esta instalação". Essa chave é do operador da instalação, não da conta.

A checagem da instalação roda primeiro: com as duas desligadas, a mensagem que aparece é a da instalação.

Casos de uso

• Centralizar o acesso: a empresa controla logins e desligamentos pelo diretório corporativo.
• Reforçar a segurança: aplicar as políticas de senha e o segundo fator (MFA) do próprio IdP.
• Onboarding/offboarding ágil: liberar ou revogar o acesso de um agente direto no IdP, sem mexer conta a conta na plataforma.

Dicas, limites e boas práticas

• Mantenha o certificado do IdP atualizado — certificados expiram e quebram o login quando vencem.
• Combine o SSO com papéis bem definidos (RBAC) e com auditoria para governança completa.
• Teste com um agente antes de exigir SAML de toda a equipe.

Disponibilidade e paywall

• O SSO com SAML é premium: se o recurso não estiver no seu plano, a área de Segurança mostra uma tela de upgrade (no Cloud, com caminho para a cobrança) em vez do formulário.
• Disponível apenas nas instalações Cloud e Enterprise e somente quando o método de login SAML está liberado para a conta.

Solução de problemas

• O login falha ou entra em loop: confira SSO URL, Entity ID do IdP e o Certificado — um valor divergente entre a plataforma e o IdP impede a autenticação.

• Atributo de papel ausente / agente sem permissão: verifique se o IdP envia email, first_name e last_name, e revise o papel atribuído na governança de acesso.

• Certificado expirado: gere um novo certificado no IdP e atualize o campo Certificado.

• Usuário não provisionado: a conta só é criada na primeira entrada se os atributos esperados chegarem — confirme o mapeamento de atributos no IdP.

• Não vejo a configuração de SAML: o recurso premium pode não estar habilitado, ou a instalação não é Cloud/Enterprise, ou o método de login SAML não está liberado para a conta.

• Não consigo convidar alguém que já usa a plataforma em outra conta: é a regra de conta única do SAML. A pessoa precisa sair da outra conta antes de ser convidada, ou você mantém o convite para depois de desligar o SAML.

• O agente não consegue redefinir a senha: esperado. Uma conta de login no método SAML recebe "Esta conta usa autenticação SAML. A redefinição de senha não está disponível. Por favor, contate o administrador." A senha passa a ser gerenciada no IdP.

• O login por e-mail e senha é recusado: também esperado. A resposta é "Esta conta usa autenticação SAML. Por favor, faça login através do provedor SAML da sua organização."

• O certificado é recusado ao salvar: o campo exige um certificado X.509 válido em formato PEM. Cole o conteúdo completo, incluindo as linhas de início e fim.

• Ativei o SAML e parte do time continua entrando com senha: são as pessoas que também pertencem a outra conta — elas ficam de fora da conversão de propósito.

Veja também

• Papéis personalizados e governança (RBAC)
• Logs de auditoria
• Login, perfil e verificação em duas etapas (2FA)
• Visão geral de Administração