Skip to main content

SAML 2.0 Single Sign-On (SSO)

cidaas supports SAML 2.0 for Single Sign-On (SSO) authentication. You can configure cidaas to act as an Identity Provider (IdP) or as a Service Provider (SP).

Key Benefits

SAML 2.0 SSO provides several key advantages for your organization:

  • Enhanced Security: Industry-standard protocol with support for signed and encrypted assertions, ensuring message integrity and confidentiality
  • Improved User Experience: Single sign-on eliminates password fatigue—users authenticate once and access multiple applications seamlessly
  • Centralized Identity Management: When acting as IdP, manage user identities, security policies, and access controls from a single platform
  • Enterprise Integration: Seamlessly integrate with existing identity systems when acting as SP
  • Audit & Compliance: Comprehensive authentication logs and audit trails for security compliance and monitoring
  • Flexible Deployment: Support for both HTTP-POST and HTTP-Redirect bindings to accommodate various application requirements
  • Attribute Mapping: Flexible attribute transformation to map user data between systems while maintaining data privacy

Understanding IDP vs SP

  • Identity Provider (IdP): cidaas provides and provisions user identity to other systems (applications)

    • cidaas authenticates users and sends their identity information to applications
    • Applications trust cidaas to verify who the user is
    • Example: Users log in to cidaas, then access multiple applications without logging in again
  • Service Provider (SP): cidaas receives user identity from other systems (external identity providers)

    • External systems authenticate users and send identity information to cidaas
    • cidaas trusts the external system to verify who the user is
    • Example: Users log in to an external system (like Active Directory), then access cidaas without logging in again

Key Features:

  • SAML 2.0 compliant SSO
  • HTTP-POST and HTTP-Redirect bindings
  • Signed and encrypted SAML assertions
  • Attribute mapping and transformation

SAML Response Delivery: SAML responses are delivered via HTTP-POST binding to avoid URL length limitations. The ProtocolBinding attribute in AuthnRequests is set to urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST to ensure responses are sent via POST.


SAML as Identity Provider (IdP)

When cidaas acts as an Identity Provider (IdP), it provides SSO authentication for your applications. Users authenticate once with cidaas and can access multiple applications without re-entering credentials.

What this means: cidaas provides and provisions user identity to other systems (your applications).

cidaas as Identity Provider Flow

The following diagram illustrates the authentication flow when cidaas acts as an Identity Provider, including configuration and runtime APIs:

Detailed Authentication Flow:

  1. User Access Request: The user attempts to access a protected resource on a Service Provider (SP) application.

  2. AuthnRequest to cidaas: The SP generates a SAML AuthnRequest and redirects the user's browser to cidaas (acting as IdP). The request includes:

    • SP's entity ID
    • Assertion Consumer Service (ACS) URL
    • Requested NameID format
    • Optional: Requested attributes
  3. cidaas Authentication:

    • If the user has an active SSO session with cidaas, authentication may be automatic
    • If not authenticated, cidaas presents the login page
    • User authenticates with credentials (username/password, MFA, etc.)
    • cidaas may apply additional security checks (MFA, risk-based authentication)
  4. SAML Assertion Generation: After successful authentication, cidaas:

    • Creates a SAML Assertion with user identity information
    • Includes user attributes based on SP configuration
    • Signs the assertion using the configured signing algorithm
    • Optionally encrypts the assertion if encryption is configured
    • Sets validity conditions (NotBefore, NotOnOrAfter, Audience)
  5. SAML Response: cidaas generates a SAML Response containing:

    • The signed (and optionally encrypted) SAML Assertion
    • User attributes mapped from cidaas user profile
    • Authentication context (how the user was authenticated)
    • Session information (SessionIndex, SessionNotOnOrAfter)
  6. Response to SP: cidaas sends the SAML Response to the SP's Assertion Consumer Service (ACS) URL via HTTP-POST binding.

  7. SP Validation: The SP validates:

    • The digital signature on the assertion (using cidaas public certificate)
    • Assertion validity period
    • Audience restriction matches SP's entity ID
    • Response is intended for this SP (InResponseTo validation)
  8. User Session Creation: Upon successful validation, the SP:

    • Extracts user information from the SAML assertion
    • Creates a user session
    • Maps SAML attributes to application user attributes
  9. Access Granted: The user is redirected to the originally requested resource and can now access the application.

