SAML 2.0 Single Sign-On

Cognethics acts as a Service Provider (SP) for SAML 2.0, accepting authentication assertions from your identity provider (IdP). Supports both SP-initiated (user clicks "Log in with Okta") and IdP-initiated (user logs in to Okta, gets redirected to Cognethics) flows.

Quick Reference

Service Provider Metadata

Download your tenant's SP metadata XML from:

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

Upload this metadata to your identity provider. The metadata includes:

• SP entity ID
• ACS URL (where IdP will POST SAML responses)
• SLO endpoint (where Cognethics initiates logout)
• SP signing certificate (public key)
• NameID formats (Persistent, EmailAddress, Transient)

Supported NameID Formats

• Persistent (default) — Unique identifier that persists across sessions
• EmailAddress — User email as identifier
• Transient — Temporary identifier (new for each assertion)

Attribute Mapping

Configure which IdP SAML attributes map to Cognethics user fields:

Custom attributes can be mapped to custom user fields per tenant from Admin → Enterprise SSO → SAML Identity Providers → (your IdP) in the Cognethics console.

SSO Flows

SP-Initiated Flow

1. User navigates to https://{tenant}.cognethics.com/
2. User clicks "Log in with Okta" (or other IdP)
3. Browser redirected to IdP login (GET /api/auth/saml/login/)
4. User authenticates at IdP
5. IdP POSTs signed SAML assertion to Cognethics ACS endpoint
6. Cognethics validates signature and attributes, creates/updates user
7. Cognethics issues JWT access + refresh tokens via secure server-to-server handoff
8. User logged into Cognethics

IdP-Initiated Flow

1. User logs in directly to IdP (e.g., Okta portal)
2. User clicks "Cognethics" app link in IdP
3. IdP POSTs signed SAML assertion directly to Cognethics ACS endpoint
4. Cognethics validates, creates/updates user, issues JWT tokens
5. User logged into Cognethics

Single Logout (SLO)

SP-Initiated Logout

1. User clicks "Log out" in Cognethics
2. Browser directed to GET /api/auth/saml/slo/
3. Cognethics generates SAML LogoutRequest, POSTs to IdP SLO endpoint
4. IdP logs out the user
5. IdP responds with SAML LogoutResponse
6. User logged out from both IdP and Cognethics

IdP-Initiated Logout

1. User logs out from IdP portal
2. IdP POSTs SAML LogoutRequest to Cognethics SLO endpoint
3. Cognethics logs out the user
4. Cognethics responds with SAML LogoutResponse to IdP

Multi-Domain SSO Routing

Configure email-domain-based IdP routing. Users with email addresses matching a configured domain are automatically routed to the correct IdP.

Example:

• @engineering.acme.com → Okta (Engineering team)
• @marketing.acme.com → Azure AD (Marketing team)
• @*.acme.com (fallback) → OneLogin (entire company)

Domain routing is verified via DNS TXT record or HTTP file verification.

DNS Verification

Add a TXT record to your domain:

_cognethics-verify.engineering.acme.com TXT "v=cognethics1 <verification-token>"

Cognethics queries DNS to confirm domain ownership.

HTTP Verification

Host a file at:

https://engineering.acme.com/.well-known/cognethics-domain-verify.txt

Cognethics fetches the file to confirm domain ownership.

Audit Logging

Every SSO event is logged with full context:

Access audit logs from the Cognethics platform admin console.

Automatic User Provisioning

When a user authenticates via SAML for the first time, Cognethics can automatically:

• Create a new user account
• Populate user fields from IdP attributes (email, name, roles)
• Assign the user to organizations or roles (based on attribute mapping)

If a user already exists, their attributes are updated based on the configured mapping.

Disable automatic user creation to require manual admin approval for new users.

Configuration

A tenant administrator configures SAML directly from the Cognethics console at Admin → Enterprise SSO → SAML Identity Providers:

