SAML SSO Integration Guide

This guide provides an overview of how to configure SAML Single Sign-On (SSO) between Multi-Pass and a third-party Service Provider (SP).

Multi-Pass acts as the Identity Provider (IdP) in this federation model.

Multi-Pass is working on SCIM support to enable automated user and group provisioning.

Make sure you have:

A Multi-Pass Dashboard account with administrative privileges.
Identified the correct tenant if your dashboard manages multiple tenants.

In this guide, we refer to your tenant as <TENANT_NAME>.

Admin access for that tenant.

Configure the Service Provider

Create a SAML profile in your SP’s admin portal using the following parameters from Multi-Pass:

Setting	Value
Name	Multi-Pass (Display Name)
IdP Entity ID	https://ca.auth.kzero.com/realms/<TENANT_NAME>
Sign-In URL	https://ca.auth.kzero.com/realms/<TENANT_NAME>/protocol/saml
Sign-Out URL	https://ca.auth.kzero.com/realms/<TENANT_NAME>/protocol/saml
Change Password URL	https://ca.auth.kzero.com/realms/<TENANT_NAME>/account
SAML Metadata URL	https://ca.auth.kzero.com/realms/<TENANT_NAME>/protocol/saml/descriptor

Download the X.509 Certificate

To obtain the signing certificate:

Open the SAML metadata descriptor in your browser.

https://ca.auth.kzero.com/realms/<TENANT_NAME>/protocol/saml/descriptor

Locate the <ds:X509Certificate> tag.
Open a text editor and paste:

-----BEGIN CERTIFICATE-----

[Paste the certificate from the XML]

-----END CERTIFICATE-----

Save it as a .pem or .txt file if required by your SP.

All elements in the URLs (like <TENANT_NAME>) are case sensitive. Match your configuration exactly.

What Each Field Means

IdP Entity ID

Unique identifier of Multi-Pass as IdP.
Used by the SP to verify the source of the SAML assertions.
Also called: IdP Issuer URI, Issuer ID, SAML Issuer URL, Identity Provider Identifier, IDP Entity ID, Identity Provider Issuer

Sign-In URL

Where the user is redirected to authenticate.
Also called: IDP SSO URL, IDP Sign-in URL, ID Provider Login URL, IDP ACS URL, Sign-in Page URL, Sign in Url, SAML Login Endpoint, SAML Sign-in URL, SAML SSO URL, SAML 2.0 URL, SSO Login URL, SSO Endpoint, Sign-in Endpoint, Login URL, Sign on URL, Identity Provider single sign-on URL, Remote Login URL

Sign-Out URL

Where the user is sent to terminate their session.
Also called: IdP Single Sign-On URL, Sign-out Endpoint, Sign out Url, IDP Single logout service URL, ID Provider Single Logout URL

Change Password URL

A redirect path used for password update/reset.

Multi-Pass is passwordless, but some SPs require a placeholder.

Signing Certificate

Verifies the integrity of the SAML assertion.
Signature method: RSA-SHA256
Digest method: SHA256
Also called : x509 Certificate, Signing Certificate, Key x509 Certificate, Certificate Fingerprint (requires only the footprint), SAML Fingerprint, IdP Signature Certificate

Configure Multi-Pass (IdP)

Multi-Pass offers two configuration interfaces:

The Legacy Advanced Console
The New Recommended Dashboard interface

You will need to collect the following from your Service Provider:

SP Detail	Meaning
Entity ID	Unique identifier of the Service Provider (e.g., Audience URI)
ACS URL	Endpoint where SAML responses are posted (Assertion Consumer Service URL)
Relay State (optional)	Destination URL after successful login (e.g., user dashboard)

Terminology may vary depending on the SP:

Entity ID = SP Entity ID, Audience

ACS URL = Assertion Consumer Service URL

Best Practices & Notes:

Ensure user emails in the SP match those in Multi-Pass.
Users migrated to SSO must log in via Multi-Pass only.
After configuration, test authentication flows using non-critical accounts.
Check if your SP requires signing AuthnRequests or enabling SLO (Single Logout).

Configure a SAML Client in Multi-Pass (Legacy Advanced Console)

This guide explains how to configure a new SAML client in the Multi-Pass Advanced Console and optionally add user attributes to be included in SAML responses.

Access the Advanced Console

Open Multi-Pass Dashboard
Select the tenant you want to configure.
Click on Advanced Console from the left menu.
In the menu, click on Clients.
Click on Create Client.

Create the Client

Leave all other settings as default unless your SP requires specific values.

Fill in the following settings:

Field	Value
Client Type	SAML
Client ID	<Entity URL> from your Service Provider
Name	Service Provider Name (e.g. halopsa)

Click Save

Configure SAML Settings

Go back into the newly created client and complete the configuration under each tab.

