Your suggested change has been received. Thank you.

close

Suggest A Change

https://thales.na.market.dpondemand.io/docs/dpod/services/kmo….

Thales Logo

All

  • All
back

IDAAS core - Access

SAML Applications

search

SAML Applications

The Access component implements OpenID Connect and the Security Assertion Markup Language (SAML) 2.0 protocol to enable secure single sign-on (SSO) authentication and single logout (SLO) across multiple applications and services. SAML is an XML-based standard that allows users to authenticate once with the identity provider (IDP) and then access multiple service providers (SPs) without having to re-enter their credentials.

Think of the IDP as a trusted authentication service that acts as a central hub for user identity verification. When a user tries to access a protected application (service provider), instead of logging in directly to that application, they are redirected to this IDP to authenticate. After the IDP authenticates the user, the IDP provides the application with a secure assertion that confirms the user's identity and authentication status. The Access component supports both OIDC and SAML, which means it can log in and log out a user in a browser independently of the protocol that is used.

Single sign-on flows

The Access component's IDP supports both major SSO initiation patterns:

SP-initiated SSO

This is the more common flow where users attempt to access a protected application directly. The service provider detects that the user is not authenticated and redirects them to the IDP for authentication. After successful authentication at the IDP, the user is automatically redirected back to the original application with proper authentication credentials.

Use case: Suitable for scenarios where users bookmark or directly navigate to specific applications they need to use.

IDP-initiated SSO

In this flow, users start their session by logging in to the IDP directly (for example, through a user portal or dashboard). After authentication, they can click links or tiles to access various applications without additional login prompts. The IDP generates and sends SAML assertions to the target service providers on behalf of the authenticated user.

Use case: Suitable for organizations with a central user portal where employees access all their applications from one location.

SAML binding support

SAML bindings define how SAML messages are transported between the IDP and service providers. The Access component's IDP supports multiple binding types to ensure compatibility with various applications:

  • HTTP-POST binding

    SAML messages are embedded in HTML forms and transmitted via HTTP POST requests. This method can handle larger SAML assertions and provides better security because the SAML data is not visible in browser URL bars or server logs.

  • HTTP-redirect binding

    SAML messages are encoded and transmitted as URL parameters through HTTP redirects. This method is simpler to implement but has size limitations due to browser URL length restrictions.

  • Artifact binding

    This is a two-step process where a small artifact (reference token) is first sent via HTTP redirect, and then the service provider uses a separate back-channel SOAP request to retrieve the actual SAML assertion from the IDP. This method provides enhanced security and can handle large assertions while keeping browser interactions lightweight.

Authentication context and request handling

Requested authentication context

To specify the level of authentication assurance they require, service providers can include a RequestedAuthnContext element in their authentication requests. This allows applications to request specific authentication methods or strength levels. The Access component allows only an exact comparison (Comparison="exact"). However, your SPs can request multiple levels that it accepts.

The IDP evaluates these requests and either satisfies the requirement with an appropriate authentication method or denies access if the requested level cannot be met.

Passive authentication requests

To make passive authentication requests, service providers can set the IsPassive attribute to true. In passive mode, the IDP only authenticates the user if they already have an active session. If no active session exists, the IDP does not prompt for credentials but instead returns an authentication failure response.

Use case: Useful for background authentication checks or when applications want to verify user authentication status without interrupting the user experience with login prompts.

Authentication request examples

The following are examples of SAML authentication requests (AuthnRequest) that service providers might send to the IDP:

Basic SP-initiated authentication request

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6"
    Version="2.0"
    IssueInstant="2024-12-01T10:39:34Z"
    Destination="https://your-idp-domain.com/saml/sso"
    AssertionConsumerServiceURL="https://sp.example.com/saml/acs"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">

    <saml:Issuer>https://sp.example.com</saml:Issuer>
</samlp:AuthnRequest>

Authentication request with a specific authentication context

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6"
    Version="2.0"
    IssueInstant="2024-12-01T10:39:34Z"
    Destination="https://your-idp-domain.com/saml/sso"
    AssertionConsumerServiceURL="https://sp.example.com/saml/acs"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST">

    <saml:Issuer>https://sp.example.com</saml:Issuer>

    <samlp:RequestedAuthnContext Comparison="exact">
        <saml:AuthnContextClassRef>
            urn:onewelcome:broker:v1:apple:auth
        </saml:AuthnContextClassRef>
    </samlp:RequestedAuthnContext>
</samlp:AuthnRequest>

Passive authentication request

<samlp:AuthnRequest
    xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    ID="_8e8dc5f69a98cc4c1ff3427e5ce34606fd672f91e6"
    Version="2.0"
    IssueInstant="2024-12-01T10:39:34Z"
    Destination="https://your-idp-domain.com/saml/sso"
    AssertionConsumerServiceURL="https://sp.example.com/saml/acs"
    ProtocolBinding="urn:oasis:names:tc:SAML:2.0:bindings:HTTP-POST"
    IsPassive="true">

    <saml:Issuer>https://sp.example.com</saml:Issuer>
</samlp:AuthnRequest>

Authentication responses

User identification and NameID format

This IDP uses a specific approach to user identification that prioritizes privacy and consistency across all service provider integrations.

NameID format and content

The IDP exclusively uses the following NameID format for all SAML assertions:

urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified

NameID value: The IDP sends only the user's Universally Unique Identifier (UUID) as the NameID value. This UUID is a system-generated, unique identifier that remains constant for each user across all service provider interactions.

Example NameID in SAML assertion

<saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:unspecified">
        a1b2c3d4-e5f6-7890-ab12-cd34ef567890
    </saml:NameID>
    <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
        <saml:SubjectConfirmationData
            NotOnOrAfter="2024-12-01T11:39:34Z"
            Recipient="https://sp.example.com/saml/acs"/>
    </saml:SubjectConfirmation>
</saml:Subject>

Implementation considerations for service providers

Since the NameID contains only a UUID and not human-readable information like email addresses or usernames, service providers must rely on SAML assertion attributes to obtain user information such as:

  • Email address
  • Customer number
  • Username
  • Phone number
  • Other user properties

Service providers should map and store the UUID from the NameID as the primary user identifier, while using assertion attributes for user display and application logic.

Logout capabilities

SP-Initiated SLO

Service providers can initiate logout requests to terminate user sessions across all connected applications. When a user logs out from one application, the IDP coordinates logout across all other service providers where the user has active sessions.

Selective logout control

Administrators can configure specific service providers to be excluded from SLO operations. This is useful for applications that need to maintain persistent sessions or have special logout requirements.

Integrated OIDC and SAML logout

The Access component's IDP features deep integration between SAML and OpenID Connect (OIDC) protocols. When a user authenticates through either SAML or OIDC, they establish a unified session that spans both protocols.

SLO needs some additional configuration. For SAML applications, the SP metadata needs to define a SingleLogoutService binding. Web clients with an OIDC scope need to define a front-channel logout URL.

Unified logout behavior:

  • A logout initiated through any SAML service provider terminates sessions across all SAML SPs and all OIDC relying parties (RPs).

  • A logout initiated through any OIDC relying party terminates sessions across all OIDC RPs and all SAML service providers.

This ensures complete session cleanup, regardless of which protocol or application initiated the logout.

This integration prevents session leakage and security vulnerabilities that could occur if users remained logged in to applications using different protocols.

SAML metadata

IDP metadata

The IDP publishes its metadata document at an endpoint that contains all the technical information service providers need to establish trust and communication. When you register a SAML application in the OneWelcome Identity Platform, the location for the IDP metadata is shown at the top of the SAML application page. If your tenant has multiple domains, such as a domain for each brand, there is a metadata document for each domain.

The metadata includes:

  • Entity ID is a unique identifier for this IDP.

  • SSO service endpoints are URLs for different binding types (POST, Redirect, Artifact).

  • Single logout service endpoints are URLs for coordinating logout operations.

  • Signing certificates are public keys used to verify SAML assertion signatures.

  • Supported name ID formats are types of user identifiers that the IDP can provide.

  • Metadata location is where IDP metadata can be accessed:

    https://your-idp-domain.com/oauth/saml-idp/metadata

Service provider metadata

To establish a new service provider connection, administrators must upload or configure the SP's metadata document. The SP metadata contains essential information, including:

  • Entity ID is a unique identifier for the service provider.

  • Assertion consumer service URLs determine where the IDP should send SAML assertions.

  • Single logout URLs are endpoints for logout coordination.

  • Required attributes provide user information that the SP needs to function.

  • Certificate information provides public keys for encryption and signature verification.

Register an application via SAML

  1. Obtain the SP metadata from the application vendor or generate it through the application's configuration.

  2. Log in to the OneWelcome Identity Platform console. If you have more than one tenant, select the tenant.

  3. Browse to Core > Applications, click Add Application, and select SAML.

  4. Under Basic information, enter a Display name for your application.

    Add SAML application

  5. Under SAML SP configuration, provide the SP metadata URL or SP metadata.

    • To provide the SP metadata URL, select URL and enter the URL.

    • To provide the SP metadata, select XML and enter the metadata XML.

    SAML SP configuration

  6. Choose the logout control behavior for this service provider:

    • To include the SP in SLO, do not select the SLO disabled check box. This is standard behavior where the SP participates in a coordinated logout.

    • To exclude the SP from SLO, select the SLO disabled check box. The SP maintains its session even when SLO is initiated from other applications. This is useful for applications that need to maintain persistent sessions or have special logout requirements.

  7. To allow IDP-initiated SSO flows, select the Enable IDP-initiated SSO check box.

    SP-initiated SSO flows are always allowed.

  8. To add additional attributes to the SAML assertion, or to determine whether users are authorized under specific conditions, link an Authentication Response Web Hook.

    You define these web hook configurations on the Access admin console.

  9. To specify the assurance level to use if the authentication request doesn't specify one, select the Default Authentication Context Class References.

  10. Under Identity provider, select the Default identity provider that you want to use for this application.

    Identity providers

    You configure these identity providers on the Access admin console.

  11. Under Additional identity providers, select any additional IDPs that the SP can select in the authentication request.

    You can link multiple IDPs to a single SAML SP, so that you can use the same SAML SP for both business-to-customer and employee logins.

    In the authentication request, you can overwrite the default IDP. This is only possible if the requested IDP is part of the additional IDPs that you define when you register an application via SAML. To request one of these additional IDPs in the authentication request, use the Scoping element:

    xml <samlp:Scoping> <samlp:IDPList> <samlp:IDPEntry ProviderID="https://idp.example.com/entity"/> </samlp:IDPList> </samlp:Scoping>

  12. Select Submit.

  13. Test the integration using both IDP-initiated and SP-initiated flows.

Troubleshooting SAML integrations

The IDP provides detailed logging and diagnostic information to help identify and resolve integration issues quickly.

When troubleshooting SAML integration issues, common areas to check include:

  • Clock synchronization between the IDP and SP systems

  • Certificate validity and proper configuration

  • Expired or outdated SP or IDP metadata

  • Correct URL configuration for SSO and SLO endpoints

  • Attribute mapping and name ID format compatibility

  • Network connectivity for back-channel communications (especially for artifact binding)

On this page