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:

1. In the Applications page of your Okta admin page, select Create App Integration
   
2. When prompted, select OIDC as the as the sign-in method, and Web Application as the application type
   
   
   
   
3. Set up your application integration name, and check Implicit (hybrid) as the grant type
   
   
   
   
4. 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 
5. For the Sign-out redirect URI, it should be the same as the sign-in redirect URI except with signout-callback-oidc instead of openidconnectaccount. For example, https://<machine-name>.domain:8080/signout-callback-oidc



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

1. 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.
   
   
2. 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

1. 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".
   
   `
   
   
2. 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.
3. 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.
   
   
   
   
4. 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

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

1. Connect to your Redgate Monitor repository.

2. Run the following script. This will add the additional groups scope on to the default openid  and profile scopes that Monitor uses.

   INSERT INTO [settings].[KeyValuePairs] VALUES ('OIDC-Scope', 'groups', 'STRING')

3. Restart Redgate Monitor’s website.

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.

1. In the Configuration page, under Users, click Authentication settings:
   
   
   
   
2. Select Use OpenID Connect:
   
3. A popup appears:
   
4. 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>.
   
5. Enter the Client ID. You can find this in your Okta app integration page for Monitor under Applications > Applications
   
   
6. Enter the Username claim name or Group claim name. For Okta, by default these should be preferred_username for the Username claim name and groups for the Group claim name.

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

8. 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 enter RGMonitor Admins into the text field.

9. Click Save settings. Redgate Monitor logs you and all other users out.
10. Access the login page for Redgate Monitor which should redirect you to your Identity Provider's login page.

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.

1. 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.
2. 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:

1. 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.
   
   1. For Name and Value Type it should be groups 
   2. The Filter should match any groups you assigned to Redgate Monitor, e.g. contains RGMonitor 
   3. It should Always be included in token type ID Token
   4. Optionally you can add it to the profile  scope or select Any scope.
      
2. 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