Admin: OpenID connection (OIDC) configuration

Overview

RPI supports the use of the Keycloak and Okta OpenID connection (OIDC) providers to authenticate users accessing RPI.

OIDC providers Keycloak and Okta have been validated for use with RPI. Separate sections describe how to configure the aforementioned RPI applications for each.

Adjust these values to match your environment's configuration:

YAML

OpenIdProviders:
  enabled: true
  name: KeyCloak

The following values.yaml settings are provided to configure OpenID Connect:

Setting	Description
`enabled`	Set to `true` to enable OpenID Connect settings.
`name`	Name of the OpenID Connect provider. Supported providers are: `KeyCloak`, `Okta`, and `AzureAD`.
`authorizationHost`	Authorization host for OpenID Connect. The user will be taken to this page when logging into RPI using the OpenID authentication.
`clientID`	The Client ID configured within the OpenID provider.
`audience`	Audience for the OpenID Connect authentication request.
`redirectURL`	The redirect URL used for retrieving the token, as configured within the OpenID provider.
`enableRefreshTokens`	`true` = enable the option to enable refresh tokens (default/recommended) `false` = disable refresh tokens If refresh tokens are disabled, the client will be logged off once the token expires, per the period configured within the OpenID provider.
`validateIssuer`	When set to `true`, validates issuer of the OpenID Connect provider (i.e., the `authorizationHost` must match the issuer name supplied in the access token).
`validateAudience`	When set to `true`, validates audience of the OpenID Connect provider (i.e., the `audience` must match the audience name supplied in the access token).
`customScopes`	Custom scopes for OpenID Connect. This is the list of custom scopes required to request the OpenID access token.
`logoutIdTokenParameter`	Query parameter name used to pass the id token on logout. The default value is `id_token_hint`.
`supportsUserManagement`	`true` = RPI supports management of users directly within OIDC provider (as well as native user management).

Prerequisites

Before generating your overrides, set up your OIDC provider and gather the following values:

Value	Where to find it
Authorization Host	Keycloak: `https://<host>/realms/<realm>` Okta: `https://<domain>/oauth2/default`
Client ID	The application/client ID from your identity provider's app registration
Audience	Keycloak: usually the same as Client ID Okta: `api://<client-id>`
Redirect URL	Your RPI Interaction API URL, e.g. `https://rpi-interactionapi.example.com`
Custom Scopes	Keycloak: `openid`, `profile` Okta: `api://<client-id>/Interaction.Clients`

Complete your identity provider setup before generating your overrides so you have the required values ready.

Keycloak

The steps below assume the Realm has been created and configured within Keycloak.

Refer to the Keycloak documentation for steps on how to create the required components.

audience
1. Log into the Keycloak portal, under the Realm configured for RPI.
2. Expand the “Clients” section.
3. For a typical install, the “account” Client ID is the default name for the audience. Set this value at the audience configuration setting.

authorizationHost
1. As Keycloak is self-installed, the Authorization Host will be formatted as follows: https://<fqdm>:<port>/auth/realms/<realm_name>.
2. Set this value at the authorizationHost configuration setting.
clientID
1. Open the list of Keycloak Clients and select the client ID configured for RPI.
2. Copy the value in the “Client ID” text box and set the clientID setting to the same.

customScopes
- Custom scopes are not required for this provider; however, the email claim must be configured within the client scope. This feature is enabled by default, but can be confirmed by navigating to Client Scopes > Email > Mappers > Email. Ensure the Add to access token option is turned on.

redirectURL
1. Open the client settings for the Keycloak client configured for RPI.
2. Under the Settings tab, scroll down to the Valid Redirect URIs configuration setting and select the +@ icon to add a new redirect URI. This must be a valid and accessible URL with the https:// protocol.
3. Use the same URL at the redirectURL setting.
4. Select the Save button once the URI is updated.

Okta

The steps below assume the application has been created within Okta.

Refer to the Okta documentation for steps on how to create the required components.

audience
1. Log into the Okta portal and expand the “Security” section.
2. Select the “APIs” link.
3. Under the “Authorization Servers” tab, copy the value in the Audience column and paste the value into the audience configuration setting.

authorizationHost
1. Open the API configuration screen.
2. Copy the value in the “Issuer URI” column of the “Authorization Servers” tab and paste the value into the authorizationHost setting.

clientID
1. Expand the “Applications” section and select the “Applications” link to view the list of configured applications.
2. Proceed by selecting the application created for use in RPI.
3. Under “Client Credentials”, select the copy Client ID button and paste the value into the clientID setting.

customScopes
1. Custom scopes are not required for this provider; however, the email claim must be configured within the Audience, as covered above. To add the email claim, expand the “Security” section and select the “APIs” link. Select the “Name” link of the Audience to open the configuration. Once in the configuration, select the “Claims” tab and select the Add Claim button.
2. Enter “email” for Name and “appuser.email” for Value.
3. Select the Save button.

redirectURL
1. Open the settings for the RPI Okta application.
2. Under General Settings, select the Edit link.
3. Scroll down to the LOGIN section of the settings and enter a URL in the “Sign-in redirect URIs” text box. This must be a valid and accessible URL with the https:// protocol.
4. Copy the same URL for the “Sign-out redirect URIs” text box as well.
5. Click the Save button once complete.
6. Paste the value into the redirectURL setting.

Generate Your Overrides

Once you have the values above, go to the Helm Assistant Generate tab > Step 8: Services > OpenID Connect and enter them. They will be included in your generated overrides.yaml automatically.

For all available OpenIdProviders configuration keys, see the Helm Assistant Reference tab.