Pular para o conteúdo principal
Este guia é o inverso de Login com a Cativa.
  • Em Login com a Cativa, a Cativa é o IdP: um app de terceiro autentica o usuário usando a conta da comunidade.
  • Aqui, a empresa é o IdP: os membros entram na comunidade Cativa usando o sistema de login que a empresa já tem. A Cativa age como Relying Party e federa para o IdP do cliente.
Use isto quando a comunidade pertence a uma organização que já tem um diretório de identidade (Google Workspace, Microsoft Entra/Azure AD, Okta, Auth0, Keycloak, ou qualquer provedor OIDC) e os membros não devem criar uma senha separada.
Quer testar sem ter um IdP real? O repo cativa-sso traz um IdP OIDC mock pronto pra rodar na pasta cliente-idp (Node + Express): discovery, JWKS RS256, authorize/token/userinfo. Suba ele atrás de um túnel público e registre como provedor pra exercitar o fluxo ponta a ponta.

​
Como funciona

A Cativa valida a assinatura do id_token (via JWKS do provedor), confere o audience (o seu client_id) e exige a claim email. No primeiro login, se auto-provisionamento estiver ligado, o usuário é criado na comunidade a partir dos dados do IdP.

​
Pré-requisitos

  1. Um app OAuth/OIDC no seu IdP — crie um client no provedor da empresa e anote client_id e client_secret.
  2. A URL de callback da Cativa, registrada no seu IdP como redirect URI autorizada. Você não precisa montá-la na mão: ao abrir o formulário de Identity Provider no admin da Cativa (próxima seção), ele mostra a URL de callback exata, com o seu slug já preenchido, e um botão Copiar. Cole esse valor no client do seu IdP. O formato é: 
    https://apis.cativalab.digital/tenant/api/v2/sso/external/{customerName}/callback
    {customerName} é o slug da sua comunidade — o subdomínio público da Cativa (https://{customerName}.cativa.digital). É fixo por tenant, e o admin que está configurando já o conhece (é a comunidade dele). Na dúvida, copie a URL que o formulário mostra em vez de digitar o slug você mesmo.
  3. Acesso de admin à comunidade Cativa para cadastrar o provedor.

​
Cadastrar o Identity Provider

No admin da comunidade, em Integrações → SSO → Provedores → Novo provedor, escolha o preset do seu IdP (Google, Microsoft, Okta, Auth0, Keycloak) ou Custom (OIDC) e preencha:
1

Discovery

Cole a Metadata URL (o .well-known/openid-configuration do seu IdP) e clique em Buscar configuração — a Cativa preenche authorize/token/userinfo/jwks sozinha. (Em provedores sem discovery, informe os endpoints manualmente.)
2

Credenciais

Informe Client ID e Client Secret do client que você criou no IdP, e os Scopes (no mínimo openid email profile).
3

Provisionamento

Ligue Auto-provisionar para criar o usuário no primeiro login, e escolha a Role padrão (Usuário ou Admin). Sem auto-provisionar, só usuários já existentes (e vinculados) conseguem entrar.
4

Slug

Defina um slug (ex.: empresa) — ele entra na URL de início do login federado.
Mantenha apenas um provedor habilitado durante os testes. O callback identifica o provedor por um cookie setado no início; com vários provedores habilitados e o cookie ausente, a identificação fica ambígua.

​
Disparar o login

Aponte o botão “Entrar com a conta da empresa” para: 
https://apis.cativalab.digital/tenant/api/v2/sso/external/{customerName}/{slug}/authorize
A Cativa redireciona para o IdP da empresa, recebe o code no callback, valida o id_token, vincula/auto-provisiona o usuário e redireciona o browser de volta para a comunidade já autenticado.

​
O que o IdP precisa devolver

  • Um id_token assinado, validável pelo jwks do provedor (a Cativa busca a chave pública do discovery/JWKS).
  • A claim email é obrigatória — é a chave de identidade. Sem ela o login é recusado.
  • given_name / family_name / picture são usados (quando presentes) ao auto-provisionar o usuário.

​
Erros comuns

O cookie anti-CSRF (sso_state) não voltou. Garanta que o IdP redirecionou para a mesma URL de callback registrada (.../tenant/api/v2/sso/external/{customerName}/callback, com o prefixo completo) e que o fluxo foi concluído dentro de 10 minutos.
O id_token veio sem a claim email. Ajuste os scopes/claims no client do seu IdP para incluir email (e email_verified quando aplicável).
Há mais de um provedor habilitado e o cookie de identificação se perdeu. Deixe só um habilitado, ou inicie sempre pela URL /sso/external/{customerName}/{slug}/authorize (com o slug correto).
A assinatura do id_token não validou, ou o audience não bate. Confira que o Client ID cadastrado é o mesmo aud que o IdP emite, e que a Metadata URL aponta para o JWKS certo.

​
Próximos passos

Login com a Cativa

O fluxo inverso: a Cativa como IdP para apps de terceiro.

IdP de exemplo (GitHub)

A pasta cliente-idp é um IdP OIDC mock pronto pra rodar, para testar este fluxo.