Admin: Appendix B - OpenID Connect configuration

Overview

RPI supports the use of the AzureAD, Okta, and KeyCloak OpenID connection (OIDC) providers to authenticate users accessing RPI. To integrate an OIDC provider with your environment, update the settings in the OpenIdProviders section of the values.yaml file (refer to our GitHub repo for more information). Adjust these values to match your environment's configuration:

OpenIdProviders:
  enabled: true
  name: AzureAD

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).

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

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.

AzureAD

To configure AzureAD for use as an RPI OIDC provider, you will need a valid Azure Tenant ID and App Registration Client ID. Please follow these steps to obtain these.

1. Log into the Microsoft Entra Admin center and then select the Microsoft Entra ID (Azure AD) tile.

2. From the +Add drop down, choose App registration.

3. Name your registration.

4. Choose the account type.

5. Set the Redirect URI to be Public client/native (Mobile & Desktop).

6. Set the value of the Redirect URI.

7. You’ll be redirected the App Registrations overview page. Select the Add an Application ID URI link.

8. Select the Add link next to Application ID URI.

9. Add a custom scope named Interaction.Clients.

10. Having obtained an Azure Tenant ID and App Registration Client ID, configure application settings in RPI as follows:

    • Azure Tenant ID: authorizationHost

    • App Registration Client ID: clientID, audience, and customScopes

11. Add the following permissions under API Permissions:

    • email

    • openid

    • User.Read

12. Under Expose an API, set Who can consent? to Admins and users.