Set Up SSO with Okta

As an alternative to Kong Konnect’s native authentication, you can set up single sign-on (SSO) access to Konnect through Okta with OpenID Connect. This authentication method allows your users to log in to Kong Konnect using their Okta credentials, without needing a separate login.

You can’t mix authenticators in Kong Konnect. With Okta authentication enabled, all non-admin Konnect users have to log in through Okta. Only the Konnect org owner can continue to log in with Konnect’s native authentication.

Prerequisites and overview of steps

To set up Okta single sign-on (SSO) for Konnect, you need access to an Okta admin account and a Konnect admin account, which you will access concurrently.

Optionally, if you want to use team mappings, you must configure Okta to include group claims in the ID token.

Here are the steps you need to complete, in both Okta and Konnect. First, complete the following in Okta:

Set up an Okta application
(Optional) If using group claims for team mapping, set up claims in Okta.

Then, you can set up Konnect to talk to the Okta application:

Set up Okta IDP in Konnect, referring back to Okta for details
Map Konnect teams to Okta groups
Test and publish config

Set up Okta

Prepare the Okta application

Create a new application in Okta to manage Kong Konnect account integration.

Sign in to your Okta admin account.
In the sidebar, click Applications > Applications, then click Create App Integration.
Select the application type:
1. For the Sign-in method, select OIDC - OpenID Connect.
2. For the Application Type, select Web Application.
3. Click Next.
Configure the application:
1. In the App integration name box, enter a unique name for your application.
2. For the Grant type, ensure the Authorization Code checkbox is selected.
3. For both the Sign-in redirect URIs and Sign-out redirect URIs boxes, enter: https://cloud.konghq.com/login
4. In the Assignments pane, for Controlled access, choose your preferred access level for this application. This preferred access level sets the permissions for Okta admins.
Click Save.

Leave this page open. You’ll need the connection details here to configure your Kong Konnect account.

(Optional) Set up claims in Okta

If you are intending to use group claims for Konnect team mappings, follow this guide to set them up. Otherwise, skip to Add a user to your application.

The connection between Konnect and Okta uses OpenID Connect tokens. To have Okta send the correct information to your Konnect org, set up claims to extract that information.

Open your Okta account in a new browser tab.
In the sidebar, select Security > API.
Select the authorization server that you want to configure.
Click the Claims tab to configure the groups claim.
Click ID, then click Add Claim.

Configure a groups claim by filling in the following fields:

Field	Value
Name	`groups`
Include in token type	ID token, Always
Value type	Groups
Filter	Select Matches regex from the drop-down, then enter `.*` in the field.
Include in	Choose The following scopes and select `openid`, `email`, and `profile`.

This claim tells Okta to reference a subset of Okta groups. In this case, the wildcard (.*) value tells Okta to make all groups available for team mapping.

If the authorization server is pulling in additional groups from third-party applications (for example, Google groups), the groups claim cannot find them. An Okta administrator needs to duplicate those groups and re-create them directly in Okta. They can do this by exporting the group in question in CSV format, then importing the CSV file to populate the new group.

Click Create.

If you have problems setting up these claims, refer to the Okta documentation for troubleshooting:

Add a user to your application

In the sidebar of your Okta account, click Applications > Applications.
Select your Konnect application.
Click the Assignments tab.
Click Assign > Assign to People, and then click Assign next to the name of the users you want to add.
Optional: In the dialog, enter additional information about the user.
Click Save and Go Back.
Click Done.

Test claims and find groups for mapping

In the sidebar of your Okta account, click Security > API.
Select the authorization server that you want to configure.
Click the Token Preview tab.
Enter your client in the OAuth/OIDC client box. This is the name you created previously for your Okta application.
In the Grant Type menu, select Authorization Code.
In the User menu, select an Okta user that is assigned to the Konnect application to test the claim with.
In the Scope box, enter openid, email, and profile.
Click Preview Token.
In the generated preview, ensure that the groups value is present.
From the list of groups in the preview, identify groups that you want to use in Konnect. Take note of these groups.

Set up Konnect

Provide Okta connection details

In another separate browser tab, log in to Kong Konnect.
Click Organization, and then Auth Settings.
Click Configure provider for OIDC.
In Okta, locate your issuer URI.
1. Go to Security > API.
2. Copy the issuer URI for your authorization server. It should look something like this:
```
 https://example.okta.com/oauth2/default
```
  Where default is the name or ID of the authorization server.
  
  Note: Do not use the issuer URI from your application’s settings. That URI is incomplete: https://example.okta.com.
