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

Prepare the Okta application

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

  1. Sign in to your Okta admin account.
  2. In the sidebar, click Applications > Applications, then click Create App Integration.

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

  5. Click Save.

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

Optionally set up claims in Okta to have Okta send the correct information to your Konnect org, set up claims to extract that information.

  1. Open your Okta account in a new browser tab.

  2. In the sidebar, select Security > API.

  3. Choose the authorization server you wish to configure.

  4. Click the Claims tab to configure the groups claim.

  5. Click ID, then click Add Claim.

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

    Note: If the authorization server includes groups from third-party applications, like Google Groups, the groups claim will not detect them. To address this, an Okta administrator must manually recreate these groups in Okta by exporting the group data in CSV format and then importing it to create a new group.

  7. Click Create.

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

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

  1. Sign in to your Okta admin account.
  2. In the sidebar, click Applications > Applications, then click Create App Integration.

  3. Select the application type:

    1. For the Sign-in method, select SAML 2.0.
    2. Click Next.
  4. Configure the application:
    1. In the General Settings page, enter a unique name for your application in the App Name box. Optionally add a logo in App Logo and update App Visibility. Click Next.
    2. In the Configure SAML page:
      1. Add placeholder values for the below fields.
        1. Single Sign-On URL: https://global.api.konghq.com/v2/authenticate/login_path/saml/acs
        2. Audience URI (SP Entity ID): https://cloud.konghq.com/sp/SP_ID

    3. Optional: In the Attribute Statements, add the following three attributes:

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

    4. Optional: In the Group Attributes, add the following attribute:

      Name Name format Filter Filter Value
      groups Unspecified Matches regex .*
    5. Click Next.
    6. On the Feedback page, select I’m an Okta customer adding an internal app and click Finish.

Add a user to your application

  1. In the sidebar of your Okta account, click Applications > Applications.

  2. Select the Konnect application.

  3. Click the Assignments tab.

  4. Click Assign > Assign to People, and then click Assign next to the name of the users you want to add.

  5. Optional: In the dialog, enter additional information about the user.

  6. Click Save and Go Back.

  7. Click Done.

Test claims and find mapping groups:

  1. In the sidebar of your Okta account, click Security > API.

  2. Select the authorization server that you want to configure.

  3. Click the Token Preview tab.

  4. Enter your client in the OAuth/OIDC client box. This is the name you created previously for your Okta application.

  5. In the Grant Type menu, select Authorization Code.

  6. In the User menu, select an Okta user that is assigned to the Konnect application to test the claim with.

  7. In the Scope box, enter openid, email, and profile.

  8. Click Preview Token.

  9. In the generated preview, ensure that the groups value is present.

  10. From the list of groups in the preview, identify groups that you want to use in Konnect. Take note of these groups.

  1. In the sidebar of your Okta account, click Applications > Applications.

  2. Select the Konnect application.

  3. Click the Assignments tab.

  4. Click Assign > Assign to People, and then click Assign next to the name of the users you want to add.

  5. Optional: In the dialog, enter additional information about the user.

  6. Click Save and Go Back.

  7. Click Done.

Set up Konnect

Provide Okta connection details

  1. In another separate browser tab, log in to Kong Konnect.
  2. Click organizations icon Organization > Settings, then Authentication Schemes.

  3. Click Configure provider for OIDC.

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

  5. Paste the issuer URI from Okta in the Issuer URI box in Konnect.

  6. In Okta, copy your client ID and client secret by going to Applications > Applications and selecting 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. 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 (/).
  9. Click Save.
  10. From the list of authentication providers, open the context menu and Enable OIDC.
  1. In another separate browser tab, log in to Kong Konnect.
  2. Click organizations icon Organization > Settings, then Authentication Schemes.

  3. Click Configure provider for SAML.

  4. In Okta, locate your Metadata :
    1. Go to Sign On page in the Okta application created in the previous step.

    2. Copy the IDP Metadata URL under the Settings section. It should look like:

        https://<your-okta-domain>.okta.com/app/exkgzjkl0kUZB06Ky5d7/sso/saml/metadata

  5. In the 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 choose another one.
    • The path can be any alphanumeric string.
    • The path does not require a slash (/).
  6. Click Save.
  7. From the list of authentication providers, open the context menu and Enable SAML.
  8. Close the configuration dialog and click Enable on your SAML provider.
  9. In Okta update the placeholder Single Sign-On URL and Audience URI (SP Entity ID) that you set in the previous section.
  10. Close the configuration dialog and click Enable on your SAML provider.

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

  2. In Kong Konnect, go to organizations icon 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.

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

  1. Copy your Konnect organization’s login URI.

  2. Paste the URI into a browser address bar. An Okta login page should appear.

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

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

Note: If you need to find your login path, go to My Account, locate the Login Path, and append it to cloud.konghq.com/login/.

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

  1. Log in to your Okta admin account.
  2. Click Applications > Applications, then select your Kong Konnect Okta application.
  3. On General tab, click Edit for the General Settings pane.
  4. In the Application section, click the Implicit (hybrid) checkbox for the Grant type.
  5. 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.
  6. Click Save.

Okta reference docs