Configuration Steps

As a CIAM admin, you can configure the SAML SSO flow for your application with the following steps.

  1. Log in on the Admin dashboard.

  2. Click Login Provider in the left menu

  3. Select SAML Login Provider and Saml IDP saml-provider-idp.png

  4. Select the Application you would like to offer to log in with SAML. saml-provider-enable.png

  5. Once enabled, the SAML Settings options will appear. Click Save to save your configuration. This will display a Success Confirmation indicating that the SAML configuration you've done is saved.

Parameters to be copied from cidaas to the Service Provider's Portal

  1. Copy the Login URL and paste it for the SSO URL for SAML. copy_login_url1.png
  2. Under SAML Settings, copy the signing key fingerprint.finger_print1.png
  3. From the SP Meta Data section under App Settings, copy the SAML Metadata. SP_Metadata_1.png

Technical Integration

APIMethodDescriptionReference
List SAML IdP ProvidersGETRetrieve all SAML Identity Provider configurationsView API
Create/Update SAML IdPPOSTCreate or update SAML Identity Provider configurationView API

Runtime Endpoints:

  • /saml-srv/idp/login - SAML IdP login endpoint (receives AuthnRequests from SPs)
  • /saml-srv/idp/logout - SAML IdP logout endpoint

Attribute Mapping for IdP Configuration

When cidaas acts as an Identity Provider, attribute mapping defines how cidaas user attributes are mapped to SAML attribute names that the Service Provider expects:

  • Inner Key: The cidaas user attribute name (e.g., email, given_name, family_name)
  • External Key: The SAML attribute name that will be sent in the SAML assertion to the SP (e.g., emailAddress, firstName, lastName)
  • NameID Format: The format used for the user identifier in the SAML assertion (e.g., urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress)

cidaas automatically includes standard user attributes in SAML assertions. You can configure which cidaas attributes are sent and how they are named in the SAML assertion to match your SP's requirements.

Common Attribute Mappings:

cidaas typically sends the following attributes in SAML assertions:

  • User identifier (NameID) - usually the user's email or unique identifier
  • Email address
  • First name (given_name)
  • Last name (family_name)
  • Custom fields (if configured)

Example SAML Attribute Mapping:

When configuring SAML IdP, you can specify which cidaas user attributes should be included in the SAML assertion and their corresponding SAML attribute names. For example:

  • cidaas email → SAML attribute email or emailAddress
  • cidaas given_name → SAML attribute firstName or givenName

App Settings Configuration:

In addition to attribute mapping, ensure the following app settings are configured in App Settings:

  • Allow Registration with Social Information: Enable this to allow users to register using SAML provider information. Without this setting, login will only work for users that were created beforehand.
  • Autologin: Enable autologin to automatically authenticate users with their configured SAML identity provider without requiring manual login selection. This works in conjunction with domain-based webfinger to provide seamless authentication experience.
  • cidaas family_name → SAML attribute lastName or surname

The SP can also request specific attributes in the AuthnRequest using the <samlp:AttributeConsumingService> element, and cidaas will include those requested attributes in the response.

NameID Configuration:

The NameID (user identifier) in the SAML assertion can be configured based on the SP's requirements:

  • Email Format: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress - uses the user's email
  • Persistent Format: urn:oasis:names:tc:SAML:2.0:nameid-format:persistent - uses a persistent unique identifier
  • Unspecified Format: urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified - uses the default identifier

cidaas as IdP: Default Behavior

  • SAML Responses: Always sent via HTTP-POST binding (to avoid URL length limitations)
  • AuthnRequests: Accepts both POST and Redirect bindings from SPs

SAML Metadata, Signing, and Encryption Configuration (IdP)