Paste the issuer URI from Okta in the Issuer URI box in Konnect.
In Okta, copy your client ID and client secret by going to Applications > Applications and selecting your Konnect application.
Paste the Client ID and Client Secret from your Okta application into Kong Konnect.

See the Okta developer documentation to learn more about client credentials in Okta.
In the Organization Login Path box, enter a unique string. For example: examplepath.

Konnect uses this string to generate a custom login URL for your organization.

Requirements:
- The path must be unique across all Konnect organizations. If your desired path is already taken, you must to choose another one.
- The path can be any alphanumeric string.
- The path does not require a slash (/).
Click Save.

Map Konnect teams to Okta groups

By mapping Okta groups to Konnect teams, you can manage a user’s Konnect team membership directly through Okta group membership.

After mapping is set up:

Okta users belonging to the mapped groups can log in to Konnect.
When a user logs into Konnect with their Okta account for the first time, Konnect automatically provisions an account with the relevant roles.
If your org already has non-admin Konnect users before mapping, on their next login they will be mapped to the teams defined by their Okta group membership.
An organization admin can view all registered users in Konnect, but cannot edit their team membership from the Konnect side. To manage automatically-created users, adjust user permissions through Okta, or adjust the team mapping.

Any changes to the mapped Okta groups on the Okta side are reflected in Kong Konnect. For example:

Removing a user from a group in Okta also deactivates their Konnect account.
Moving a user from one group to another changes their team in Konnect to align with the new group-to-team mapping.

Refer to the token preview in Okta to locate the Okta groups you want to map.

You can also locate a list of all existing groups by going to Directory > Groups in Okta. However, not all of these groups may be accessible by the groups claim. See the claims setup step for details.
In Kong Konnect, go to Organization > Auth Settings > Team Mappings and do at least one of the following:
- To manage user and team memberships in Konnect from the Organization settings, select the Konnect Mapping Enabled checkbox.
- To assign team memberships by the IdP during SSO login via group claims mapped to Konnect teams, select the IdP Mapping Enabled checkbox and enter your Okta groups in the relevant fields.
Each Konnect team can be mapped to one Okta group.

For example, if you have a service_admin group in Okta, you might map it to the Service Admin team in Konnect. You can hover over the info (i) icon beside each field to learn more about the team, or see the teams reference for more information.

You must have at least one group mapped to save configuration changes.
Click Save.

Test and apply the configuration

Important: Keep built-in authentication enabled while you are testing Okta authentication. Only disable built-in authentication after successfully testing Okta authentication.

You can test the Okta configuration by navigating to the login URI based on the Organization Login Path you set earlier. For example: cloud.konghq.com/login/examplepath. You will see the Okta sign in window if your configuration is set up correctly.

You can now manage your organization’s user permissions entirely from the Okta application.

Log in through Okta to test the integration

Copy your Konnect organization’s login URI.

If you ever need to find the path again, you can always find it under Organization > Auth Settings, then copy the Organization Login URI and append it to cloud.konghq.com/login/.
Paste the URI into a browser address bar. An Okta login page should appear.
Using an account that belongs to one of the groups you just mapped (for example, an account belonging to the service_admin group in Okta), log in with your Okta credentials.

If a group-to-team mapping exists, the user is automatically provisioned with a Kong Konnect account with the relevant team membership.
Log out of this account, and log back in with a Konnect admin account.
In the left menu, select Organization.

You should see a list of users in this org, including a new entry for the previous user and the team that they were assigned to.

(Optional) Enable Kong Konnect as a dashboard app in Okta

If you want your users to have easy access to Kong Konnect alongside their other apps, you can add it to your Okta dashboard.

Log in to your Okta admin account.
Click Applications > Applications, then select your Kong Konnect Okta application.
On General tab, click Edit for the General Settings pane.
In the Application section, click the Implicit (hybrid) checkbox for the Grant type.
In the Login section:
1. In the Login Initiated by menu, select Either Okta or App.
2. For the Application Visibility, click the Display application icon to users checkbox.
3. In the Initiate login URI box, enter your organization’s login URI. You can find the URI in Kong Konnect by going to Settings > Identity Management.
Click Save.