Cange
Conta e Configurações

Manual de configuração do SSO (SAML) no Cange

14 de novembro de 202613 min de leitura1 visualizações
#Integração#Configuração

Com o SSO ativado, as pessoas da sua empresa entram no Cange usando as credenciais do provedor de identidade corporativo, e o Cange para de pedir senha própria. Este manual reúne a configuração completa de ponta a ponta: o que copiar do Cange, o que fazer no seu provedor (Microsoft Entra ID, Google Workspace ou outro) e como testar antes de liberar para todo mundo.

Antes de começar

RequisitoDetalhe
PlanoDisponível apenas para contas Enterprise
Permissão no CangePerfil de Administrador da conta
Provedor de identidade (IdP)Um IdP compatível com SAML 2.0 e acesso de administrador nele
O que você vai trazer do IdPLogin URL (URL de logon ou SSO) e o certificado público X.509
Usuários no CangeCada pessoa que vai entrar por SSO já precisa estar cadastrada no Cange com o mesmo e-mail do IdP. O SSO não cria usuários automaticamente.

O que você vai fazer

A configuração acontece nas duas pontas e envolve quatro valores. Você copia dois do Cange para o provedor, e traz dois do provedor para o Cange.

  • Do Cange para o IdP: Audience URI (SP Entity ID) e Single sign on URL (ACS URL).
  • Do IdP para o Cange: Login URL e certificado público X.509.

Deixe as duas abas abertas lado a lado, porque você vai alternar entre elas várias vezes.

Não existe "gerar chave" nesse processo. O SAML não usa client ID e client secret, e não é a mesma coisa que o botão "Fazer login com o Google". O provedor cria o certificado automaticamente, e você baixa apenas a parte pública dele. Se o seu IdP oferecer o download de um arquivo .pfx ou .p12 protegido por senha, esse não é o arquivo que você precisa.

Parte 1: copie os endpoints do Cange

  1. No painel do administrador, acesse https://app.cange.me/company-config/security.
  2. Role até a seção Autenticação de Dois Fatores (MFA).
  3. No campo MFA Obrigatória, selecione Ativo. É esse passo que habilita a definição de um método de autenticação para toda a conta.
  4. No campo Método Padrão, selecione SAML. Um botão Configurar aparece ao lado do campo.
  5. Clique em Configurar. A janela Configurar SAML (Single Sign-On) abre com quatro campos: dois preenchidos pelo Cange, somente leitura, e dois que você precisa preencher.
Janela Configurar SAML (Single Sign-On) do Cange, com os campos Audience URI, Single sign on URL, Login URL e IDP Public Certificate
Os dois primeiros campos são gerados pelo Cange e vão para o seu provedor. Os dois últimos recebem os dados do provedor.

Na seção Endpoints do serviço SAML, use o botão Copiar de cada campo:

Campo no CangeComo costuma se chamar no IdPValor
Audience URI (SP Entity ID)Identifier, Entity ID, Audiencehttps://api.cange.me/auth/saml/metadata
Single sign on URL (ACS URL)Reply URL, ACS URL, Assertion Consumer Servicehttps://api.cange.me/auth/saml/acs
Sempre copie os valores direto da tela, pelo botão Copiar. Não digite manualmente e não reaproveite valores de outra documentação. Qualquer diferença de caractere, barra final ou protocolo faz a configuração falhar.

Agora pause o Cange e vá até o seu provedor de identidade.

Parte 2: crie a aplicação no seu provedor

Siga a seção do seu provedor. Se você usa outro IdP, pule para Outros provedores.

Microsoft Entra ID