AspectDescriptionWhat You NeedConfiguration Location
SAML Metadatacidaas generates metadata that Service Providers need to import-Copy SAML Metadata from SP Meta Data section in App Settings
Metadata includes: entity ID, SSO URLs, signing certificates, supported bindings-Provide metadata to SPs for import
Signingcidaas signs assertions using cidaas's private keycidaas's private key (automatically managed)Automatic - signing is always enabled for assertions
SPs validate signatures using cidaas's public certificatecidaas's public certificate (included in metadata)SPs receive certificate via SAML metadata
Encryptioncidaas encrypts assertions for the SP (optional)SP's public certificateSet encryption_certificate (SP's public cert) and encryption_config in SAML settings
SP decrypts using its private key-SP manages its own private key

Sensitive Information:

ItemPurposeSecurity LevelNotes
cidaas private keyUsed to sign assertions🔒 Never shareManaged by cidaas automatically
cidaas public certificateShared via metadata for SPs to validate signaturesSafe to shareIncluded in SAML metadata
SP's public certificateNeeded if encryption is enabledSafe to shareSP provides this, used to encrypt assertions

SAML as Service Provider (SP)

When cidaas acts as a Service Provider (SP), it receives user identity from external identity providers. Users authenticate with an external system (like Active Directory or another IdP), and that system sends identity information to cidaas.

What this means: cidaas receives user identity from other systems (external identity providers).

cidaas as Service Provider Flow

The following diagram illustrates the authentication flow when cidaas acts as a Service Provider, including configuration and runtime APIs:

