OpenID Connect 1.0 Federation

Cognethics acts as an OpenID Connect Relying Party (RP) against your IdP. We support the authorization-code flow with PKCE (RFC 7636 S256), validate ID tokens against the IdP's JWKS, and provision users automatically from configurable claim mappings.

Quick Reference

RP Metadata

Fetch the RP metadata to discover the redirect URI and the list of configured IdPs for your tenant:

curl https://{tenant}.cognethics.com/api/auth/oidc/metadata/

Sample response:

{
  "tenant_id": "...",
  "tenant_name": "Acme Corp",
  "redirect_uri": "https://acme.cognethics.com/api/auth/oidc/callback/",
  "login_url_template": "https://acme.cognethics.com/api/auth/oidc/login/?idp={slug}",
  "discover_url": "https://acme.cognethics.com/api/auth/oidc/discover/",
  "supported_response_types": ["code"],
  "supported_grant_types": ["authorization_code", "refresh_token"],
  "supported_scopes": ["openid", "profile", "email"],
  "pkce_required": true,
  "token_endpoint_auth_methods_supported": ["client_secret_basic", "none"],
  "configured_idps": [
    {
      "id": "...",
      "slug": "corporate-okta",
      "name": "Corporate Okta",
      "is_default": true,
      "issuer": "https://acme.okta.com"
    }
  ]
}

Configuration

Each OIDC IdP is configured per-tenant with:

The discovery document is fetched automatically; the authorization_endpoint, token_endpoint, userinfo_endpoint, jwks_uri, and issuer fields are populated from it. Configuration is also exposed via the Cognethics MCP entity_crud/core/oidc_identity_provider/{list,read,create,update,delete} operations, so AI clients can drive setup end-to-end.

Claim Mapping

By default Cognethics maps standard OIDC claims:

Customize per-IdP for non-standard claims. Example:

{
  "email": "email",
  "preferred_username": "username",
  "https://acme.com/claims/department": "department",
  "https://acme.com/claims/employee_id": "external_id"
}

Authorization Flow

1. User visits https://{tenant}.cognethics.com/api/auth/oidc/login/?idp={slug}&next=/welcome
2. Cognethics generates a PKCE code_verifier, code_challenge, OAuth state, and OIDC nonce — stored short-lived (10 min) and bound to the attempt
3. Browser redirected to the IdP's authorization_endpoint with response_type=code, code_challenge_method=S256, and scope=openid profile email
4. User authenticates at the IdP
5. IdP redirects back to /api/auth/oidc/callback/?code=...&state=...
6. Cognethics looks up the state row, validates not-expired and not-consumed, marks it consumed
7. Cognethics POSTs the authorization code to the IdP's token_endpoint with code_verifier (and client_secret if applicable)
8. IdP returns id_token (a JWT), access_token, and optionally refresh_token
9. Cognethics validates the ID token signature against the IdP's JWKS, checks iss, aud, exp, nbf, and nonce
10. Optionally fetches the UserInfo endpoint for richer claims (if require_userinfo=true)
11. Resolves the Cognethics user by mapped email claim; creates if auto_create_users=true
12. Issues Cognethics JWTs via a one-time server-to-server handoff code — tokens never appear in URLs

ID Token Validation

Every ID token is validated against:

• Signature: JWS algorithm matches id_token_signed_response_alg (default RS256); signed by a key from the IdP's jwks_uri. JWKS is cached for one hour with automatic rotation on signature failure.
• iss: Matches the IdP's configured issuer exactly.
• aud: Includes the configured client_id.
• exp: Token has not expired (120-second clock skew tolerance).
• nbf: Not-before time has passed (with skew).
• nonce: Matches the nonce Cognethics sent in the authorization request — guards against replay.
• sub: Required; used as the IdP-stable subject identifier in audit and session tables.

Multi-Domain SSO Routing

Configure email-domain-based IdP selection so users with different email domains land on different IdPs automatically:

• @engineering.acme.com → Okta (Engineering team)
• @marketing.acme.com → Azure AD (Marketing team)
• @acme.com (fallback) → default IdP

Use the discovery probe to check which IdP an email would route to without redirecting:

curl 'https://{tenant}.cognethics.com/api/auth/oidc/discover/[email protected]'

Single Logout (RP-Initiated)

If your IdP publishes an end_session_endpoint in its discovery document, Cognethics initiates RP-initiated logout per OpenID Connect RP-Initiated Logout 1.0. Users logging out of Cognethics are also signed out at the IdP, with post_logout_redirect_uri support for landing-page customization.