Portal: https://entra.microsoft.com. Permissão necessária: Administrador de Aplicativos, Administrador de Aplicativos de Nuvem ou função equivalente. O SSO SAML básico está disponível em todos os planos do Entra, inclusive o gratuito.

  1. No menu lateral, vá em Aplicativos, Aplicativos Empresariais.
  2. Clique em Novo aplicativo, depois em Criar seu próprio aplicativo.
  3. Dê o nome Cange e selecione Integrar qualquer outro aplicativo que você não encontra na galeria (Non-gallery). Clique em Criar.
  4. Dentro da aplicação, clique em Logon único e selecione o bloco SAML. A tela abre dividida em blocos numerados, e você vai trabalhar nos blocos 1 a 4.
  5. No bloco 1, Configuração Básica do SAML, clique no lápis e preencha Identificador (ID da Entidade) com o Audience URI do Cange e URL de Resposta com a ACS URL do Cange. Deixe a URL de Logon em branco, ou informe a URL de acesso do Cange se quiser habilitar login iniciado pelo Entra. Clique em Salvar.
  6. No bloco 2, Atributos e Declarações, confirme que a Declaração de nome exclusivo (Name ID) tem origem Atributo e atributo de origem user.mail, ou user.userprincipalname se o UPN for o e-mail corporativo da sua organização. Formato: Endereço de e-mail ou Persistente.
  7. No bloco 3, Certificado de Assinatura SAML, clique em Baixar na linha Certificado (Base64) e salve o arquivo .cer. Ainda nesse bloco, clique no lápis e preencha o Endereço de e-mail de notificação com uma caixa monitorada pelo time de TI, não a caixa pessoal de um administrador.
  8. No bloco 4, Configurar Cange, copie a URL de Logon. Ela tem o formato https://login.microsoftonline.com/{tenant-id}/saml2. Guarde também o Identificador do Microsoft Entra e a URL de Logoff.
  9. No menu lateral da aplicação, clique em Usuários e grupos, depois em Adicionar usuário/grupo. Para o teste inicial, atribua apenas um usuário piloto. Clique em Atribuir.
O passo 9 é obrigatório. Sem atribuir usuários, o login falha mesmo com todo o resto correto, com o erro AADSTS50105.

Referência visual dos mesmos passos na documentação da Microsoft: Habilitar o logon único para um aplicativo empresarial.

Google Workspace

