Version: Latest (4.0.0)

SAML 2.0 Single Sign-On (SSO)

cidaas supports SAML 2.0 for Single Sign-On (SSO) authentication. This page covers configuring cidaas as a Service Provider (SP) — adding an external SAML IdP as a login provider for your users.

Looking to configure cidaas as an IdP instead? As of cidaas v4.0.0, use the SAML_SP application type and the Trust Desk creation wizard — see SAML SP Integration.

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
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
- Covered by SAML SP Integration, not this page
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
- Covered below on this page

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 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:

User Access Request: The user attempts to access a protected resource in cidaas (acting as SP).
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
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.)
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
SAML Response: The external IdP generates a SAML Response containing:
- The signed (and optionally encrypted) SAML Assertion
- User attributes from the IdP
- Authentication context
Response to cidaas: The IdP sends the SAML Response to cidaas's Assertion Consumer Service (ACS) URL via HTTP-POST or HTTP-Redirect binding.
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)
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
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.

Log in to Trustdesk.
Navigate to Providers → Identity Providers.
Click + Add provider and select SAML as the standard type.
Import the external IdP's metadata (URL or XML file), or fill in the individual fields.
Configure attribute mapping and the user_id_attribute.
Save the configuration.

SAML SP APIs

API	Method	Description	Reference
Create SAML SP configuration	`POST`	Create a provider with `standard_type: SAML`	View API
List SAML SP configurations	`GET`	List all provider configurations	View API
Update SAML SP configuration	`PUT` / `PATCH`	Update an existing SAML Service Provider configuration	View API
Delete SAML SP configuration	`DELETE`	Delete a SAML Service Provider configuration	View API

Runtime Endpoints (unchanged):

/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, using the same unified attribute_mapping structure described under Attribute Mapping for SP Configuration:

external_key: the attribute name as it appears in the SAML assertion from the IdP
field_key: the corresponding cidaas user attribute
data_type: mandatory for SAML — the SAML data type of the incoming attribute (e.g. string, xsd:string)
user_id_attribute (on the provider, not inside attribute_mapping): specifies which SAML attribute should be used as the unique identifier for user matching (typically sub or a unique ID from the IdP)

Example attribute mapping:

{
  "attribute_mapping": {
    "email": {
      "field_key": "email",
      "external_key": "emailAddress",
      "data_type": "string"
    },
    "given_name": {
      "field_key": "given_name",
      "external_key": "name",
      "data_type": "string"
    }
  },
  "saml": {
    "user_id_attribute": "sub"
  }
}

SAML Metadata, Signing, and Encryption Configuration (SP)

Aspect	Description	What You Need	Configuration Location
SAML Metadata	cidaas needs metadata from the external IdP to establish trust	IdP'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
Signing	cidaas validates signatures from the external IdP	IdP'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)
Encryption	cidaas decrypts assertions received from the IdP (optional, if IdP encrypts)	cidaas's own certificate/key pair	cidaas generates its SP signing/encryption certificates automatically (read-only `sp_signing_certificates`/`sp_encryption_certificates`); share the public certificate with the IdP
	IdP encrypts using cidaas's public certificate	-	Retrieve the generated certificate from the provider configuration and share it with the IdP

Sensitive Information:

Item	Purpose	Security Level	Notes
cidaas private key	Used to decrypt assertions (if encryption enabled)	🔒 Never share	Keep secure, required for decryption
cidaas public certificate	Shared with IdP for encryption	✅ Safe to share	IdP uses this to encrypt assertions
IdP's public certificate	Used to validate signatures	✅ Safe to share	Included in IdP metadata
IdP's private key	Managed by IdP (not used by cidaas)	🔒 Never shared	Managed 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

Feature	HTTP-POST	HTTP-Redirect
Message Encoding	Base64 only	DEFLATE + Base64 + URL encoding
Transport Method	HTTP POST (form submission)	HTTP GET (URL redirect)
JavaScript Required	Yes	No
Message Size Limit	~No limit (POST body)	~2000-8000 chars (URL limit)
Browser History	Not visible	Visible (encoded)
Server Logs	Body not always logged	Full URL logged
Signature Handling	Embedded in XML	Separate query parameters
Implementation Complexity	Medium (form + JS)	Low (redirect)
Best For	Large assertions, many attributes	Simple 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:

Role	What You Sign	What You Validate	Configuration Location
cidaas as IdP	Assertions (always), Responses (optional)	-	cidaas automatically signs with its private key
cidaas as SP	AuthnRequests (optional)	Assertions from IdP	Validate using IdP's public cert from metadata

How Signing Works:

The sender creates a digital signature using their private key
The signature is embedded in the SAML XML (for POST binding) or sent as a URL parameter (for Redirect binding)
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:

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

Encryption Configuration by Role:

Role	What You Encrypt	What You Decrypt	What You Need
cidaas as IdP	Assertions for SP	-	SP's public certificate
cidaas as SP	-	Assertions from IdP	cidaas'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

info

Need Support?

Please contact us directly on our support page or reach out to cidaas support at [email protected].

Key Benefits​

Understanding IDP vs SP​

SAML as Service Provider (SP)​

cidaas as Service Provider Flow​

Configuration Steps​

SAML SP APIs​

Attribute Mapping for SP Configuration​

SAML Metadata, Signing, and Encryption Configuration (SP)​

cidaas as SP: Default Behavior​

SAML Bindings: HTTP-POST vs HTTP-Redirect​

Comparison Table​

HTTP-POST Binding​

HTTP-Redirect Binding​

When to Use Each Binding​

SAML Signing​

SAML Encryption​

Example SAML Response​