Overview

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

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.
 

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.
 

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:
 

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.
 

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.

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.

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.
 

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