SAML SSO Mapping

A SAML SSO Mapping references an Identity Provider (IdP), defines how the IdP attributes map to User fields (Username, Name, Email, and Role), and enables the IdP as a login option for Users.

By adding a SAML SSO Mapping, you can:

• Enable Just-in-Time (JIT) provisioning of Users on first successful SSO login.
• Map IdP group/role values to User roles (Admin or Read-only).
• Keep User profile data updated on each login.
• Control behavior when role data is missing or doesn't match (deny login or assign a default role).
• Support multiple IdPs, each with its own attribute mapping.

info

SSO is only available for Users. For Account authentication, refer to Login Methods.

Before You Begin

JIT Provisioning and Data Updates

First Login

When a User signs in via SSO for the first time and the assertion is valid, USP creates the User in USP Manager using the configured Username Attribute Name and the other configured mapping options.

If the Username Attribute Name is missing, or resolves to a value that already exists with a different Login Method (e.g., Standard or LDAP), the login is denied.

Subsequent Logins

The next times the User logs in, USP;

• Re-evaluates authorization against the current mapping rules.
• Updates User fields if they differ from the IdP assertion.
• Refreshes Updated At whenever any User data changes.

On User or Mapping Removal

If a User is removed from the IdP, or if the SSO configuration is deleted in USP:

• The User remains visible in the Users list but will no longer be able to log in.
• If the User authenticates again after an IdP has been replaced, they may be re-provisioned as a new User depending on whether the new provider emits a different value for the configured Username Attribute Name.

Configuring a SAML SSO Mapping

info

Before creating a SAML SSO Mapping, ensure that you already have a SAML SSO Configuration in place and know the Base URL of your USP Manager instance, which is required to generate the Redirect URI.

To add a SAML SSO Mapping, follow these steps:

1. From the Sidebar, click General > Auth Sources.
2. Click the SAML SSO Mapping card.
3. Click Add Mapping.
4. Complete the details for SAML SSO Mapping using the Field Descriptions table as a guide.
5. Click Save.

Field Descriptions

Name	Description	Specifications	Required
Name	The name of the SAML SSO Mapping.. This value is displayed as the label of the SSO button on the USP login page.	Must be unique. Must follow the Standard Naming Pattern.	Yes
Description	The description of the SAML SSO Mapping.		No
Identity Provider	The SAML SSO Configuration associated with this mapping.	Must reference an already created SAML SSO Configuration.	Yes
Username Attribute Name	The attribute to use as the unique user identifier. If not specified, the default NameID element will be used.	This value should be globally unique and not change over time (e.g., email, uid, userPrincipalName).	Yes
Email Attribute Name	The name of the attribute that contains the User's email address.		Yes
Name Attribute Name	The name of the attribute that contains the User's name (full name).		Yes
Group Attribute Name	The name of the attribute from which the role will be derived. This could be an existing attribute or a custom one, such as mftRole.		Yes
Base URL	The base URL of the USP Manager instance.	Must be the hostname where the USP application is accessible.	Yes
Full Redirect URI	The automatically generated complete redirect URI. If the name includes any of the following keywords, a corresponding IdP icon will appear on the login page: okta entra google auth0	Must be configured in your IdP as the callback URL for SAML authentication.	Yes
Group Attribute to Role Mapping	A two column table for linking IdP roles/groups to USP User roles	Enter the exact role/group name from your IdP for each USP role.	Yes
Missing or Unrecognized Role Policy	Specifies what to do if the Group Attribute to Role Mapping is not found or the role could not be identified. Options: Deny Assign default role		Yes
Default Role	The default role to assign if the Group Attribute to Role Mapping is not found or the role could not be identified. Options: Read-only Admin		Yes, if Missing or Unrecognized Role Policy is Assign default role.

Managing SAML SSO Mapping

Validating the Mapping

After adding the Mapping, you can easily validate the configuration following these steps:

1. From the USP Admin UI login page, click the SSO button corresponding to this mapping, or navigate directly to /login/saml/<mapping_name>.
2. Authenticate at the IdP and confirm you land in USP and that your User was created as expected.
3. If authentication fails, review the mapping fields and the USP logs.

Editing SAML SSO Mapping

To edit a SAML SSO Mapping, follow these steps:

1. From the Sidebar, click General > Auth Sources.
2. Click the SAML SSO Mapping card.
3. Click the SAML SSO Mapping you want to edit.
4. Complete the details for the SAML SSO Mapping using the Field Descriptions table as a guide.
5. Click Save.

SAML SSO Mapping Metadata

Each SSO Mapping Metadata includes all parameters listed in the Field Descriptions table, plus read-only metadata:

Name	Description
Created At	Date and time this SAML SSO Mapping was created.
Updated At	Date and time this SAML SSO Mapping was last updated.

Deleting SAML SSO Mapping

danger

Before deleting a SAML SSO Mapping, ensure that at least one User with Admin role and Standard authentication remains available. Otherwise, you may lose administrative access to USP Manager.

Deleting an SSO provider configuration is straightforward; however, you must plan what to do with any orphaned Users that have already been provisioned via the provider. Those options include:

Option	When to Choose	Result
Delete the Users	No plans to migrate to a new provider, or don't want to preserve Users records.	Users are removed from USP; if they authenticate later via an active SSO provider, they will be re-provisioned.
Migrate the Users to a new provider	You are moving to a different IdP and want to preserve existing User records.	Update each User's login method metadata to associate them with the new SSO provider; Users continue to log in without interruption.
Retain as orphaned	You need the records for auditing but do not want Users to log in.	Users remain visible but cannot authenticate; even with a new provider configured, their usernames remain tied to the deprecated provider.

To delete a SAML SSO Mapping, follow these steps:

1. From the Sidebar, click General > Auth Sources.
2. Click the SAML SSO Mapping card.
3. Click the SAML SSO Mapping you want to delete.
4. Click the Delete button above the SAML SSO Mapping details.
5. You will be asked to confirm the deletion. Click Delete.

info

If a mapping is deleted, existing SAML-provisioned Users remain listed in USP but cannot authenticate through that mapping. If you later create a new mapping for the same IdP and the user still meets the mapping rules, they can be re-provisioned on next login.