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.