Manage users with OIDC

You can configure Imply Pivot for single sign-on with an external OpenID Connect (OIDC) identity provider, such as Okta or Auth0. When you use OIDC, Pivot relies on the external system to authenticate users and optionally map identity provider groups to Pivot roles. When you use an OIDC connection, Pivot creates an account for the user the first time the user logs in.

For information on the preferred approach to configure OIDC for Imply Enterprise Hybrid (formerly Imply Cloud), see Direct access Pivot.

The sample code in this topic uses example for the company name and example.com for the domain name.

Configure the OIDC application

To configure the OIDC application in your identity provider, specify the callback URLs for the authentication flow. Set all callback URLs to <PIVOT_URL>/authorization-code/callback, where <PIVOT_URL> is the publicly routable URL of your Pivot deployment. After you have created your OIDC app, configure Pivot with the Client ID and Client Secret.

Configuring Pivot

To configure Pivot for OIDC, add the user mode and identity provider information to the Pivot config file.

Set the user management mode to use OIDC:

userMode: oidc-authentication

Provide some information about your OIDC app configuration within the oidcOptions block:
- issuer: the root URL for your identity provider, such as https://example.okta.com
- client_id: the client ID from your OIDC app configuration
- client_secret: the client secret from your OIDC app configuration
Define the OIDC scopes you wish to use for authentication. The minimum required scopes are openid, profile, and email.
Configure the OIDC connector to identify Pivot using the app_base_url that refers to the <PIVOT_URL> you defined in the identity provider app setup.

The following example illustrates a basic Pivot OIDC configuration:

userMode: oidc-authentication
oidcOptions:
  issuer: https://example.okta.com
  app_base_url: https://my-pivot.com
  client_id: XXXXXXX
  client_secret: XXXXXXX
  scope: "openid profile email"

Map user IDs

By default, Pivot uses the value of the sub (subject) key in the UserInfo response object for the Pivot user ID. To use an alternate value instead of sub, specify a different key from the UserInfo response object for the userIdProperty config property. For example, you can use email instead of sub for the Pivot user ID:

userMode: oidc-authentication
userIdProperty: email
useCaseInsensitiveMatching: true
 oidcOptions:
  issuer: https://example.okta.com
  app_base_url: https://my-pivot.com
  client_id: XXXXXXX
  client_secret: XXXXXXX
  scope: "openid profile email"

By default, Pivot maps existing users to OIDC responses using case-sensitive matching. Set the useCaseInsensitiveMatching flag to true to disable case-sensitivity.

Onboard OIDC users

Pivot attempts to assign mapped groups to users as roles upon first login.

After that, you can use Pivot's built-in role management to manage users and roles through the Pivot UI. If Pivot doesn't find role mappings for a user at first login, a Pivot administrator can manually assign roles after first login time. To provide a better experience at initial login, you can set the top-level defaultRole Pivot config property to a basic Pivot user role.

When you first enable OIDC, you can set superAdminUser to your own account to simplify seeding a super administrator user. This way you can log in as an admin user and set up roles for your users. For example:

userMode: oidc-authentication
userIdProperty: email
useCaseInsensitiveMatching: true
defaultRole: user
superAdminUser: myname@example.com
oidcOptions:
  issuer: https://example.okta.com
  app_base_url: https://my-pivot.com
  client_id: XXXXXXX
  client_secret: XXXXXXX
  scope: "openid profile email"

Configure OIDC as a role authority

You can configure Pivot to allow your identity provider to manage user authorization roles in Pivot.

Configure the OIDC app on your identity provider to expose a groups claim. Groups claims vary by provider, so refer to your provider documentation for details. For example, see the following guide for Okta OIDC applications.
Add the groups claim to the Pivot oidcOptions scope. For example:

...
oidcOptions:
  issuer: https://my-company.okta.com
  app_base_url: https://my-pivot.com
  client_id: XXXXXXX
  client_secret: XXXXXXX
  scope: "openid profile email groups"

By default, Pivot uses the value of the groups key from the UserInfo response object for a list of groups to use for mapping. To use an alternate property for a list of groups, specify a different key from the UserInfo response object for the groupsProperty config property. For example, the following configuration looks for the user-roles key from the UserInfo object:

userMode: oidc-authentication
userIdProperty: email
groupsProperty: user-roles
useCaseInsensitiveMatching: true
defaultRole: user
superAdminUser: myname@example.com
oidcOptions:
...

By default, Pivot maps a user's groups to Pivot roles upon first login. To synchronize role mapping upon every login, set the roleAuthority config property to external.

When you use an external role mapping:

Pivot assigns the default role if the user's set of groups is nonexistent.
Pivot assumes that an empty set of groups returned by OIDC indicates that the user should not be assigned any permissions in Pivot, including the default role.

The latter can happen if you configure your OIDC app to return a limited set of groups, but the user attempting to log in has not been assigned any groups from that set.

For a more permissive configuration, set the applyDefaultRoleWhenNoGroupsMatch property to true to ensure that any authenticated OIDC user is granted the defaultRole. For example:

userMode: oidc-authentication
userIdProperty: email
useCaseInsensitiveMatching: true
applyDefaultRoleWhenNoGroupsMatch: true
defaultRole: user
roleAuthority: external
superAdminUser: myname@mycompany.com
oidcOptions:
  issuer: https://my-company.okta.com
  app_base_url: https://my-pivot.com
  client_id: XXXXXXX
  client_secret: XXXXXXX
  scope: "openid profile email groups"

Advanced configuration and troubleshooting

The issuer value should be the base URL of the OpenID Provider Configuration Document for your identity provider. Pivot automatically appends /.well-known/openid-configuration when initiating the authentication flow. If the provider configuration document in your environment is not available at that URL, provide a discoveryUrl parameter instead of issuer with the value set to the fully qualified URL of the discovery document.

When you configure Pivot to use OIDC, navigation through Pivot automatically initiates the login flow against the identity provider. Pre-authenticated users arrive directly at the Pivot home screen. If you prefer to display the login screen, append ?showLoginPage=true to any Pivot URL to disable automatic login.

Learn more

See the following related topics:

User management in Pivot for an overview of user management in Pivot, including roles and permissions.
Direct access Pivot for the preferred approach to integrate Imply Enterprise Hybrid with OIDC.