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
Email
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 - - Applies only to users designated to use the Standard login method.
Web Service Access	- - System Default - - Applies only to users designated to use the Standard login method.

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, HTTP-Artifact	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 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. Required fields display an asterisk ( * ) after the field name. Default values for fields, if available, display automatically.
Step 3	Click the button.

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.

Required fields display an asterisk ( * ) after the field name.
Default values for fields, if available, display automatically.

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. If disabled, all fields are read-only.
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: `scheme://server:port/contextPath`
Identity Provider Metadata File	Identity Provider metadata file 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. In addition to user fields, you can specify an attribute mapping for Groups allowing for automatic provisioning of a user's group membership. See Group Membership Attribute Mapping for more details.
First Name	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the First Name of the user.
Middle Name	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Middle Name of the user.
Last Name	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Last Name of the user.
Email	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Email of the user.
Active	Name of an attribute, of type `xs:boolean`, `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Active condition of the user. Non-boolean type values that evaluate to true are "true", "1", "yes", and "on." All other non-boolean type values evaluate to false.
Groups	Name of a multi-valued attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Group Name of each group that the user is a member of.
Title	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Title of the user.
Department	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Department of the user.
Manager	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Name of the Manager of the user.
Business Phone	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Business Phone of the user.
Mobile Phone	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Mobile Phone of the user.
Home Phone	Name of an attribute, of type `xs:string` or `xs:any`, from the attribute statement of the SAML assertion containing the Home Phone of the user.
Buttons	This section identifies the buttons displayed above and below the Single Sign-On Settings that let you perform various actions.
Update	Unable to render {include} The included page could not be found.
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: Universal Controller is being initialized. Please try again later.
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 'username' not synchronized with Universal Controller. Please check with your administrator. Additionally, the uc.log will contain the following warning: User 'username' authenticated by identity provider 'remote-entity-id' not synchronized with a Universal Controller account.
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: User 'username' not synchronized with Universal Controller. Please check with your administrator. Additionally, the uc.log will contain the following warning: User 'username' authenticated by identity provider 'remote-entity-id' is synchronized with an inactive Universal Controller account.
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 'username' not synchronized with Universal Controller. Please check with your administrator. Additionally, the uc.log will contain the following warning: User 'username' authenticated by identity provider 'remote-entity-id' is not permitted to use Single Sign-On login method.
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: User account 'username' is locked. Please check with your administrator.
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: User 'username' not permitted to login through the web browser. Please check with your administrator.
Authentication Statement Too Old	If users already are authenticated with their Identity Provider, depending on how long their Identify Provider allows them to stay authenticated, they could experience an "Error validating SAML message" authentication error when signing into the Universal Controller through single sign-on. If users are experiencing this error, search the uc.log for the following message: Authentication statement is too old to be used with value 2019-08-15T19:22:56.312Z Upon confirming the presence of the above message, review property saml.maxAuthenticationAge and adjust accordingly. This property allows you to set the maximum time between a user's authentication and processing of an authentication statement, which by default is 7200 seconds.

Browser not supported