Overview

Universal Controller enables Web Browser Single Sign-On (SSO) through OAuth 2.0 (with OpenID Connect).

OAuth 2.0 authorization framework is a protocol that allows a user to grant a third-party web site or application access to the user's protected resources, without necessarily revealing their long-term credentials or even their identity.

OpenID Connect (OIDC) is an identity layer built on top of OAuth 2.0. It extends OAuth 2.0 to include user authentication, enabling clients to verify the identity of the user and obtain basic profile information.

Universal Controller uses OAuth Single Sign-On for authentication and User Provisioning. All user and group authorization must be configured within Universal Controller through Permission and Role assignment.

Single Sign-On Login

OAuth Single Sign-On can be initiated by either Universal Controller or the Identity Provider.

Only users designated with Single Sign-On as a Login Method can authenticate using OAuth 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).

Universal Controller Initiated Login

Universal Controller will initiate the OAuth Single Sign-On login flow when an unauthenticated user accesses the web application through the following URL.

http(s)://<server:port>/uc/oauth2

Identity Provider-Initiated Login

Identity Provider-initiated OAuth 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 OAuth-authenticated user to access the Universal Controller web application are restored when the Service Provider-initiated OAuth SSO authentication flow has completed successfully and the user has been redirected back to the Universal Controller web application.

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 OAuth-enabled user, the Controller allows you to initiate the OAuth 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 OAuth 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 OAuth 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 OAuth SSO authentication flow has completed, click Continue on the original dialog to proceed, which closes the OAuth 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, OAuth Single Sign-On are incorrectly configured or the Identity Provider is inaccessible.

Logout

By initiating the Logout menu option, an OAuth-authenticated user is only logged out of the Universal Controller.

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 Access / ID Token:

When LDAP synchronization is enabled, provisioning of users through LDAP synchronization takes precedence over provisioning of users through the Access / ID Token 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 Access / ID Token attributes with Universal Controller user fields, Universal Controller must provide a way to configure a mapping between Universal Controller User fields and Access / ID Token attributes.

The following Universal Controller user fields are mappable.

User Id (Username)
(By default, this field is automatically mapped to the OAuth Subject identifier (sub) from the Access / ID Token, however, you can override this by specifying a User Id (Username) Claim Name.)
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 Access / ID Token attributes, during the single sign-on process, is considered an Identity Provider-sourced user.

User Field Defaults

OAuth 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 Access / ID Token. Universal Controller allows configuring which Access / ID Token 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 OAuth Single Sign-On, its group membership will be updated based on the group attribute value in the accepted Access / ID Token. The user will be added to, or removed from, groups accordingly.

OAuth Single Sign-On

An administrator can turn on/off and configure OAuth Single Sign-On through the user interface.

Step 1

From the Administration navigation pane, select OAuth Single Sign-On. The OAuth Single Sign-On page displays.

Step 2

Enter / select your OAuth Single Sign-On, 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 OAuth Single Sign-On (or any type of record), see Records.

OAuth Single Sign-On Field Descriptions