Audit Logging

Every OIDC event is captured with full context:

Common IdP Configurations

Okta (OIDC)

1. Okta Admin → Applications → Create App Integration → OIDC — Web Application
2. Set:
   • Sign-in redirect URI: https://{tenant}.cognethics.com/api/auth/oidc/callback/
   • Sign-out redirect URI: https://{tenant}.cognethics.com/
   • Grant types: Authorization Code (with PKCE)
3. Note the Client ID and Client Secret
4. Register the IdP in Cognethics with discovery_url=https://{your-okta-domain}/.well-known/openid-configuration

Azure AD / Microsoft Entra ID

1. Entra Admin → App registrations → New registration
2. Set:
   • Redirect URI (Web): https://{tenant}.cognethics.com/api/auth/oidc/callback/
   • Front-channel logout URL: https://{tenant}.cognethics.com/logout
3. Certificates & secrets → New client secret
4. API permissions → Microsoft Graph → openid, profile, email
5. Register the IdP in Cognethics with discovery_url=https://login.microsoftonline.com/{tenant-id}/v2.0/.well-known/openid-configuration

Auth0

1. Auth0 Dashboard → Applications → Create Application → Regular Web Application
2. Allowed Callback URLs: https://{tenant}.cognethics.com/api/auth/oidc/callback/
3. Advanced Settings → Grant Types: Authorization Code, Refresh Token
4. Note the Domain, Client ID, Client Secret
5. Register in Cognethics with discovery_url=https://{your-auth0-domain}/.well-known/openid-configuration

Google Workspace

1. Google Cloud Console → APIs & Services → Credentials → Create OAuth client ID
2. Application type: Web application
3. Authorized redirect URIs: https://{tenant}.cognethics.com/api/auth/oidc/callback/
4. Register in Cognethics with discovery_url=https://accounts.google.com/.well-known/openid-configuration

Security Properties

• PKCE on every flow — RFC 7636 S256 code challenge for every authorization-code exchange; replay-resistant even if the redirect URI leaks
• state parameter — Random per-attempt token, single-use, expires in 10 minutes; binds the callback to the original login attempt and prevents CSRF
• nonce parameter — Random per-attempt token returned in the ID token's nonce claim; prevents ID-token replay across login attempts
• JWKS rotation — JWKS cached one hour by default; on signature failure the JWKS is re-fetched once to recover from key rotation transparently
• Client secrets encrypted at rest — Fernet symmetric encryption
• Server-to-server token handoff — Cognethics JWT pair is delivered via a one-time exchange code; the access/refresh tokens never appear in URLs, Referer headers, or browser history
• Audit log — Every authorization request, callback, validation failure, user creation, and SLO is recorded with correlation IDs

MCP Integration

OIDC IdPs are first-class MCP entities. AI clients with the right permissions can:

Create example:

{
  "tool": "entity_crud",
  "app": "core",
  "entity": "oidc_identity_provider",
  "operation": "create",
  "data": {
    "name": "Corporate Okta",
    "slug": "corporate-okta",
    "discovery_url": "https://acme.okta.com/.well-known/openid-configuration",
    "client_id": "0oa1...",
    "client_secret": "...",
    "is_active": true,
    "is_default": true
  }
}

Troubleshooting

"ID token signature validation failed":

• Verify the IdP's JWKS endpoint is reachable from Cognethics
• Trigger a refresh_discovery action to re-fetch the JWKS
• Confirm the configured id_token_signed_response_alg matches the IdP's signing algorithm

"ID token issuer mismatch":

• The iss claim must exactly match the IdP's configured issuer. Common cause: trailing slash differences. Refresh discovery to align.

"ID token nonce mismatch":

• The callback received an ID token whose nonce doesn't match the in-flight state. Most often this means the user opened two login windows. Have them retry from a single tab.

"State already consumed" / "State expired":

• The authorization callback was re-played or arrived after the 10-minute window. Have the user retry.

"User {email} not found and auto-creation is disabled":

• Either enable auto_create_users for the IdP, or pre-create the user with the matching email.

Standards

• OpenID Connect Core 1.0
• OpenID Connect Discovery 1.0
• OpenID Connect RP-Initiated Logout 1.0
• OAuth 2.0 (RFC 6749)
• PKCE (RFC 7636)

Back to Enterprise Authentication · See also SAML 2.0 SSO · SCIM 2.0 Provisioning