1. Add Identity Provider — paste your IdP's metadata URL or upload the metadata XML. Cognethics fetches and parses the metadata to populate entity ID, SSO URL, signing certificate, and NameID format automatically.
2. Download the Cognethics SP metadata XML from Admin → Enterprise SSO → SAML Service Provider and upload it to your IdP (most IdPs accept the XML in one click).
3. Add SSO Domains (e.g. engineering.acme.com) and verify ownership via DNS TXT record.
4. Activate the IdP when you've tested the flow with a single user. Users in mapped domains will be routed automatically; SP-initiated and IdP-initiated flows both work.

Attribute mapping defaults follow the standard SAML claim URIs; per-attribute overrides are configurable on the IdP detail page.

Common IdP Configurations

Okta SAML 2.0

1. In Okta Admin: Applications → Create App Integration → SAML 2.0
2. Configure:
   • Single Sign-On URL (ACS): https://{tenant}.cognethics.com/api/auth/saml/acs/
   • Audience URI (SP Entity ID): https://{tenant}.cognethics.com/
   • Default RelayState: (empty or your app URL)
   • NameID format: Persistent / EmailAddress
   • Application username: Email
3. Attributes: Email, First name, Last name, (any custom attributes)
4. Download SAML metadata from Okta
5. In Cognethics: Admin → Enterprise SSO → SAML Identity Providers → Add Identity Provider, paste the Okta metadata URL or upload the XML

Azure AD / Microsoft Entra

1. In Azure AD: Enterprise applications → New application → SAML
2. Configure:
   • Identifier (Entity ID): https://{tenant}.cognethics.com/
   • Reply URL (ACS): https://{tenant}.cognethics.com/api/auth/saml/acs/
   • Sign on URL: https://{tenant}.cognethics.com/
   • Logout URL: https://{tenant}.cognethics.com/api/auth/saml/slo/
3. User attributes: Email (mail), First name (givenname), Last name (surname)
4. Download SAML metadata (XML)
5. In Cognethics: Admin → Enterprise SSO → SAML Identity Providers → Add Identity Provider, upload the metadata XML

OneLogin SAML 2.0

1. In OneLogin Admin: Applications → Add App → search "SAML Test Connector"
2. Configure:
   • Assertion Consumer Service (ACS) URL: https://{tenant}.cognethics.com/api/auth/saml/acs/
   • Entity ID: https://{tenant}.cognethics.com/
   • Name ID Format: Persistent
3. Parameters: Email, First name, Last name
4. Download SAML metadata
5. In Cognethics: Admin → Enterprise SSO → SAML Identity Providers → Add Identity Provider, upload the metadata XML

Security Considerations

• SAML assertions are signed — Cognethics validates the IdP's signature on every assertion
• ACS endpoint is CSRF-exempt — IdP POSTs are validated via SAML signature, not CSRF tokens
• Tokens are never in URLs — Authorization codes are exchanged server-to-server; access tokens are returned in response body, not URL
• Signing certificates are encrypted at rest — IdP signing certificates and SP signing keys are stored encrypted in the Cognethics database
• Audit logging — All authentication events, failures, and user provisioning are logged

Troubleshooting

"Invalid signature" error:

• Verify IdP signing certificate matches what Cognethics has on file
• Download fresh metadata from IdP and send to Cognethics to update

"User not found / not auto-created":

• Check attribute mapping — does IdP send email attribute?
• Verify automatic user creation is enabled for the IdP

"Domain verification failed":

• For DNS: ensure TXT record is correctly formatted and propagated
• For HTTP: ensure file is accessible at the public URL and contains the exact token

Support

For SAML configuration help, see the in-product help linked from Admin → Enterprise SSO, or reach our support team through the form below. Useful information to include in any request:

• IdP type (Okta, Azure AD, etc.)
• SAML metadata XML (or download link)
• Desired attribute mapping
• Domain routing requirements
• Any special compliance/audit requirements

Back to Enterprise Authentication · See also SCIM 2.0 Provisioning