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
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
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
First, complete the following in Okta:
Then, you can set up Konnect to talk to the Okta application:
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:
- For the Sign-in method, select OIDC - OpenID Connect.
- For the Application Type, select Web Application.
- Click Next.
- Configure the application:
- In the App integration name box, enter a unique name for your application.
- For the Grant type, ensure the Authorization Code checkbox is selected.
- For both the Sign-in redirect URIs and
Sign-out redirect URIs boxes, enter:
- In the Assignments pane, for Controlled access, choose your
preferred access level for this application. This preferred access level sets the permissions for
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
Click ID, then click Add Claim.
groups claim by filling in the following fields:
|Include in token type
||ID token, Always
||Select Matches regex from the drop-down, then enter
.* in the field.
||Choose The following scopes and select
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
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.
If you have problems setting up these claims, refer to the Okta documentation
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.
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
Click Preview Token.
In the generated preview, ensure that the
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.
- Go to Security > API.
Copy the issuer URI for your authorization server. It should look
something like this:
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:
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:
Konnect uses this string to generate a custom login
URL for your organization.
- 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
- 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
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
- 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
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.
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
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
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
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:
- In the Login Initiated by menu, select Either Okta or App.
- For the Application Visibility, click the Display application icon to users checkbox.
- 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.
Okta reference docs