Skip to main content
This guide is the inverse of Sign in with Cativa.
  • In Sign in with Cativa, Cativa is the IdP: a third-party app authenticates the user with the community account.
  • Here, the company is the IdP: members sign into the Cativa community using the login system the company already has. Cativa acts as the Relying Party and federates to the client’s IdP.
Use this when the community belongs to an organization that already has an identity directory (Google Workspace, Microsoft Entra/Azure AD, Okta, Auth0, Keycloak, or any OIDC provider) and members shouldn’t create a separate password.
Want to test without a real IdP? The cativa-sso repo ships a runnable mock OIDC IdP in the cliente-idp folder (Node + Express): discovery, RS256 JWKS, authorize/token/userinfo. Run it behind a public tunnel and register it as a provider to exercise the flow end to end.

​
How it works

Cativa verifies the id_token signature (via the provider’s JWKS), checks the audience (your client_id) and requires the email claim. On first login, if auto-provisioning is on, the user is created in the community from the IdP data.

​
Prerequisites

  1. An OAuth/OIDC app in your IdP — create a client in the company provider and note its client_id and client_secret.
  2. Cativa’s callback URL, registered in your IdP as an allowed redirect URI. You don’t have to build it by hand: when you open the Identity Provider form in the Cativa admin (next section), it shows the exact callback URL with your slug already filled in, plus a Copy button. Paste that value into your IdP client. The shape is: 
    https://apis.cativalab.digital/tenant/api/v2/sso/external/{customerName}/callback
    {customerName} is your community’s slug — the public Cativa subdomain (https://{customerName}.cativa.digital). It’s fixed per tenant, and the admin who sets this up already knows it (it’s their own community). If in doubt, copy the URL the form shows rather than typing the slug yourself.
  3. Admin access to the Cativa community to register the provider.

​
Register the Identity Provider

In the community admin, under Integrations → SSO → Providers → New provider, pick your IdP preset (Google, Microsoft, Okta, Auth0, Keycloak) or Custom (OIDC) and fill in:
1

Discovery

Paste the Metadata URL (your IdP’s .well-known/openid-configuration) and click Discover endpoints — Cativa fills authorize/token/userinfo/jwks for you. (For providers without discovery, enter the endpoints manually.)
2

Credentials

Enter the Client ID and Client Secret of the client you created in the IdP, and the Scopes (at minimum openid email profile).
3

Provisioning

Turn on Auto-provision to create the user on first login, and choose the Default role (User or Admin). Without auto-provisioning, only already-existing (and linked) users can sign in.
4

Slug

Set a slug (e.g. company) — it goes in the federated login start URL.
Keep only one provider enabled while testing. The callback identifies the provider via a cookie set at the start; with multiple providers enabled and the cookie missing, identification is ambiguous.

​
Trigger the login

Point your “Sign in with your company account” button to: 
https://apis.cativalab.digital/tenant/api/v2/sso/external/{customerName}/{slug}/authorize
Cativa redirects to the company IdP, receives the code at the callback, validates the id_token, links/auto-provisions the user, and redirects the browser back to the community already authenticated.

​
What the IdP must return

  • A signed id_token, verifiable against the provider’s jwks (Cativa fetches the public key from discovery/JWKS).
  • The email claim is required — it’s the identity key. Without it, login is rejected.
  • given_name / family_name / picture are used (when present) when auto-provisioning the user.

​
Common errors

The anti-CSRF cookie (sso_state) didn’t come back. Make sure the IdP redirected to the exact registered callback URL (.../tenant/api/v2/sso/external/{customerName}/callback, with the full prefix) and the flow completed within 10 minutes.
The id_token came without the email claim. Adjust the scopes/claims on your IdP client to include email (and email_verified where applicable).
More than one provider is enabled and the identification cookie was lost. Keep only one enabled, or always start from the /sso/external/{customerName}/{slug}/authorize URL (with the right slug).
The id_token signature didn’t validate, or the audience doesn’t match. Confirm the registered Client ID equals the aud your IdP issues, and that the Metadata URL points to the right JWKS.

​
Next steps

Sign in with Cativa

The inverse flow: Cativa as the IdP for third-party apps.

Example IdP (GitHub)

The cliente-idp folder is a runnable mock OIDC IdP to test this flow.