OAuth Single Sign-On
- Stonebranch (Deactivated)
- Alec Berger
- Jeremey Laprise
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
- 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 - - |
Web Service Access | - - System Default - - |
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.
|
Step 3 | Click the |
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. |
| 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.
|
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
If not specified, defaults to values from the request using the It is recommended that you specify the The fully qualified sign-in redirection endpoint for each Cluster Node will be:
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.
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. |
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
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: |
|---|---|
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 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: |
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 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: |
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: |