Settings Tab

Field	Value
Valid Redirect URIs	<ACS URL> from your SP
IDP-Initiated SSO URL Name	SP name (lowercase, no spaces)
Home URL	https://ca.auth.kzero.com/<TENANT_NAME>/protocol/saml/clients/<SSO_Name>
Relay State	Optional
Name ID Format	email
Force Name ID Format	ON
Sign Documents	OFF
Sign Assertions	ON

Keys Tab

Field	Value
Client Signature Required	OFF

Advanced Tab

Field	Value
Assertion Consumer Service POST Binding URL	<ACS URL from your SP>

Click Save when done

Add User Attributes (Optional)

Some Service Providers may require additional user attributes in the SAML response. These are typically mapped using User Property mappers.

To add user attributes:

In the left menu, go to Clients.
Select your newly created client.
Navigate to the Client Scopes tab.
Select the scope ending in -dedicated (e.g., halopsa-dedicated).
Click on Configure a new mapper > User Property.
Choose one of the following User Properties:

username – Username of the user
firstName – First name (given name)
lastName – Last name (surname)
email – Email address

Enter a SAML Attribute Name (as expected by the SP).
Click Save.

Repeat the process for each required user attribute. Check your Service Provider’s documentation for required SAML attributes. Additional user attributes are included in thesaml:AttributeStatement element within the SAML response. Each user attribute isrepresented as a separate saml:Attribute entry.

Example :

<saml:Attribute FriendlyName="UserAttributeFriendlyName"
Name="UserAttributeSAMLAttributeName"
NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
    <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
        username
    </saml:AttributeValue>
</saml:Attribute>

Understanding the SAML Response from Multi-Pass

When a user authenticates successfully, Multi-Pass sends a SAML response to the Service Provider (SP).

This SAML response is an XML document that follows the SAML 2.0 protocol standards.

Key Sections in a SAML Response :

saml:Subject

Identifies the user that the SAML assertion refers to.
Critical for the SP to know who is authenticated.
saml:NameID / The user's unique identifier (e.g., username or email address). The format can vary: urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress or others.

saml:AttributeStatement

Provides additional metadata about the user.
Typically contains:

Email address
User roles
Department
Any other custom attributes needed by the SP for authorization or user personalization.

dsig:Signature

A digital signature included in the assertion or parts of the SAML message.
Ensures:

Integrity – Confirms that the assertion wasn't modified during transit.
Authentication – Confirms the message comes from a trusted Identity Provider (IdP).
Non-repudiation – Prevents the sender from denying the message if the private key is secure.

Example: SAML Response Template:

<samlp:Response xmlns:samlp="urn:oasis:names:tc:SAML:2.0:protocol"
    xmlns:saml="urn:oasis:names:tc:SAML:2.0:assertion"
    Destination="SP ACS URL">
    <saml:Issuer>https://ca.auth.kzero.com/realms/TENANT_ID</saml:Issuer>
    <samlp:Status>
        <samlp:StatusCode Value="urn:oasis:names:tc:SAML:2.0:status:Success" />
    </samlp:Status>
    <saml:Assertion xmlns="urn:oasis:names:tc:SAML:2.0:assertion">
        <saml:Issuer>https://ca.auth.kzero.com/realms/kzero</saml:Issuer>
        <dsig:Signature xmlns:dsig="http://www.w3.org/2000/09/xmldsig#">
        </dsig:Signature>
        <saml:Subject>
            <saml:NameID Format="urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress">
                email@email.com
            </saml:NameID>
            <saml:SubjectConfirmation Method="urn:oasis:names:tc:SAML:2.0:cm:bearer">
                <saml:SubjectConfirmationData Recipient="SP ACS URL" />
            </saml:SubjectConfirmation>
        </saml:Subject>
        <saml:Conditions>
            ...
        </saml:Conditions>
        <saml:AuthnStatement>
            <saml:AuthnContext>
                <saml:AuthnContextClassRef>urn:oasis:names:tc:SAML:2.0:ac:classes:unspecified</saml:AuthnContextClassRef>
            </saml:AuthnContext>
        </saml:AuthnStatement>
        <saml:AttributeStatement>
            <saml:Attribute Name="Role"
                NameFormat="urn:oasis:names:tc:SAML:2.0:attrname-format:basic">
                <saml:AttributeValue xmlns:xs="http://www.w3.org/2001/XMLSchema"
                    xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:type="xs:string">
                    role-name
                </saml:AttributeValue>
            </saml:Attribute>
        </saml:AttributeStatement>
    </saml:Assertion>
</samlp:Response>

Destination in the response must match the ACS URL configured in the SP.

The Signature ensures that the message has not been tampered with and is issued by the expected Identity Provider.

Attributes inside AttributeStatement must match what the SP expects for successful authorization.