SAML applications

The OneWelcome Identity Platform 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 OneWelcome Identity Platform supports both OIDC and SAML, which means it can log in and log out a user independently of the protocol that is used.

Single sign-on flows

The OneWelcome Identity Platform's IDP supports the two main SSO initiation patterns:

• SP-initiated SSO

• IDP-initiated SSO

SP-initiated SSO

SP-initiated SSO is the more common flow where users attempt to access a protected application directly. The SP 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 navigate directly to the specific applications that they need to use.

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

IDP-initiated SSO

With IDP-initiated SSO, 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 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 OneWelcome Identity Platform'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 OneWelcome Identity Platform 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.

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

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

NameID format in authentication requests

This example demonstrates how a service provider can request a specific NameID format. The IDP supports only the Format attribute in the NameIDPolicy element.

Example: Authentication request with specific NameID format

<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:NameIDPolicy Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress"/>
</samlp:AuthnRequest>

Authentication responses

User identification and NameID format

The IDP provides flexible user identification through support for multiple NameID formats, allowing service providers to request the user identifier format that best suits their requirements.

Supported NameID formats

The IDP supports the following NameID formats:

In authentication requests, the IDP supports only the Format attribute in the NameIDPolicy.

NameID format selection logic

The IDP determines which NameID format to use based on the following priority order:

┌─────────────────────────────────────────────────────┐
│ 1. Explicit NameID in AuthnRequest                  │
│    Does the SP request a specific format via the    │
│    NameIDPolicy in the authentication request?      │
└────────────┬────────────────────────────────────────┘
             │ No
             ▼
┌─────────────────────────────────────────────────────┐
│ 2. First Match from SP metadata                     │
│    Use the first format from the SP metadata list   │
│    that the IDP supports and has a mapping for      │
└────────────┬────────────────────────────────────────┘
             │ No match / Not available
             ▼
┌─────────────────────────────────────────────────────┐
│ 3. Fallback to unspecified                          │
│    Use urn:oasis:names:tc:SAML:1.1:nameid-format:   │
│    unspecified as the final fallback                │
└─────────────────────────────────────────────────────┘

NameID attribute mapping

The selected NameID format must have a configured attribute mapping (either default or custom). The mapped attribute must be available during authentication.

You can configure attribute mappings for each supported NameID format. During the mapping configuration, you can:

• Select an attribute from a list of available user attributes.
• Define a custom attribute name if needed.

Example: NameID in SAML assertion

<saml:Subject>
    <saml:NameID Format="urn:oasis:names:tc:SAML:2.0:nameid-format:persistent">
        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>

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 OneWelcome Identity Platform's IDP features deep integration between the SAML and 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. The NameID formats will be included here if at least one Service Provider has a (default) mapping.

• Metadata location is where you can access the IDP metadata:

  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.

   

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.

   

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.

    

    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)