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:
-
User Access Request: The user attempts to access a protected resource on a Service Provider (SP) application.
-
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
-
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)
-
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)
-
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)
-
Response to SP: cidaas sends the SAML Response to the SP's Assertion Consumer Service (ACS) URL via HTTP-POST binding.
-
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)
-
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
-
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.
-
Log in on the Admin dashboard.
-
Click Login Provider in the left menu
-
Select SAML Login Provider and Saml IDP

-
Select the Application you would like to offer to log in with SAML.

-
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
- Copy the Login URL and paste it for the SSO URL for SAML.
- Under SAML Settings, copy the signing key fingerprint.
- From the SP Meta Data section under App Settings, copy the SAML Metadata.
Technical Integration
| API | Method | Description | Reference |
|---|---|---|---|
| List SAML IdP Providers | GET | Retrieve all SAML Identity Provider configurations | View API |
| Create/Update SAML IdP | POST | Create or update SAML Identity Provider configuration | View 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 attributeemailoremailAddress - cidaas
given_name→ SAML attributefirstNameorgivenName
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 attributelastNameorsurname
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)
| Aspect | Description | What You Need | Configuration Location |
|---|---|---|---|
| SAML Metadata | cidaas 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 | |
| Signing | cidaas signs assertions using cidaas's private key | cidaas's private key (automatically managed) | Automatic - signing is always enabled for assertions |
| SPs validate signatures using cidaas's public certificate | cidaas's public certificate (included in metadata) | SPs receive certificate via SAML metadata | |
| Encryption | cidaas encrypts assertions for the SP (optional) | SP's public certificate | Set 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:
| Item | Purpose | Security Level | Notes |
|---|---|---|---|
| cidaas private key | Used to sign assertions | 🔒 Never share | Managed by cidaas automatically |
| cidaas public certificate | Shared via metadata for SPs to validate signatures | ✅ Safe to share | Included in SAML metadata |
| SP's public certificate | Needed if encryption is enabled | ✅ Safe to share | SP 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:
-
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.
- Login on the Admin interface.
- Click Login Provider in the left menu
- Click Login Providers -> SAML SP -> Create New SAML Service Provider.
SAML SP APIs
| API | Method | Description | Reference |
|---|---|---|---|
| List SAML SP Providers | GET | Retrieve all SAML Service Provider configurations | View API |
| Create SAML SP | POST | Create a new SAML Service Provider configuration | View API |
| Update SAML SP | PUT | Update an existing SAML Service Provider configuration | View 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
subor 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)
| 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 public certificate + cidaas's private key | Set 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:
| 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="...">orSAMLResponse - 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) andencryption_configin SAML settings - cidaas uses SP's public certificate to encrypt assertions
- SP decrypts using its private key
- Configure
- As SP:
- Configure
sp_encryption_certificate(cidaas's public certificate) andsp_encryption_private_key(cidaas's private key) - Share cidaas's public certificate with the IdP
- cidaas decrypts received assertions using its private key
- Configure
- Encryption is controlled by the
saml-encryptionfeature 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.