Detailed Authentication Flow:

  1. User Access Request: The user attempts to access a protected resource in cidaas (acting as SP).

  2. AuthnRequest to IdP: cidaas generates a SAML AuthnRequest and redirects the user's browser to the external Identity Provider (IdP). The request includes:

    • cidaas entity ID
    • Assertion Consumer Service (ACS) URL
    • Requested NameID format
    • Optional: Requested attributes
  3. External IdP Authentication:

    • If the user has an active SSO session with the IdP, authentication may be automatic
    • If not authenticated, the IdP presents the login page
    • User authenticates with credentials (username/password, MFA, etc.)
  4. SAML Assertion Generation: After successful authentication, the external IdP:

    • Creates a SAML Assertion with user identity information
    • Includes user attributes
    • Signs the assertion
    • Optionally encrypts the assertion
  5. SAML Response: The external IdP generates a SAML Response containing:

    • The signed (and optionally encrypted) SAML Assertion
    • User attributes from the IdP
    • Authentication context
  6. Response to cidaas: The IdP sends the SAML Response to cidaas's Assertion Consumer Service (ACS) URL via HTTP-POST or HTTP-Redirect binding.

  7. cidaas Validation: cidaas validates:

    • The digital signature on the assertion (using IdP's public certificate)
    • Assertion validity period
    • Audience restriction matches cidaas entity ID
    • Response is intended for cidaas (InResponseTo validation)
  8. User Account Management: Upon successful validation, cidaas:

    • Extracts user information from the SAML assertion
    • Maps SAML attributes to cidaas user attributes using attribute mapping
    • Creates a new user account or updates an existing one
    • Creates a user session
  9. Access Granted: The user is redirected to the originally requested resource and can now access cidaas.

Benefits of cidaas as SP:

  • Integrate with existing identity systems
  • Leverage existing user directories
  • Centralize user management in external systems
  • Support federated identity scenarios

Configuration Steps

As a CIAM admin, you can configure the SAML SSO flow for your application with the following steps.

  1. Login on the Admin interface.
  2. Click Login Provider in the left menu
  3. Click Login Providers -> SAML SP -> Create New SAML Service Provider.

SAML SP APIs

APIMethodDescriptionReference
List SAML SP ProvidersGETRetrieve all SAML Service Provider configurationsView API
Create SAML SPPOSTCreate a new SAML Service Provider configurationView API
Update SAML SPPUTUpdate an existing SAML Service Provider configurationView API

Runtime Endpoints:

  • /saml-srv/sp/acs - SAML SP Assertion Consumer Service (receives SAML Responses from IdP)
  • /saml-srv/sp/metadata - SAML SP metadata endpoint (for IdP to retrieve cidaas SP metadata)

Attribute Mapping for SP Configuration

When cidaas acts as a Service Provider, attribute mapping defines how SAML attributes received from the external IdP are mapped to cidaas user attributes:

  • External Key: The attribute name as it appears in the SAML assertion from the IdP
  • Inner Key: The corresponding cidaas user attribute name
  • User ID Attribute: Specifies which SAML attribute should be used as the unique identifier for user matching (typically sub or a unique ID from the IdP)

For example, if the IdP sends an attribute named emailAddress, you can map it to cidaas's email attribute by setting:

  • external_key: "emailAddress"
  • inner_key: "email"

Example Attribute Mapping:

{
"attribute_mapping": [
{
"inner_key": "email",
"external_key": "emailAddress",
"is_custom_field": false,
"is_identity_custom_field": false,
"ignore": false
},
{
"inner_key": "given_name",
"external_key": "name",
"is_custom_field": false,
"is_identity_custom_field": false,
"ignore": false
},
{
"inner_key": "sub",
"external_key": "sub",
"is_custom_field": false,
"is_identity_custom_field": true,
"ignore": false
}
]
}

User ID Attribute: The user_id_attribute field specifies which SAML attribute should be used as the unique user identifier. This is typically set to sub or a unique identifier from the IdP.

SAML Metadata, Signing, and Encryption Configuration (SP)

AspectDescriptionWhat You NeedConfiguration Location
SAML Metadatacidaas needs metadata from the external IdP to establish trustIdP's metadata (URL or XML file)Import IdP's metadata during SP configuration
Metadata includes: entity ID, SSO URL, signing certificate, supported bindings-Metadata can be provided via URL or XML file
Signingcidaas validates signatures from the external IdPIdP's public certificate (included in IdP metadata)Automatic - cidaas uses IdP's public cert from metadata to validate
cidaas can optionally sign AuthnRequests-Configure via sign_auth_request (optional)
Encryptioncidaas decrypts assertions received from the IdP (optional, if IdP encrypts)cidaas's public certificate + cidaas's private keySet sp_encryption_certificate (cidaas public cert) and sp_encryption_private_key (cidaas private key)
IdP encrypts using cidaas's public certificate-Share cidaas's public certificate with the IdP

Sensitive Information:

ItemPurposeSecurity LevelNotes
cidaas private keyUsed to decrypt assertions (if encryption enabled)🔒 Never shareKeep secure, required for decryption
cidaas public certificateShared with IdP for encryptionSafe to shareIdP uses this to encrypt assertions
IdP's public certificateUsed to validate signaturesSafe to shareIncluded in IdP metadata
IdP's private keyManaged by IdP (not used by cidaas)🔒 Never sharedManaged by IdP, never shared with cidaas

cidaas as SP: Default Behavior

  • AuthnRequests: Can be configured to use POST or Redirect binding
  • SAML Responses: Accepts both POST and Redirect bindings from IdPs

SAML Bindings: HTTP-POST vs HTTP-Redirect

SAML supports two primary bindings for transporting SAML messages: HTTP-POST and HTTP-Redirect. Understanding the differences helps you choose the right binding for your use case.

Comparison Table

FeatureHTTP-POSTHTTP-Redirect
Message EncodingBase64 onlyDEFLATE + Base64 + URL encoding
Transport MethodHTTP POST (form submission)HTTP GET (URL redirect)
JavaScript RequiredYesNo
Message Size Limit~No limit (POST body)~2000-8000 chars (URL limit)
Browser HistoryNot visibleVisible (encoded)
Server LogsBody not always loggedFull URL logged
Signature HandlingEmbedded in XMLSeparate query parameters
Implementation ComplexityMedium (form + JS)Low (redirect)
Best ForLarge assertions, many attributesSimple setups, no JS environments

HTTP-POST Binding

How it works:

  • SAML messages are Base64-encoded (not compressed)
  • Messages are sent as form data in an HTTP POST request body
  • The browser automatically submits a hidden HTML form via JavaScript

Characteristics:

  • No size limitations: Can handle large SAML messages (assertions with many attributes)
  • No URL encoding issues: Special characters don't need URL encoding
  • More secure for large payloads: Messages aren't visible in browser history or server logs
  • Better for signed messages: XML signatures are easier to embed in POST body
  • ⚠️ Requires JavaScript: The browser must execute JavaScript to submit the form
  • ⚠️ Visible in browser: Users can see the form submission in browser dev tools

Technical Details:

  • SAML message is Base64-encoded only (no compression)
  • Embedded in <input type="hidden" name="SAMLRequest" value="..."> or SAMLResponse
  • Sent via HTTP POST to the destination URL
  • Content-Type: application/x-www-form-urlencoded

Example Flow:

SP → User Browser: HTML form with SAMLRequest in hidden field
User Browser → IdP: HTTP POST with SAMLRequest in body
IdP → User Browser: HTML form with SAMLResponse in hidden field
User Browser → SP: HTTP POST with SAMLResponse in body

HTTP-Redirect Binding

How it works:

  • SAML messages are DEFLATE-compressed, then Base64-encoded, then URL-encoded
  • Messages are sent as query parameters in an HTTP GET redirect
  • The browser follows the redirect URL automatically

Characteristics:

  • No JavaScript required: Works with simple HTTP redirects
  • Simple implementation: Just redirect to a URL
  • Visible in address bar: Easy to debug (though messages are encoded)
  • ⚠️ URL length limitations: Most browsers/servers limit URLs to ~2000-8000 characters
  • ⚠️ URL encoding complexity: Special characters must be properly encoded
  • ⚠️ Less secure for large payloads: Messages appear in browser history and server access logs
  • ⚠️ Compression required: Must DEFLATE compress before encoding to fit in URL

Technical Details:

  • SAML message is DEFLATE-compressed, then Base64-encoded, then URL-encoded
  • Sent as query parameter: ?SAMLRequest=...&RelayState=...
  • Sent via HTTP GET redirect (302/303 status code)
  • For signed requests, signature is sent as separate query parameters: ?SAMLRequest=...&SigAlg=...&Signature=...

Example Flow:

SP → User Browser: HTTP 302 Redirect to IdP with SAMLRequest in URL
User Browser → IdP: HTTP GET with SAMLRequest in query string
IdP → User Browser: HTTP 302 Redirect to SP with SAMLResponse in URL
User Browser → SP: HTTP GET with SAMLResponse in query string

When to Use Each Binding

Use HTTP-POST when:

  • Your SAML assertions contain many attributes (large payloads)
  • You need to send encrypted assertions (encrypted assertions are larger)
  • You want messages hidden from browser history
  • JavaScript is available in your environment
  • You prioritize security and privacy

Use HTTP-Redirect when:

  • Your SAML messages are small (few attributes)
  • JavaScript is not available or disabled
  • You need simple, stateless redirects
  • You want easy debugging (visible in URL)
  • You're working with legacy systems that only support redirects

SAML Signing

SAML signing provides message integrity and authentication. Signed SAML messages ensure that the content has not been tampered with and that the message originates from the expected party.

Supported Signing Algorithms:

  • RSA-SHA1
  • RSA-SHA256 (default)
  • RSA-SHA384
  • RSA-SHA512

What Gets Signed:

  • Assertions: Always signed when cidaas acts as IdP
  • Responses: Optional, configurable via signature_config.sign_targets
  • AuthnRequests: Optional, configurable via sign_auth_request (SP side)
  • LogoutRequests/LogoutResponses: Optional, configurable via signature_config.sign_targets

Configuration by Role:

RoleWhat You SignWhat You ValidateConfiguration Location
cidaas as IdPAssertions (always), Responses (optional)-cidaas automatically signs with its private key
cidaas as SPAuthnRequests (optional)Assertions from IdPValidate using IdP's public cert from metadata

How Signing Works:

  1. The sender creates a digital signature using their private key
  2. The signature is embedded in the SAML XML (for POST binding) or sent as a URL parameter (for Redirect binding)
  3. The recipient validates the signature using the sender's public certificate from SAML metadata

Key Points:

  • As IdP: cidaas's private key is used to sign (managed automatically)
  • As SP: IdP's public certificate (from metadata) is used to validate signatures
  • Public certificates are shared via SAML metadata
  • Private keys are never shared and must be kept secure

SAML Encryption

SAML encryption protects sensitive data in transit. Encryption uses a hybrid approach: symmetric encryption for the content and asymmetric encryption for the key transport.

Supported Content Encryption Algorithms (Symmetric):

  • AES-128-CBC
  • AES-256-CBC (default)
  • AES-128-GCM
  • AES-256-GCM

Supported Key Transport Algorithms (Asymmetric):

  • RSA-OAEP-SHA1
  • RSA-OAEP-SHA256 (default)

How Encryption Works:

  1. The assertion is encrypted using a symmetric algorithm (AES)
  2. The symmetric key is encrypted using an asymmetric algorithm (RSA-OAEP) with the recipient's public key
  3. Both the encrypted assertion and encrypted key are sent to the recipient
  4. The recipient decrypts the key with their private key, then decrypts the assertion

Encryption Configuration by Role:

RoleWhat You EncryptWhat You DecryptWhat You Need
cidaas as IdPAssertions for SP-SP's public certificate
cidaas as SP-Assertions from IdPcidaas's public cert (for IdP) + cidaas's private key (to decrypt)

Configuration Details:

  • As IdP:
    • Configure encryption_certificate (SP's public certificate) and encryption_config in SAML settings
    • cidaas uses SP's public certificate to encrypt assertions
    • SP decrypts using its private key
  • As SP:
    • Configure sp_encryption_certificate (cidaas's public certificate) and sp_encryption_private_key (cidaas's private key)
    • Share cidaas's public certificate with the IdP
    • cidaas decrypts received assertions using its private key
  • Encryption is controlled by the saml-encryption feature flag

Key Points:

  • Encryption is optional but recommended for sensitive data
  • Public certificates are used to encrypt (safe to share)
  • Private keys are used to decrypt (must be kept secure, never shared)
  • The party that encrypts uses the recipient's public certificate
  • The party that decrypts uses their own private key

Example SAML Response

When cidaas acts as an IdP, it generates SAML responses containing assertions with user information. Here's the structure of a typical SAML Response:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol" 
ID="..." InResponseTo="..." Version="2.0"
IssueInstant="..." Destination="...">
<saml:Issuer xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion">...</saml:Issuer>
<samlp:Status>
<samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success"/>
</samlp:Status>
<saml:Assertion xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
ID="..." Version="2.0" IssueInstant="...">
<saml:Issuer>...</saml:Issuer>
<saml:Subject>
<saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
[email protected]
</saml:NameID>
<saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
<saml:SubjectConfirmationData NotOnOrAfter="..."
Recipient="..."
InResponseTo="..."/>
</saml:SubjectConfirmation>
</saml:Subject>
<saml:Conditions NotBefore="..." NotOnOrAfter="...">
<saml:AudienceRestriction>
<saml:Audience>...</saml:Audience>
</saml:AudienceRestriction>
</saml:Conditions>
<saml:AuthnStatement AuthnInstant="..."
SessionNotOnOrAfter="..."
SessionIndex="...">
<saml:AuthnContext>
<saml:AuthnContextClassRef>
urn:oasis:names:tc:SAML:2.0:ac:classes:PasswordProtectedTransport
</saml:AuthnContextClassRef>
</saml:AuthnContext>
</saml:AuthnStatement>
<saml:AttributeStatement>
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
Name="email">
<saml:AttributeValue xsi:type="xs:string">[email protected]</saml:AttributeValue>
</saml:Attribute>
<saml:Attribute NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic"
Name="given_name">
<saml:AttributeValue xsi:type="xs:string">John</saml:AttributeValue>
</saml:Attribute>
</saml:AttributeStatement>
</saml:Assertion>
</samlp:Response>

Key Components:

  • Response: Contains the overall SAML response with status
  • Assertion: Contains the actual authentication and user information
  • Subject: Identifies the authenticated user (NameID)
  • Conditions: Defines validity period and audience restrictions
  • AuthnStatement: Describes how the user was authenticated
  • AttributeStatement: Contains user attributes mapped from cidaas user profile

Need Support?

Please contact us on our support page.