Setting up Okta as your OpenID Connect Identity Provider
Published 21 August 2024
This documentation is intended to provide detailed information on how to set up Okta as your identity provider to enable authentication in Redgate Monitor via OpenID Connect. See our page on Authenticating with OpenID Connect for a general overview on this feature.
Pre-requisites
This guide assumes the following:
- You have already created your Okta organization
- Your Redgate Monitor Web Server has been set up to use HTTPS by default. See this page for information on how to set this up.
Creating your App integration
First you will need to create and configure your Okta App integration for Redgate Monitor:
- In the Applications page of your Okta admin page, select Create App Integration
- When prompted, select OIDC as the as the sign-in method, and Web Application as the application type
- Set up your application integration name, and check Implicit (hybrid) as the grant type
- For the Sign-in redirect URI you should use the HTTPS endpoint that you would typically use to access Redgate Monitor through the browser with
/openidconnectaccount
as the path. For example:https://<machine-name>.domain:8080/openidconnectaccount
- For the Sign-out redirect URI, it should be the same as the sign-in redirect URI except with
signout-callback-oidc
instead ofopenidconnectaccount
. For example,https://<machine-name>.domain:8080/signout-callback-oidc
- For the Assignments section, if you already have groups set up to use with Redgate Monitor OIDC then you can add them at this point by selecting "Limit access to selected groups". Otherwise, choose Skip group assignment as it will be covered later, and save your integration.
OIDC token configuration
Before you can use your application integration in Monitor, you will need to make sure the token is correctly configured as follows
- In the General > General Settings section of your Monitor app integration, deselect the "Allow access token" option under "Grant Type" so that only ID Tokens are included. Without this, group claims will not be included in your token when using the default organization server.
- In the Sign On > OpenID Connect ID Token section of your app integration, you must set up a filter for groups that you wish to use with Monitor otherwise no groups will appear in the token. For example, groups that contain "RGMonitor". If you have not yet set up any groups then you should make sure that they pass your filter when you do.
Setting up and assigning groups
If you wish to use groups to streamline adding new users to Monitor you must set the group up within Okta and add users from your organization into the group
- In the Directory > Groups page of the Okta admin panel, you should click Add group and give it a name that would match the filter set up in your OIDC token configuration above, for example "RGMonitor Admins".
` - After opening your new group, In the People tab you can assign the members of your organization that you wish to be part of the group by clicking Assign people and searching for their username before clicking the + button on the right to add them to the group.
- In the Applications tab of the group, you can then attach this group to your Redgate Monitor app integration by choosing Assign applications, and pressing Assign on your Monitor application.
- Optionally, if you have active directories available you can assign these to your group as well through the Directories tab.
Adding the groups scope to Redgate Monitor
You do not need to manually add a scope if you are using a custom authorization server as group claims can be assigned to the default scopes
If you intend to use Okta's default organization server as your OIDC endpoint, it is necessary to include a groups scope when requesting a token otherwise no groups will be included in the token.
To set up Monitor to do this requires making some manual changes to the repository's OIDC configuration as follows
- Connect to your Redgate Monitor repository.
Run the following script. This will add the additional groups scope on to the default
openid
andprofile
scopes that Monitor uses.INSERT
INTO
[settings].[KeyValuePairs]
VALUES
(
'OIDC-Scope'
,
'groups'
,
'STRING'
)
- Restart Redgate Monitor’s website.
If you decide to switch OIDC providers, you may have to remove this if the provider does not accept additional scopes like groups.
You can do this by following the steps above with this script instead:
DELETE FROM [settings].[KeyValuePairs] WHERE KeyName LIKE N'OIDC-Scope'
Configuring your OIDC provider in Redgate Monitor
At this point your Okta app integration should be fully set up to work with Monitor, so all that remains is to create the configuration.
- In the Configuration page, under Users, click Authentication settings:
- Select Use OpenID Connect:
- A popup appears:
- Under Authority, if you are using the default Okta organization server then you can find the domain by visiting your Okta admin console clicking your username in the upper-right corner. The domain appears in the dropdown menu beneath your username. The authority should be https://<okta-domain>.
- Enter the Client ID. You can find this in your Okta app integration page for Monitor under Applications > Applications
- Enter the Username claim name or Group claim name. For Okta, by default these should be
preferred_username
for the Username claim name andgroups
for the Group claim name.
Enable Send ID token on logout. Okta requires this option to be enabled as their specification requires the id token to be sent back when a logout is requested.
Add an Administrator user or group. If you have set up the
RGMonitor Admins
group as shown earlier in this guide, you should select the Group option and enterRGMonitor Admins
into the text field.- Click Save settings. Redgate Monitor logs you and all other users out.
- Access the login page for Redgate Monitor which should redirect you to your Identity Provider's login page.
In case of any problems or misconfiguration, follow Switching back to Redgate Monitor basic authentication.
Adding additional roles
After adding your OIDC configuration to Monitor, you will have an administrator group or user defined. If you want to add more roles (e.g. standard users) via groups, or individual users, then this must be configured separately.
- If you intend to create a new group, for example "RG Monitor Read Only Users", first you should repeat the steps outlined in Setting up and assigning groups.
- Take a note of the group name, and follow our documentation on adding new OIDC users and groups to see how you can add it to Monitor
Using a custom authorization server
Okta gives the option of using the default organization server, or creating a custom authorization server. If you intend to use a custom authorization server there are a couple of differences to consider:
- In the Claims tab of your authorization server (found in the Security > API section of the Okta admin page), you will need to add a new claim for groups as your token will not use the one set up inside your app registration.
- For Name and Value Type it should be
groups
- The Filter should match any groups you assigned to Redgate Monitor, e.g.
contains RGMonitor
- It should Always be included in token type ID Token
- Optionally you can add it to the
profile
scope or select Any scope.
- For Name and Value Type it should be
- The Authority that you configure in Redgate Monitor should be the Issuer URI listed for your authorization server in the Security > API section of the Okta admin page