| Panel | ||||
|---|---|---|---|---|
|
Overview
| Note | ||
|---|---|---|
| ||
The information provided on this page assumes you have a working knowledge of SAML Single Sign-On. |
...
Universal Controller uses SAML Single Sign-On for authentication and Single Sign-On Settings User Provisioning. All user and group authorization must be configured within Universal Controller through Permission and Role assignment.
Terminology
IdP | Identity Provider (for example, Okta) | Third-party system that pre-authenticates SAML users. |
SAML | Security Assertion Markup Language | SAML is an XML-based protocol for exchanging security information between a SAML Identity Provider and a SAML Service Provider. |
SP | Service Provider (for example, Universal Controller) | Receives and accepts authentications via SAML Single Sign-On. |
SSO | Single Sign-On | Method of authentication. |
| Anchor | ||||
|---|---|---|---|---|
|
Single Sign-On Login
SAML Single Sign-On can be initiated by either Universal Controller, as the Service Provider, or the Identity Provider.
Only users designated with Single Sign-On as a Login Method can authenticate using SAML Single Sign-On. However, users designated with both Standard and Single Sign-On as a Login Method can continue to log into the Universal Controller using the standard application URL (see Logging In).
Service Provider-Initiated Login
Universal Controller, as a Service Provider, will initiate the SAML Single Sign-On login flow when an unauthenticated user accesses the web application through the following URL.
http(s)://<server:port>/uc/saml
Identity Provider-Initiated Login
Identity Provider-initiated SAML Single Sign-On begins at the Identity Provider, typically by accessing an application-specific Identity Provider URL. Once authenticated, the user will be taken to the Universal Controller web application.
Action URLs
Any Action URL parameters on the URL used by the SAML-authenticated user to access the Universal Controller web application are restored when the Service Provider-initiated SAML SSO authentication flow has completed successfully and the user has been redirected back to the Universal Controller web application.
| Note | ||
|---|---|---|
| ||
This is not applicable for an Identity Provider-initiated login. |
Session Expired
Universal Controller allows you to restore an HTTP session without leaving the application (or losing data) by prompting you to re-enter your login credentials in a Session Expired pop-up:
...
When the Identity Provider has authenticated you and the SAML SSO authentication flow has completed, click Continue on the original dialog to proceed, which closes the SAML SSO authentication flow window.
Administrator Account
Modification of the ops.admin account Login Method is not permitted; therefore, the account will always be accessible for cases where, for example, SAML Single Sign-On Settings are incorrectly configured or the Identity Provider is inaccessible.
| Anchor | ||||
|---|---|---|---|---|
|
Single Logout
Universal Controller supports SAML Single Logout for SAML-authenticated users, in accordance with the SAML 2.0 Single Logout profile.
...
| Note | ||
|---|---|---|
| ||
It is required that the configured Identity Provider metadata declares a Single Logout endpoint. |
User Sessions
The administrative functionality in the user interface that allows for management of User Sessions is applicable only for local Universal Controller sessions; therefore, expiring a user's session through this interface is only expiring the local Universal Controller session.
| Anchor | ||||
|---|---|---|---|---|
|
User Provisioning
The following diagram illustrates the expectations in Universal Controller for provisioning users from attributes available in the SAML assertion:
...
| Anchor | ||||
|---|---|---|---|---|
|
User Attribute Mapping
For Universal Controller to correlate SAML assertion attributes with Universal Controller user fields, Universal Controller must provide a way to configure a mapping between Universal Controller User fields and SAML assertion attributes.
...
Any user created by SAML assertion attributes, during the single sign-on process, is considered an Identity Provider-sourced user. See Single Sign-On Settings in Attribute Mappings in SAML Single Sign-On Settings.
User Field Defaults
Single Sign-On provisioned users are created with the following default field values:
Field | Value |
|---|---|
User Password | random, 32-characters |
Password Requires Reset | true |
Login Method | Single Sign-On |
Web Browser Access | - - System Default - - |
Command Line Access | - - System Default - - |
Web Service Access | - - System Default - - |
Group Membership Attribute Mapping
An additional configuration is provided to allow for assigning group membership using the SAML assertion. Universal Controller allows configuring which SAML assertion attribute contains the user's group membership.
...
If a group membership attribute mapping is specified, any time that an Identity Provider-sourced user authenticates using SAML Single Sign-On, its group membership will be updated based on the group attribute value in the accepted SAML assertion. The user will be added to, or removed from, groups accordingly.
SAML Configuration
Service Provider Metadata
Universal Controller is configured for automatic generation of Service Provider metadata. By default, the Service Provider Entity ID for a Universal Controller deployment is: https://uc.stonebranch.com/sp.
However, Universal Controller allows an administrator to customize the Service Provider Entity ID by specifying a Service Provider Entity ID Subdomain in the SAML Single Sign-On Settings in the user interface.
For example, an Service Provider Entity ID Subdomain value of dev would allow for a Service Provider Entity ID of https://dev.uc.stonebranch.com/sp.
SAML Endpoints
To generate the SAML endpoints for the Service Provider metadata, an SP Entity Base URL for Universal Controller must be determined. By default, Universal Controller uses information from first request after the Controller has been initiated to automatically generate a Service Provider Entity Base URL in the format scheme://server:port/contextPath.
...
To configure the SP Entity Base URL to a specific value, an administrator can specify the Service Provider Entity Base URL from the SAML Single Sign-On Settings in the user interface.
The following table documents the SAML endpoints, and their supported bindings, contained within the Universal Controller Service Provider metadata.
...
Universal Controller provides a Service Provider Metadata link, from the SAML Single Sign-On Settings, for downloading the Universal Controller Service Provider metadata file.
...
http(s)://<server:port>/uc/saml/metadata
Identity Provider Metadata
Universal Controller requires the Identity Provider configuration provided in the form of an IdP metadata XML file.
...
You can specify the location of the Identity Provider metadata file in the SAML Single Sign-On Settings Details of the user interface. By default, on initial start-up, the Controller automatically populates the Identity Provider metadata file setting with a value of ${catalina.base}/conf/saml/idp.xml.
For example, if ${catalina.base} resolves to /opt/tomcat, the Identity Provider metadata file setting would be populated with /opt/tomcat/conf/saml/idp.xml.
SAML KeyStore
SAML message exchanges required for the Web Browser SSO profile and the Single Logout profile involve usage of cryptography for the signing and encryption of data.
...
The location of the KeyStore File can be specified from the SAML Single Sign-On Settings in the user interface. However, by default, Universal Controller automatically populates the KeyStore File setting with a value of ${catalina.base}/conf/saml/samlKeystore.jks on initial start-up.
...
The JKS keystore password, the default private key alias, and the default private key password can also be specified from the SAML Single Sign-On Settings in the user interface. Each of these settings are populated with a default value of ucsaml on initial start-up.
...
| Panel |
|---|
keytool -exportcert -alias ucsaml -file ucsaml.cer -keystore samlKeystore.jks -storepass ucsaml -storetype JKS |
Java Cryptography Extension (JCE)
Universal Controller is configured to use signature algorithm SHA256withRSA and digest method algorithm SHA-256.
...
| Note | ||
|---|---|---|
| ||
Starting with Java 1.8.0_162, JCE unlimited policy is enabled by default. You no longer need to install the policy file in the JRE or set the security property crypto.policy. |
Debugging
The uc.saml.log.level property can be configured in the uc.properties to enable debug logging for the SAML framework. However, as a best practice, saml.log.level should remain at INFO under normal operation.
| Anchor | ||||
|---|---|---|---|---|
|
SAML Single Sign-On
...
An administrator can turn on/off and configure SAML Single Sign-On through the user interface.
| Note | ||
|---|---|---|
| ||
Each Universal Controller cluster node maintains its own SAML Single Sign-On Settings configuration, associated by Node Id. Therefore, you must complete the SAML Single Sign-On Settings configuration for each deployed cluster node, including the Active node and any Passive nodes. The Identify Provider Metadata File and KeyStore File, by default located under ${catalina.base}/conf/saml/, must be accessible to each cluster node. |
Step 1 | From the Administration navigation pane, select Configuration > SAML Single Sign-On Settings. The SAML Single Sign-On Settings page displays. |
|---|---|
Step 2 | Enter / select your SAML Single Sign-On Settings, using the field descriptions below as a guide.
|
Step 3 | Click the |
For information on how to access additional details - such as Metadata and complete database Details - for SAML Single Sign-On Settings (or any type of record), see Records.
| Anchor | ||||
|---|---|---|---|---|
|
SAML Single Sign-On
...
Field Descriptions
The following table describes the fields and buttons that display in the SAML Single Sign-On Settings.
Field Name | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|
Details | This section contains detailed information on the SAML Single Sign-On settings. | ||||||||
SAML Single Sign-On | If enabled, turns on SAML Single Sign-On. | ||||||||
| If enabled, turns on the provisioning of users through SAML assertion attributes. | ||||||||
SP Entity ID | Read-only; Unique identifier of the Universal Controller Service Provider. | ||||||||
SP Entity ID Subdomain | Customize the SP Entity ID with a unique subdomain. | ||||||||
SP Entity Base URL | Base URL to construct SAML endpoints from; must be a URL with protocol, server, port. and context path. If one is not specified, it defaults to values from the initial request in this format: | ||||||||
Identity Provider Metadata Source
| Specifies Identity Provider Metadata Source:
| ||||||||
Identity Provider Metadata File | If Single Sign-On Settings Identity Provider Metadata Source = File; Identity Provider metadata file location. | ||||||||
| Identity Provider Metadata URL | If Single Sign-On Settings Identity Provider Metadata Source = URL; Identity Provider metadata URL location. | ||||||||
| Link to download the Service Provider metadata for the Universal Controller node. | ||||||||
Key Management | |||||||||
KeyStore File | Keystore file location. | ||||||||
KeyStore Password | Password used to protect the integrity of the keystore. Default is ucsaml. | ||||||||
Private Key Alias | Alias of the private key (with either self-signed or CA-signed certificate) used to digitally sign SAML messages. Default is ucsaml. | ||||||||
Private Key Password | Password used to protect the integrity of the private key. Default is ucsaml. See Single Sign-On Settings SAML KeyStore. | ||||||||
| If Single Sign-On Settings User Provisioning is enabled; This section allows you to configure a mapping between user fields and attributes from the attribute statement of a SAML assertion. It is displayed only when Single Sign-On Settings User Provisioning is enabled. See Single Sign-On Settings User Attribute Mapping for more details. | ||||||||
First Name | Name of an attribute, of type | ||||||||
Middle Name | Name of an attribute, of type | ||||||||
Last Name | Name of an attribute, of type | ||||||||
Name of an attribute, of type | |||||||||
Active | Name of an attribute, of type | ||||||||
Groups | Name of a multi-valued attribute, of type | ||||||||
Title | Name of an attribute, of type | ||||||||
Department | Name of an attribute, of type | ||||||||
Manager | Name of an attribute, of type | ||||||||
Business Phone | Name of an attribute, of type | ||||||||
Mobile Phone | Name of an attribute, of type | ||||||||
Home Phone | Name of an attribute, of type | ||||||||
Buttons | This section identifies the buttons displayed above and below the SAML Single Sign-On Settings that let you perform various actions. | ||||||||
Update |
| ||||||||
Refresh | Refreshes any dynamic data displayed in the SAML Single Sign-On Settings. |
Default Configuration
Upon initial start-up of Universal Controller, a default SAML Single Sign-On Settings record is created and associated with the Universal Controller node by node id. The settings are specific to the Universal Controller node, as the SP Entity ID, Base URL, and File paths may differ between each Universal Controller node. See SAML Single Sign-On SettingsField Descriptions, above, for the default configuration.
Security
SAML Single Sign-On Settings can be viewed only by users with the ops_admin role, regardless of Navigation Visibility; therefore, only users with the ops_admin role can update SAML Single Sign-On Settings.
Bulk Import/Export
Any SAML Single Sign-On Settings record in the database that has a corresponding Universal Controller node is exported to ops_single_sign_on.xml during the Bulk Export server operation.
SAML Single Sign-On Settings being updated through the Bulk Import server operation are applied immediately; however, you can update the SAML Single Sign-On Settings only for the node you are performing the Bulk Import on.
| Anchor | ||||
|---|---|---|---|---|
|
Troubleshooting
NameID
The SAML Subject NameID from the SAML assertion received from the Identity Provider correlates directly to the User ID field of a user record in the Universal Controller database.
- If User Provisioning is off, the NameID must match with the User ID field of an existing user record in the Universal Controller database.
- If User Provisioning is on, any provisioned user record will be assigned a User ID equivalent to the NameID.
Login Errors
Universal Controller Uninitialized | While the Universal Controller web application is initializing, the user login flow cannot proceed. Any users attempting to authenticate with SAML at this time receive the following error: |
|---|---|
User Account Not Found | Any SAML-authenticated user who cannot be linked to a user account in the Universal Controller database is prohibited from accessing the application and receives the following error: |
User Account Not Active | Any SAML-authenticated user linked to a Universal Controller user account that is not Active is prohibited from accessing the application and receives the following error: |
Login Method | Any SAML authenticated user linked to a Universal Controller user account that is not designated to use Single Sign-On login method is prohibited from accessing the application and receives the following error: |
User Account Locked | Any SAML-authenticated user linked to a Universal Controller user account that is locked is prohibited from accessing the application and receives the following error: |
No Web Browser Access | Any SAML-authenticated user linked to a Universal Controller user account designated with the Single Sign-On login method, but without Web Browser Access, is prohibited from accessing the application and receives the following error: |
...