Field Name	Description
Details	This section contains detailed information on the OAuth Single Sign-On.
OAuth Single Sign-On	If enabled, turns on OAuth Single Sign-On. If disabled, all fields are read-only.
User Provisioning	Turn on or off the provisioning of users through Access or ID Token attributes. Select the application access method(s) you want User Provisioning to be applied.
Issuer URI	Universal Controller uses the Issuer URI for discovery of the OpenID Connect / OAuth 2.0 protocol endpoints for authenticating users. One of the following must be a supported endpoint for the authorization server, referred to as a Provider Configuration endpoint or a Authorization Server Metadata endpoint. `{Issuer URI}/.well-known/openid-configuration` `{Issuer URI Host}/.well-known/openid-configuration/{Issuer URI Path}` `{Issuer URI Host}/.well-known/oauth-authorization-server/{Issuer URI Path}`
Scopes	List of OAuth scopes. Default is "openid".
Client Id	Client identifier for the Universal Controller Web Application required for OAuth flows.
Client Secret	Client secret used for client authentication with the authorization server.
Proof Key for Code Exchange (PKCE)	Authorization Code grant type requires PKCE as additional verification.
User Id (Username) Claim Name	Specifies the name of a specific claim / attribute to identify the Universal Controller User Id (Username). If left unspecified will default to the Subject identifier (sub).
Cluster Node Base Redirect URLs	Cluster Node Base Redirect URLs are used to construct the sign-in redirection endpoint for each Cluster Node and are specified as a URL with protocol, server, port, and context path `scheme://server:port/contextPath` If not specified, defaults to values from the request using the `Host` header value, if any, or the resolved server name (or server IP address) and server port the client connection was accepted on. It is recommended that you specify the `Base Redirect URL` for each Cluster Node rather than rely on the `Host` header value for redirection endpoint resolution. The fully qualified sign-in redirection endpoint for each Cluster Node will be: `{Cluster Node Base Redirect URL}/login/oauth2/code/default` Each Cluster Node's fully qualified sign-in redirection endpoint must be added to your registered application in the authorization server.
OAuth Bearer Token Validation	Choose the type of OAuth2 Bearer Token authentication supported for Universal Controller Web Service API endpoints. None Opaque Token JWT If None, then only Basic and Personal Access Token authentication are supported.
Introspection URI	If OAuth Bearer Token Validation = Opaque Token; The introspection endpoint URI.
JWK Set URI	If OAuth Bearer Token Validation = JWT; Specifies a JSON Web Key (JWK) endpoint that contains public keys used for Access and ID Token verification. If left unspecified, Universal Controller will use the Issuer URI to query the Provider Configuration or Authorization Server Metadata endpoint for the JWK Set URI.
Audience Claim Value	If OAuth Bearer Token Validation = JWT; Recommended specification of the expected audience claim value so the Universal Controller can validate the Token audience (aud) matches.
Attribute Mappings	If User Provisioning = Web Browser Access and/or Web Service Access; This section allows you to configure a mapping between user fields and attributes.
First Name	Name of an attribute from the Access or ID Token containing the user's First Name.
Middle Name	Name of an attribute from the Access or ID Token containing the user's Middle Name.
Last Name	Name of an attribute from the Access or ID Token containing the user's Last Name.
Business Phone	Name of an attribute from the Access or ID Token containing the user's Business Phone.
Home Phone	Name of an attribute from the Access or ID Token containing the user's Home Phone.
Mobile Phone	Name of an attribute from the Access or ID Token containing the user's Mobile Phone.
Email	Name of an attribute from the Access or ID Token containing the user's Email.
Title	Name of an attribute from the Access or ID Token containing the user's Title.
Manager	Name of an attribute from the Access or ID Token containing the user's Manager Name.
Department	Name of an attribute from the Access or ID Token containing the user's Department.
Active	Name of an attribute from the Access or ID Token containing the user's Active condition.
Groups	Name of a multi-valued attribute from the Access or ID Token containing the Group Names the user is a member of.
Universal Portal	This section allows you to set up OAuth Single Sign-On for Universal Portal.
Portal Client Id	Client identifier for the Universal Portal Single Page Application required for OAuth flows.
Portal API Scopes	Optionally, specifies the scopes required when requesting an Access Token for the Universal Controller Web Application APIs. For example, if the Universal Portal SPA needs to specify a custom scope `api://{client-id}/resources` in addition to `openid` and `profile` when requesting an Access Token for the Universal Controller Web Application APIs, you would specify the following. api://{client-id}/resources openid profile If left unspecified, the Universal Portal SPA will use the Scopes.

Security

OAuth Single Sign-On can be viewed only by users with the ops_admin or ops_sso_admin role, regardless of Navigation Visibility; therefore, only users with the ops_admin or ops_sso_admin role can update OAuth Single Sign-On.

Troubleshooting

The OAuth Single Sign-On User Id (Username) Claim Name specifies the name of a specific claim / attribute to identify the Universal Controller User Id (Username). If left unspecified, will default to the Subject identifier (sub).

The claim value received from the Identity Provider for the specified User Id (Username) Claim Name correlates directly to the Universal Controller User Id (Username) field of a user record in the Universal Controller database.

If User Provisioning is off, the claim value must match with the User Id (Username) 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 (Username) equivalent to the claim value.

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 OAuth at this time receive the following error: Universal Controller is being initialized. Please try again later.
User Account Not Found	Any OAuth-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 'issuer' not synchronized with a Universal Controller account.
User Account Not Active	Any OAuth-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 'issuer' is synchronized with an inactive Universal Controller account.
Login Method	Any OAuth-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 'issuer' is not permitted to use Single Sign-On login method.
User Account Locked	Any OAuth-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 OAuth-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.

Browser not supported