Overview
Note
The information provided on this page assumes you have a working knowledge of SAML Single Sign-On.
Universal Controller enables Web Browser Single Sign-On (SSO) through Security Assertion Markup Language 2.0 (SAML 2.0).
SAML 2.0 is an XML-based protocol for exchanging security information between a SAML Identity Provider and a SAML Service Provider.
As a SAML Service Provider, Universal Controller accepts authentication assertions from a configured SAML Identity Provider compliant with the SAML 2.0 Web Browser Single Sign-On profile.
SAML Single Sign-On eliminates the need for application-specific passwords. Universal Controller issues an authentication request to the configured Identity Provider, through the web browser, for any unauthenticated user accessing the Universal Controller web application through the SAML Login URL.
Universal Controller uses SAML Single Sign-On for authentication and 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. |
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:
If you are a SAML-enabled user, the Controller allows you to initiate the SAML Single Sign-On authentication flow without leaving the application. On the Session Expired pop-up, instead of entering your login credentials, simply click the Login button to initiate the SAML SSO authentication flow..
If only your Universal Controller session has expired, and not your session with the Identity Provider, you are logged in without being prompted for your credentials. Click Continue on the original dialog to proceed, which closes the SAML SSO authentication flow window.
If your session with the Identity Provider has expired, you are prompted for its login credentials.
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, Single Sign-On Settings are incorrectly configured or the Identity Provider is inaccessible.
Single Logout
Universal Controller supports SAML Single Logout for SAML-authenticated users, in accordance with the SAML 2.0 Single Logout profile.
By initiating the Logout menu option, a SAML-authenticated user is initiating Single Logout.
The Single Logout profile terminates the session at the originating Service Provider (Universal Controller), the Identity Provider session, and, potentially, sessions at other Service Providers connected to the same Identity Provider session, depending on the Identity Provider implementation.
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.
User Provisioning
The following diagram illustrates the expectations in Universal Controller for provisioning users from attributes available in the SAML assertion:
As illustrated, when LDAP synchronization is enabled, provisioning of users through LDAP synchronization takes precedence over provisioning of users through the SAML assertion during the Single Sign-On process.
During the next scheduled LDAP refresh, consistent with locally created users and groups, any Identity Provider-sourced user or group matching a user or group synchronized from the LDAP automatically is converted to an LDAP-sourced user or group.
Once a user has been provisioned (created) in the Universal Controller database, its Source (ldap:dn or idp:remote-entity-id) determines how the user record is refreshed during the next login through single sign-on.
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.
The following Universal Controller user fields are mappable.
- User Id (Required)
(This field automatically is mapped to the SAML Subject NameID from the SAML assertion and cannot be changed.) - First Name (Required)
- Middle Name
- Last Name
- Title
- Department
- Manager
(This field is a reference to another user and is mapped only if the attribute value contains the Name of a valid Universal Controller user.) - Business Phone
- Mobile Phone
- Home Phone
- Active
Any user created by SAML assertion attributes, during the single sign-on process, is considered an Identity Provider-sourced user. See Attribute Mappings in 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.
To support multiple groups, the attribute is multi-valued, where each attribute value specifies the Group Name of a Universal Controller group for which the user belongs. If the Universal Controller group is not already provisioned, it is provisioned automatically as an Identity Provider-sourced group.
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 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
.
For example: https://example.stone.branch:443/uc
To configure the SP Entity Base URL to a specific value, an administrator can specify the Service Provider Entity Base URL from the 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.
SAML Profile | Binding | Endpoint |
---|---|---|
Web Single Sign-on | HTTP-POST | scheme://server:port/contextPath/saml/SSO |
Single Logout | HTTP-POST, HTTP-Redirect | scheme://server:port/contextPath/saml/SingleLogout |
Universal Controller provides a Service Provider Metadata link, from the Single Sign-On Settings, for downloading the Universal Controller Service Provider metadata file.
Alternatively, you can download the metadata file directly using the following URL:
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 download the Identity Provider metadata file from the Identity Provider and save it under the Tomcat conf/
directory, in a saml/
subdirectory.
You can specify the location of the Identity Provider metadata file in the 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 Universal Controller requires a single JKS keystore that contains all private and public keys. The keystore must have one default private key.
To create the JKS keystore file, with the default private key, assuming your Identity Provider does not require keys be signed by a specific certification authority, you can use the Java utility keytool command to generate a self-signed key, entering the distinguished name information when prompted.
keytool -genkeypair -keyalg RSA -sigalg SHA256withRSA -alias ucsaml -keypass ucsaml -keystore samlKeystore.jks -storepass ucsaml -storetype JKS
To import a key signed by a certification authority, which are typically provided in .p12/.pfx format (or can be converted to .p12/.pfx format using OpenSSL), you can use the following keytool command.
keytool -importkeystore -srckeystore key.p12 -srcstoretype PKCS12 -srcstorepass password -alias alias -destkeystore samlKeystore.jks -destalias ucsaml -destkeypass ucsaml
To determine the alias available in the p12 file, you can use the following command.
keytool -list -keystore key.p12 -storetype pkcs12
If your Identity Provider metadata is signed, to verify trust of the signature, Universal Controller will use all keys found in the configured keystore. To import the public certificate of the metadata signature, you can use the following keytool command.
keytool -importcert -alias alias -keystore samlKeystore.jks -file signature.cer
The location of the KeyStore File can be specified from the 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.
For example, if ${catalina.base
} resolves to /opt/tomcat
, the KeyStore File setting would be populated with /opt/tomcat/conf/saml/samlKeystore.jks
.
The JKS keystore password, the default private key alias, and the default private key password can also be specified from the Single Sign-On Settings in the user interface. Each of these settings are populated with a default value of ucsaml
on initial start-up.
If your Identity Provider requires that you upload the public key certificate for the SAML Single Logout profile, you can export the certificate from the JKS keystore as follows.
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.
Use of SAML Single Sign-On requires installation of the Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for JDK/JRE 8 to remove limitations on cryptography capabilities.
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.
Single Sign-On Settings
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 Single Sign-On Settings configuration, associated by Node Id. Therefore, you must complete the 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 > Single Sign-On Settings. The Single Sign-On Settings page displays. |
---|---|
Step 2 | Enter / select your Single Sign-On Settings, using the field descriptions below as a guide.
|
Step 3 | Click the button. |
For information on how to access additional details - such as Metadata and complete database Details - for Single Sign-On Settings (or any type of record), see Records.
Single Sign-On Settings Field Descriptions
The following table describes the fields and buttons that display in the Single Sign-On Settings.
Field Name | Description |
---|---|
Details | This section contains detailed information on the Single Sign-On settings. |
SAML Single Sign-On | If enabled, turns on SAML Single Sign-On. |
User Provisioning | 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:
The |
Identity Provider Metadata File | If Identity Provider Metadata Source = File; Identity Provider metadata file location. |
Identity Provider Metadata URL | If Identity Provider Metadata Source = URL; Identity Provider metadata URL location. |
Service Provider Metadata | 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 SAML KeyStore. |
Attribute Mappings | If 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 User Provisioning is enabled. See 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 Single Sign-On Settings that let you perform various actions. |
Update |
Saves updates to the record. |
Refresh | Refreshes any dynamic data displayed in the Single Sign-On Settings. |
Default Configuration
Upon initial start-up of Universal Controller, a default 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 Single Sign-On Settings Field Descriptions, above, for the default configuration.
Security
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 Single Sign-On Settings.
Bulk Import/Export
Any 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.
Single Sign-On Settings being updated through the Bulk Import server operation are applied immediately; however, you can update the Single Sign-On Settings only for the node you are performing the Bulk Import on.
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: |