SAML SSO
A SAML SSO Configuration defines the connection and trust settings between USP and an external Identity Provider (IdP), enabling Single Sign-On (SSO) for Users of the USP Admin UI.
To use an IdP, you must also create a SAML SSO Mapping that references this Configuration and specifies how IdP attributes map to USP User fields (Username, Email, Name, and Role).
SAML SSO Administration via USP Admin UI
Adding a SAML SSO Configurations
Set up an IdP before creating a SAML SSO configuration. At minimum, have the IdP's SSO URL and CA certificate ready.
To add a SAML SSO Configuration, follow these steps:
- From the Sidebar, click Authentication > SSO.
- Click the SAML card.
- Click Add SAML SSO.
- Complete the details for the new SAML SSO Configuration using the Field Descriptions table as a guide.
- Click Save.
Field Descriptions
| Name | Description | Specifications | Required |
|---|---|---|---|
| Name | The name of the SAML SSO Configuration. |
| Yes |
| Description | The description of the SAML SSO Configuration. | No | |
| Identity Provider (IdP) SSO URL | The IdP's SSO endpoint URL where Users are redirected to authenticate during login. | Yes | |
| Service Provider (SP) Entity ID (Issuer) | A unique identifier for your SP (entity issuer) that the IdP recognizes. | Yes | |
| Audience URI (Expected Audience) | The identifier the IdP includes in the SAML assertion to indicate the intended recipient (this SP). |
| Yes |
| CA Certificate | The Certificate used to verify the signature on the SAML response from the IdP. | Must reference an already created CA Certificate. | Yes |
| Sign Requests | If enabled, the SAML requests are signed using the Signing Certificate. | No | |
| Canonicalizer | The algorithm used for the normalization step during the XML signature. Options:
| Yes, if Sign Requests is enabled. | |
| Signing Certificate | The TLS Certificate that is used to sign the SAML requests. | Must reference an already created TLS Certificate. | Yes, if Sign Requests is enabled. |
Editing a SAML SSO Configuration
To edit a SAML SSO Configuration, follow these steps:
- From the Sidebar, click Authentication > SSO.
- Click the SAML card.
- Click the Name of the SAML SSO Configuration you want to edit.
- Click the Edit button above the SAML SSO Configuration details.
- Edit the details of the SAML SSO Configuration using the Field Descriptions table as a guide.
- Click Save.
If you modify a SAML SSO Configuration that is currently in use by a USP Server instance, the changes will not take effect until you manually apply the updated configuration by pushing it to the server. To apply the changes:
- Navigate to Monitoring > Status.
- Click the Name of the associated USP Server instance.
- Go to the Configuration tab.
- Review the pending changes in the Updated Configuration column.
- If the changes are correct, click Push Configuration.
SAML SSO Configuration Metadata
SAML SSO Configuration details include all parameters given in the Field Descriptions table, plus the following read-only metadata:
| Name | Description |
|---|---|
| ID | Universally Unique Identifier of this SAML SSO Configuration. |
| Created | Date and time this SAML SSO Configuration was created. |
| Updated | Date and time this SAML SSO Configuration was last updated. |
Enabling/Disabling a SAML SSO Configuration
SAML SSO configurations can be Enabled or Disabled to control whether they can be used for User authentication. By default, new Configurations are Enabled, but their status can be changed at any time.
- Enabled (default): The provider is active and available for authenticating Users.
- Disabled: The provider is inactive, and Users associated with it will be unable to log in.
To enable or disable an SSO provider, follow these steps:
- From the Sidebar, click Authentication > LDAP.
- Click the SAML card.
- Click the Name of the SAML SSO Configuration you want to enable/disable.
- Click the Enable or Disable button above the SAML SSO Configuration details, depending on the current status.
Disabling a SAML SSO Configuration blocks new login attempts for associated Users. Existing sessions remain active until they expire or the User logs out.
Deleting a SAML SSO Configuration
Deleting a SAML SSO 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 |
|---|---|---|
| Manually 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 Configuration, follow these steps:
- From the Sidebar, click Authentication > LDAP.
- Click the SAML card.
- Click the Name of the SAML SSO Configuration you want to delete.
- Click the Delete button above the SAML SSO Configuration details.
- You will be asked to confirm the deletion. Click Delete.
USP Manager prevents deletion of a SAML SSO Configuration if it is currently referenced by a SAML SSO Mapping.
Additionally, if the SAML SSO Configuration is used by a USP Server instance, the updated configuration must be manually applied. To apply the changes:
- Navigate to Monitoring > Status.
- Click the Name of the associated USP Server instance.
- Go to the Configuration tab.
- Review the pending changes in the Candidate Configuration - Preview section.
- If the changes are correct, click Push Configuration.
The changes do not take effect on the server until this step is completed.