Skip to content
Kong Summit 2022: Where API Innovation Runs Wild  —Learn More →
|
search
Konnect Cloud

(Legacy) Set Up SSO with Okta

This documentation is for the legacy Konnect environment at konnect.konghq.com. For the cloud.konghq.com environment, see the current Konnect documentation.

As an alternative to Konnect Cloud’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 Konnect Cloud using their Okta credentials, without needing a separate login.

You can’t mix authenticators in Konnect Cloud. 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.

Important: Enabling SSO through Okta for a particular Konnect organization is irreversible. You cannot revert to native Konnect authentication after the switch has been made.

Make sure that you are certain you want to switch, and are ready to manage authentication and authorization through Okta for this Konnect organization.

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.

Here are the steps you need to complete, in both Okta and Konnect. 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 Konnect Cloud account integration.

  1. Sign in to your Okta admin account.
  2. From the left menu, select Applications, then Create App Integration.

  3. Select the application type:

    1. Under Sign-in method, select OIDC - OpenID Connect.
    2. Under Application Type, select Web Application.
  4. Select Next. Configure the application:
    1. Create a unique name for your application.
    2. Under Grant Type, select Authorization Code.
    3. In both the Sign-in redirect URIs and Sign-out redirect URIs fields, enter: https://konnect.konghq.com/login
    4. In the Assignments section, for Controlled access, choose your preferred access level for this application. This preferred access level sets the permissions for Okta admins.

  5. Save your settings to generate connection details.

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

Set up claims in Okta

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.

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

  2. From the left menu, select Security > API.

  3. Select the Custom Authorization Server that you want to configure.

  4. Go to the Claims tab.

    You need to configure two claims: groups and login_email.

  5. In the Claim type menu, select ID, then select 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 dropdown, then enter .* in the field
    Include in Choose The following scopes and select openid

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

  7. Select Create to save. Add another claim, this time for user login information:

    Field Value
    Name login_email
    Include in token type ID token, Always
    Value type Expression
    Value user.login
    Include in Choose The following scopes and select openid

    This claim uses emails to map users to Konnect login instances.

  8. Select Create to save the second claim.

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

Test claims and find groups for mapping

  1. Open the Token Preview tab.

  2. Select your client, set Grant Type to Authorization Code, and choose an Okta user to test the claim with.

  3. Set the scope to openid, then select Preview Token.

  4. In the generated preview, check to make sure that groups and login_email values are present.

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

  1. In another separate browser tab, log in to Konnect Cloud.
  2. Open Settings, then Identity Management.

  3. Select Okta.

    Refer back to your Okta application to fill in the following fields.

  4. Copy the Okta domain from your Okta application, then paste it into the Okta Domain field in Konnect.

  5. Copy and paste the Client ID and Client Secret from your Okta application into Konnect Cloud.

    See the Okta developer documentation to learn more about client credentials in Okta.

  6. For the Organization Login Path, enter a unique string (for example, somepath).

    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 will need to choose another one.
    • The path can be any alphanumeric string.
    • The path does not require a slash (/).

Map roles to groups

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

After mapping is set up:

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

Any changes to the mapped Okta groups on the Okta side are reflected in Konnect Cloud. 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 permissions in Konnect to align with the new group-to-role mapping.

  1. Referring to the token preview in Okta, 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, be aware that not all of these groups may be accessible by the groups claim. See the claims setup step for details.

  2. Enter your Okta groups in the relevant fields.

    Each Konnect role 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 role in Konnect. You can hover over the info (i) icon beside each field to learn more about the role, or see Users and Roles for more information.

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

Test and apply configuration

  1. (Optional) Under Logout Behavior, enable Single Logout (SLO) by checking the box.

    If this option is enabled, signing out from Konnect also signs users out of their Okta session.

  2. Select Test Configuration to make sure the configuration details are valid.

    You must test configuration before saving. If you have filled out all required fields but the Save button remains greyed out, run the test first to enable saving.

    When you test the configuration, Konnect runs a connection check. If the connection test succeeds, the page reloads and prints the message Configuration tested successfully.

    Any subsequent changes to the configuration require a test before saving.

  3. Save your changes, then confirm that you want to change your identity provider to Okta.

    Warning: This change is irreversible. Once you switch to Okta, you cannot revert to using native Konnect authentication.

  4. Konnect generates a login URI based on the Organization Login Path you set earlier. Copy this URI.

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

Log in through Okta to test the integration

  1. Copy your Konnect organization’s login URI.

    If you ever need to find the path again, you can always find it under Settings > Identity Management, then copy Organization Login URI from this page.

  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-role mapping exists, the user is automatically provisioned with a Konnect Cloud account with the relevant permissions.

  4. Log out of this account, and log back in with a Konnect admin account.

  5. 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 role that they were assigned.

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

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

  1. Sign in to your Okta admin account.
  2. Select Applications, then open your Konnect Cloud Okta application.
  3. Scroll to General Settings and select Edit.
  4. In the Application section, set Grant type to Implicit (Hybrid).
  5. In the Login section:
    1. Set Login Initiated by to Either Okta or App.
    2. Set Application Visibility to Display application icon to users
    3. Set Initiate login URI to your organization’s login URI. You can find the URI in Konnect Cloud under Settings > Identity Management.
  6. Select Save.

Okta reference docs