Manage users with OIDC

Overview

Pivot can be configured for single sign-on using an external OIDC identity provider, such as Okta or Auth0. When using OIDC, Pivot will rely on the external system to authenticate users and optionally to map identity provider groups to Pivot roles. When Pivot is configured to use an OIDC connection, it creates an account for the user the first time the user logs in.

Configuring the OIDC application

When configuring the OIDC application in your identity provider, you will need to provide the callback URLs for the authentication flow. All can be set to <PIVOT_URL>/authorization-code/callback, where <PIVOT_URL> is the publicly routable URL of your Pivot deployment. Once you have created your OIDC app, you will need to configure Pivot using the Client ID and Client Secret.

Configuring Pivot

To configure Pivot for OIDC, we'll need to set the user mode and provide some information about the identity provider in the Pivot config file. First, we will set the user management mode to use OIDC:

userMode: oidc-authentication

Next, we will provide some information about the OIDC app you configured above. These are all set under the oidcOptions block.

Here, you'll provide the issuer (the root URL for your identity provider, e.g., https://my-company.okta.com), as well as the client credentials, client_id and client_secret, available in the application you configured in the identity provider.

Additionally, you will need to define the OIDC scopes you wish to use for authentication. The minimum scopes required are openid, profile, and email.

Lastly, we'll configure the OIDC connector to identify Pivot using the app_base_url, which should point to the same <PIVOT_URL> you defined above in the identity provider application setup. A sample configuration should now look something like this:

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

Mapping User IDs

By default, Pivot will use the subject (sub) value returned by the UserInfo response as the user ID in Pivot. If you would like to use an alternate value instead—say, for example, if sub values do not map to easily identifiable user names in your system—you can specify any other value returned by the UserInfo response instead, using the userIdProperty config property.

By default, existing users will be mapped to OIDC responses using case-sensitive matching, but this can be overridden by setting the useCaseInsensitiveMatching flag to true:

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

Onboarding OIDC users

If OIDC is enabled for Pivot, by default, new users will not be granted any authorization roles, requiring a Pivot administrator to manually assign roles after users log in for the first time. If you'd like to provide a better experience when users log in for the first time, you should set the top-level defaultRole Pivot config property to a basic Pivot user role.

Additionally, when first setting up OIDC, you can simplify seeding a super administrator user by setting the superAdminUser to your own account, allowing you to log in as an admin and set up roles for your users. Your config would now look something like this:

userMode: oidc-authentication
userIdProperty: email
useCaseInsensitiveMatching: true
defaultRole: user
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"

Using OIDC as a role authority

Similarly to using LDAP for user management, it is possible to configure Pivot to allow your identity provider to manage user authorization roles in Pivot. You will first need to configure the OIDC application on your identity provider to expose a groups claim. This varies by provider, for example you can find a guide for doing this with Okta OIDC applications here.

Once that is set up, we'll need to add the groups claim to our oidcOptions scope:

userMode: oidc-authentication
userIdProperty: email
useCaseInsensitiveMatching: true
defaultRole: user
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"

By default, groups will be mapped to Pivot roles when the user first logs in. If you'd like to synchronize role mapping on every login, set the roleAuthority config property to external.

Additionally, when using external role mapping, Pivot will assume 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. This would 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 from that set.

If you prefer a more permissive configuration, you can set the applyDefaultRoleWhenNoGroupsMatch property to true, ensuring that any authenticated OIDC user will be granted the defaultRole. Your configuration would then look something like this:

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. It is automatically concatenated with /.well-known/openid-configuration when initiating the authentication flow. If the provider configuration document in your environment is not available at that URL, you may provide a discoveryUrl parameter instead of issuer with the value set to the fully qualified URL of the discovery document.

When OIDC is configured, navigating to Pivot will automatically initiate the login flow against the identity provider, and pre-authenticated users will be taken directly to the Pivot home screen. If showing a login screen is preferable, automatic logins can be disabled by appending "?showLoginPage=true" to any Pivot URL.