Skip to main content
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.

​
Cenário

A comunidade Makers pertence à empresa Acme, que usa Google Workspace pra todo mundo. Você não quer que os colaboradores criem mais uma senha: eles clicam em “Entrar com a conta Acme”, passam pelo login do Google que já usam e caem dentro da comunidade já autenticados. No primeiro acesso, a Cativa cria a conta automaticamente a partir dos dados do Google (nome, email, avatar). A Cativa é o Relying Party: ela delega a autenticação ao IdP da empresa, valida o id_token que volta e vincula (ou provisiona) o usuário na comunidade.

​
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 (YOUR_CLIENT_ID) e client_secret (YOUR_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 é:
    {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.

​
Etapa 1: 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.

​
Etapa 2: Disparar o login em runtime

Depois de cadastrado, o login federado é um fluxo de redirects que a Cativa orquestra. Você só precisa apontar um botão pra URL de início; o resto acontece server-side.
1

Aponte o botão de login pra URL de início

O botão “Entrar com a conta da empresa” só precisa navegar (GET) pra:
Exemplo em HTML puro:
A Cativa seta um cookie de estado (anti-CSRF + identificação do provedor) e responde 302 pro /authorize do IdP da empresa.
2

O usuário autentica no IdP da empresa

O browser segue o redirect e cai na tela de login que a empresa já usa (Google, Microsoft, Okta…). O usuário se autentica ali. A Cativa nunca vê a senha.
3

O IdP volta pro callback da Cativa

O IdP redireciona pra URL de callback que você registrou:
A Cativa valida o state contra o cookie, troca o code por um id_token no /token do IdP e valida a assinatura via jwks do provedor.
4

A Cativa vincula ou provisiona e redireciona já logado

Com o id_token validado, a Cativa extrai o email, procura um usuário existente na comunidade e:
  • Se existe: vincula a identidade externa e abre a sessão.
  • Se não existe e auto-provisionar está ligado: cria o usuário a partir das claims (email, given_name, family_name, picture) com a Role padrão.
Por fim, responde 302 pro frontend da comunidade com o usuário já autenticado. Nenhum código do seu lado roda nesta etapa.

​
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.
O id_token que a Cativa espera receber do seu IdP tem esta forma (ilustrativa):

​
Testar com o IdP mock

Antes de plugar o Google Workspace ou o Okta de produção, dá pra exercitar o fluxo inteiro com o IdP mock do repo cativa-sso:
1

Suba o IdP mock atrás de um túnel

Na pasta cliente-idp (Node + Express), rode o servidor e exponha-o com um túnel público (ex.: ngrok http 3000). Anote a URL pública (ex.: https://abc123.ngrok.app), o discovery fica em https://abc123.ngrok.app/.well-known/openid-configuration.
2

Registre o provedor na Cativa

No admin, cadastre um provedor Custom (OIDC) apontando a Metadata URL pro discovery do túnel. Use o client_id/client_secret que o mock aceita (estão no README da pasta). Ligue Auto-provisionar com Role padrão Usuário e defina o slug mock.
3

Rode o fluxo ponta a ponta

Navegue pra https://apis.cativalab.digital/tenant/api/v2/sso/external/{customerName}/mock/authorize. O mock apresenta um formulário de login fake, emite um id_token RS256 com a claim email, e a Cativa te devolve logado na comunidade. Um usuário novo deve aparecer no admin com o email que você digitou.

​
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.
O login federado só autentica e provisiona a conta. O acesso a grupos e cursos é controlado por badge como permissão. Depois do primeiro login, atribua os badges (por CRM, compra, ou Console) pra liberar o conteúdo.

​
Próximos passos

Login com a Cativa

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

Badges como permissão

Login autentica; badge libera acesso. Como atribuir badges depois do primeiro login federado.

IdP de exemplo (GitHub)

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