Portal: https://admin.google.com. Permissão necessária: superadministrador do Google Workspace, ou função de administrador com o privilégio de gerenciar apps SAML. Os nomes abaixo seguem o Admin Console em português. Em inglês, o caminho é Apps, Web and mobile apps, Add app, Add custom SAML app.

  1. No menu lateral, vá em Apps, Apps da Web e para dispositivos móveis.
  2. Clique em Adicionar app, depois em Adicionar app SAML personalizado. Em Nome do app, informe Cange. Clique em Continuar.
  3. Na tela Detalhes do provedor de identidade do Google, copie os três valores antes de avançar: a URL do SSO (https://accounts.google.com/o/saml2/idp?idpid=XXXXXXXX), o ID da entidade (https://accounts.google.com/o/saml2?idpid=XXXXXXXX) e o Certificado, clicando em Fazer o download do certificado. Clique em Continuar.
  4. Na tela Detalhes do provedor de serviços, preencha URL do ACS com a ACS URL do Cange e ID da entidade com o Audience URI do Cange. Deixe a URL inicial em branco e Resposta assinada desmarcado.
  5. Ainda nessa tela, na seção ID do nome, defina o Formato do ID do nome como EMAIL e o ID do nome como Informações básicas, E-mail principal. Clique em Continuar.
  6. Na tela Mapeamento de atributos, clique em Adicionar mapeamento e crie três linhas: E-mail principal para email, Nome para given_name e Sobrenome para family_name. Digite os nomes em minúsculas, exatamente assim. Clique em Concluir.
  7. Na página do app Cange, clique em Acesso do usuário. Selecione a unidade organizacional ou o grupo do usuário piloto, marque ATIVADO e clique em Salvar.
Deixe Resposta assinada desmarcado. Com essa opção marcada, o login falha na validação.
A URL do SSO e o ID da entidade são parecidos, mas não são iguais. O primeiro termina em /saml2/idp?idpid= e o segundo em /saml2?idpid=. Trocar um pelo outro é o erro mais comum aqui.
O passo 7 é obrigatório. Todo app SAML personalizado nasce desativado para todos os usuários, e sem ativar o Google bloqueia o login com o erro app_not_configured_for_user. A ativação pode levar alguns minutos e, em casos raros, até 24 horas.

Referência visual dos mesmos passos na documentação do Google: Configurar seu próprio app SAML personalizado.

Outros provedores

O procedimento é o mesmo, só os nomes dos campos mudam. Onde encontrar a Login URL em cada provedor:

  • Okta: "Identity Provider Single Sign-On URL".
  • ADFS: normalmente https://seu-adfs/adfs/ls/.
  • Outros IdPs SAML 2.0: procure por "SSO URL", "SAML 2.0 Endpoint" ou "Login URL" na tela de configuração da aplicação.

Em todos eles, baixe o certificado no formato Base64, também chamado de PEM ou "certificado bruto", e atribua pelo menos o usuário piloto à aplicação.

Parte 3: volte ao Cange e finalize

  1. Na janela Configurar SAML (Single Sign-On), preencha Login URL com a URL de logon do seu provedor.
  2. Abra o arquivo do certificado em um editor de texto simples, como Bloco de Notas ou VS Code. Não abra no Word.
  3. Copie todo o conteúdo, incluindo as linhas -----BEGIN CERTIFICATE----- e -----END CERTIFICATE-----, e cole no campo IDP Public Certificate.
  4. Use a opção de teste da conexão e confirme que o teste passa.
  5. Com o teste aprovado, clique em Salvar. O indicador de status deixa de exibir Não configurado.
  6. De volta à tela de segurança, com MFA Obrigatória em Ativo e Método Padrão em SAML, clique em Salvar MFA. É nesse momento que o login por SSO passa a valer para a conta.
Se o teste falhar, consulte a seção de erros comuns antes de mexer na configuração do IdP.

Parte 4: envie o ID da entidade ao suporte do Cange

Se o seu provedor é o Google Workspace, este passo é obrigatório e precisa ser feito antes de ativar o SSO. Envie ao suporte do Cange:

  • o nome da sua empresa no Cange;
  • o ID da entidade copiado no Admin Console (https://accounts.google.com/o/saml2?idpid=XXXXXXXX).

O suporte confirma o cadastro para você. Só siga para o teste depois dessa confirmação. Se o seu provedor for outro, pergunte ao suporte se esse envio é necessário no seu caso.

Sem esse envio, o login é concluído no Google, mas o usuário volta para a tela de login do Cange sem entrar.

Parte 5: teste com o usuário piloto

  1. Mantenha a sua sessão de administrador aberta na janela atual.
  2. Em uma janela anônima, acesse https://app.cange.me e entre com o e-mail do usuário piloto.
  3. O Cange redireciona para o provedor. Depois do login lá, o usuário volta ao Cange já autenticado.
  4. Com o fluxo validado, amplie a atribuição no IdP para o grupo ou a unidade organizacional definitiva.
Se o teste falhar, não feche a sessão de administrador. Use essa sessão para voltar o Método Padrão e corrigir a configuração.
O login deve sempre começar pelo Cange, em https://app.cange.me. Abrir o Cange pelo ícone no menu de apps do Google não é suportado e termina em erro.

O que muda depois de ativar

  • Ao acessar o Cange, os usuários são redirecionados para a tela de login do provedor de identidade.
  • Quem já tem sessão ativa no IdP entra direto, sem digitar credenciais.
  • As políticas de senha, MFA e acesso condicional passam a ser as do seu provedor.
  • A desativação ou suspensão de um colaborador no IdP bloqueia o acesso dele ao Cange.

Manutenção: rotação do certificado

O certificado tem validade e o SSO para de funcionar na data do vencimento. No Entra ID o padrão é três anos. No Google Workspace são cinco anos, e a validade aparece em Segurança, Autenticação, SSO com apps SAML.

  1. Gere ou adicione o novo certificado no seu provedor. No Entra, use Certificado de Assinatura SAML, Editar, Nova Certificação. No Google, use Segurança, Autenticação, SSO com apps SAML, Adicionar certificado.
  2. Baixe o novo certificado em Base64.
  3. Atualize o campo IDP Public Certificate no Cange e salve.
  4. Só então torne o novo certificado ativo no provedor.
A ordem importa. Atualize o Cange antes de ativar o novo certificado no IdP. Se você ativar primeiro e atualizar o Cange depois, os logins ficam bloqueados no intervalo entre as duas ações. A troca de certificado não muda o ID da entidade, então não é preciso acionar o suporte de novo.

Erros comuns e como resolver

Sintoma ou códigoCausa provávelComo resolver
O IdP recusa o login antes de voltar ao CangeIdentifier ou Entity ID divergenteConfira se o valor colado no IdP é exatamente o Audience URI da tela do Cange
Erro de "Reply URL não corresponde", ou AADSTS50011ACS URL divergenteRecopie a Single sign on URL do Cange, incluindo protocolo e sem barra no final
Erro 400 sobre a URL do ACS (Google)ACS URL divergenteRecopie a Single sign on URL do Cange, sem barra no final
Login volta ao Cange mas não autenticaAssinatura inválidaRecopie o certificado e verifique se não há espaços, quebras de linha extras ou caracteres perdidos na colagem
AADSTS700016, aplicativo não encontradoIdentifier incorreto ou app criado em outro tenantConfira o Audience URI e o tenant em uso
AADSTS50105, usuário não atribuídoO usuário não está na lista da aplicaçãoAtribua o usuário ou grupo em Usuários e grupos
AADSTS75011, método de autenticação incompatívelConflito com política de acesso condicionalRevise as políticas de acesso condicional aplicadas à aplicação
app_not_configured_for_userApp desativado para a unidade organizacional ou grupo do usuárioAtive o app em Acesso do usuário e aguarde a propagação
app_not_configuredO ID da entidade enviado pelo Cange não corresponde a nenhum appRecopie o Audience URI do Cange para o campo ID da entidade do app
Login conclui no provedor mas volta ao Cange sem entrarCertificado divergente, "Resposta assinada" marcado ou ID da entidade não enviado ao suporteRecopie o certificado, desmarque "Resposta assinada" e confirme o envio do ID da entidade com o suporte
O Cange informa que o usuário não foi encontradoO e-mail enviado pelo IdP não existe no CangeCadastre o usuário no Cange com o mesmo e-mail principal da conta corporativa
Funcionava e parou de repenteCertificado expiradoSiga a seção de rotação do certificado

Boas práticas

  • Teste com um usuário antes de liberar para todos. Ative com um grupo piloto e só depois amplie.
  • Mantenha um administrador de reserva. Garanta que exista um caminho de acesso caso o IdP fique indisponível.
  • Acompanhe a validade do certificado. Cadastre um lembrete e um e-mail de notificação de expiração no seu IdP.
  • Padronize o identificador do usuário. Use o e-mail corporativo como identificador enviado pelo IdP e garanta que ele corresponda ao cadastro no Cange.

Checklist final

  • Audience URI e ACS URL copiados da tela do Cange
  • Aplicação criada no provedor de identidade com o nome Cange
  • Identifier ou ID da entidade do app preenchido com o Audience URI do Cange
  • URL de Resposta ou URL do ACS preenchida com a ACS URL do Cange
  • Name ID mapeado para o e-mail corporativo, no formato de e-mail
  • No Google Workspace, "Resposta assinada" desmarcado
  • Certificado Base64 baixado e colado no campo IDP Public Certificate
  • Login URL colada no Cange
  • E-mail de notificação de expiração do certificado cadastrado no IdP
  • Usuário piloto atribuído à aplicação no IdP
  • ID da entidade do provedor enviado e confirmado pelo suporte do Cange, quando aplicável
  • Usuários cadastrados no Cange com o mesmo e-mail do IdP
  • Teste de conexão aprovado e configuração salva
  • MFA Obrigatória em Ativo e Método Padrão em SAML salvos
  • Login testado com o usuário piloto em janela anônima

Próximos passos

Para o detalhamento de cada ponta, consulte os artigos dedicados: "Como configurar SAML (Single Sign-On) no Cange", "Como configurar o Microsoft Entra ID para o SSO do Cange" e "Como configurar o Google Workspace para o SSO do Cange".

Este artigo foi útil?