Skip to content
|
Kong Konnect
github-edit-pageEdit this page
report-issueReport an issue

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 using OpenID Connect or SAML. These authentication methods allow your users to log in to Kong Konnect using their Okta credentials without needing a separate login.

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

This topic covers configuring Okta. For generic instructions on configuring SAML or OIDC for use with other identity providers, see the generic SSO guide.

Prerequisites

  • Ensure that any users that need to use Konnect SSO are added to Okta

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

Configure an application and group claims in Okta

  1. Create a new OIDC application in Okta to manage Kong Konnect account integration. Configure the following settings:
    • Application Type: Web Application

    • Grant type: Authorization Code

    • Sign-in redirect URIs: https://cloud.konghq.com/login (This is a placeholder value that you’ll replace later)

    • Sign-out redirect URIs: https://cloud.konghq.com/login (This is a placeholder value that you’ll replace later)

    • Controlled access: Select a group assignment option

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

    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.

  2. Add users to the Okta application.

  1. Create a new SAML 2.0 application in Okta to manage Kong Konnect account integration. Configure the following placeholder settings:

    • Single Sign-On URL: https://global.api.konghq.com/v2/authenticate/login_path/saml/acs

    • Audience URI (SP Entity ID): https://cloud.konghq.com/sp/SP_ID

  2. Optional: To include additional user attributes beyond authentication, add the following three attributes in the Attribute Statements:

    Name Name format Value
    firstName Unspecified user.firstName
    lastName Unspecified user.lastName
    email Unspecified user.email

  3. Add users to the Okta application.

  4. Generate a signing certificate to use in Konnect.

Set up Konnect

Provide Okta connection details

  1. In Kong Konnect, click organizations icon Organization > Settings, and then click the Authentication Scheme tab.

  2. Click Configure for OIDC.

  3. In Okta, update the placeholder Single Sign-On URL and Audience URI (SP Entity ID) values that you set in the previous section with the Konnect login URI.

  4. In Okta, locate your issuer URI in your authorization server settings. It should look like the following: https://{yourOktaOrg}.okta.com/oauth2/default

  5. Paste the issuer URI from Okta in the Provider URL field in Konnect.

  6. In Okta, copy your client ID and client secret from your Konnect application.

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

  8. In the Organization Login Path box, enter a unique string that will be used in the URL your users use to log in. For example: examplepath.

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

  9. After clicking Save, close the configuration dialog and from the OIDC context menu, click Enable OIDC.

  1. In Kong Konnect, click organizations icon Organization > Settings, and then click the Authentication Scheme tab.

  2. Click Configure for SAML.

  3. In Okta, go to Sign On page in the Okta application created in the previous step and copy the IDP Metadata URL under the Settings section. It should look like: https://<your-okta-domain>.okta.com/app/exkgzjkl0kUZB06Ky5d7/sso/saml/metadata

  4. In the Login Path box, enter a unique string that will be used in the URL your users use to log in. For example: examplepath.

    Requirements:

    • The path must be unique across all Konnect organizations. If your desired path is already taken, you must choose another one.
    • The path can be any alphanumeric string.
    • The path does not require a slash (/).
  5. Click Save.
  6. Copy the Single Sign-On URL and Audience URI that display after you configured SAML SSO.

  7. In Okta, update the placeholder Single Sign-On URL and Audience URI (SP Entity ID) values that you set in the previous section with the Single sign-on URL and Audience URI that display in the SAML config in Konnect.

  8. In Konnect, close the configuration dialog and click Enable SAML from the context menu.

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

  1. Configure a custom authorization server.

    Important: Using the Okta API to set up group claims with a custom authorization server is an additional paid Okta feature. Alternatively, you can use the org authorization server and create a group, enable group push, and add a group claim to the org authorization server instead.

  2. Navigate to the Token Preview tab of your authorization server and configure the following:
    • OAuth/OIDC client: Enter the client name you previously created for your Okta application
    • Grant Type: Authorization Code
    • User: Select an Okta user that is assigned to the Konnect application to test the claim with
    • Scope: openid, email, profile

    In the generated Preview Token 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.

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

  4. In Kong Konnect, go to organizations icon Organization > Settings, click the Team Mappings tab 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.

  5. Click Save.

Test and apply the configuration

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

Test the SSO configuration by navigating to the login URI based on the organization login path you set earlier. For example: https://cloud.konghq.com/login/examplepath, where examplepath is the unique login path string set in the previous steps.

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

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

In Okta, navigate to the General Settings of your application and configure the following settings:

Okta setting Value
Grant type Implicit (hybrid)
Login Initiated by Either Okta or App
Application Visibility Display application icon to users
Initiate login URI Enter your organization’s login URI. You can find the URI in Kong Konnect by going to Settings > Identity Management.

Okta reference docs