Konnect SSO

Konnect supports external single sign-on authentication using an Identity Provider (IdP). Using SSO in Konnect, you can enable authentication for the following:

• The Konnect platform: Allow Org admins to log in with SSO. This is an alternative to Konnect’s built-in authentication.
• Dev Portals: Allow developers to log in to the Dev Portal with SSO.

SSO for each of these is configured through different settings, so enabling one doesn’t automatically enable the other. Both methods support OIDC and SAML-based SSO.

We recommend using a single authentication method, however, Konnect supports the ability to combine built-in authentication with either OIDC or SAML based SSO. Combining both OIDC and SAML based SSO is not supported. Keep built-in authentication enabled while you are testing IdP authentication. Only disable built-in authentication after successfully testing the configurations in these guides.

Konnect supports any OIDC or SAML-compliant provider. The following have been verified to work out-of-the-box:

• Okta
• Azure Active Directory
• Oracle Identity Cloud Service
• Keycloak

To configure SSO in Konnect, you must configure the following in your IdP:

• Add Konnect to your IdP as an application
• Add users that need to use SSO to the IdP tenant.
• Set claims in your IdP

For Okta-specific configuration steps, see the Configure a Konnect application in Okta section on this page.

You can configure Konnect SSO in the following ways:

Note: When you configure the organization login path, enter a unique string that will be used in the URL your users use to log in. For example: examplepath.

• 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 (/).
• (SAML only) When you save this configuration, Konnect will generate two new values: a Single Sign-On URL and an Audience URI. In your IdP, update the previous placeholder Single Sign-On URL and Audience URI (SP Entity ID) with the new values generated by Konnect.

When configuring SSO for Dev Portal, it’s important to consider the following points:

• Developers are auto-approved by Konnect when they use SSO to log in to the Dev Portal. This is because Konnect outsources the approval process to the IdP instance when using SSO. Therefore, you must restrict who can sign up from the IdP rather than through Konnect.
• If you plan on using team mappings from an IdP, they must be from the same IdP instance as your SSO.
• If you have multiple Dev Portals, keep in mind that each Dev Portal has a separate SSO configuration. You can use the same IdP for multiple Dev Portals or different IdPs per Dev Portal.

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.

Depending on your IdP, choose one of the following to test the configuration:

• Konnect Org: 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/$YOUR_PATH, where $YOUR_PATH is the unique login path string set in the previous steps.
• Dev Portal: Test the SSO configuration by navigating to the callback URL for your Dev Portal. For example: https://$YOUR_PORTAL_ID.us.portal.konghq.com/login.

If the configuration is correct, you will see the IdP sign-in page.

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

If you want to use Okta as your IdP provider for SSO, you need an Okta account with administrator access to configure Applications and Authorization Server settings.

Additionally, if you’re configuring Okta SSO for Dev Portal, you’ll need a non-public Kong Konnect Dev Portal created in your Konnect organization.

Now you can finish setting up SSO in Konnect.

As an alternative to Konnect’s native authentication, you can enable single sign-on (SSO) using any identity provider (IdP) that supports OpenID Connect. This allows your users to log in to Konnect using their existing SSO credentials

To enable OIDC:

1. Send a POST or PATCH request to the /identity-providers endpoint, making sure oidc is selected for type and scopes. The profile and email scopes are recommended so Konnect obtains the user’s name and email address in the token response.
2. Once the SSO configuration is set, you can enable the OIDC auth method with the /authentication-settings endpoint by setting oidc_auth_enabled: true.
3. Verify the configuration is valid by logging in at https://cloud.konghq.com/login/$YOUR_LOGIN_PATH.

When you configure SSO for the Konnect platform and Dev Portal, you have the option to configure team mappings from your IdP as well. Team mappings allow you to map teams from your IdP to Konnect Org teams and Dev Portal teams.

After you configure Konnect SSO settings in your IdP, you can configure team mappings with the following:

When you configure team mappings for the Konnect org, keep the following in mind:

• You must have at least one group mapped to save configuration changes.
• To manage user and team memberships in Konnect from the Organization settings, select the Konnect Mapping Enabled checkbox. If you enable this, approving new users is a two step process. New users logging in to Konnect with their IdP credentials will get an access error and Konnect administrators will need to map the new user to a valid team before the user is granted access.
• 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 IdP groups in the relevant fields.

Once team mappings are set up:

• IdP users belonging to the mapped groups can log in to Konnect.
• When a user logs into Konnect with their IdP 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 IdP 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 the IdP, or adjust the team mapping.

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

• Removing a user from a group in the IdP 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.

To seamlessly use the Konnect Portal Editor preview experience, you may need to configure your IdP with additional settings to ensure the login flow and preview environment function properly.

• The Sign On URL (SSO URL) must be set to the path on your Dev Portal’s custom domain, if applicable. For example: https://example.com/login/sso
• For for OIDC authentication, you should add an additional sign-in redirect URI set to the Kong-managed Konnect Portal Editor Preview domain: https://$YOUR_SUBDOMAIN.$GEO.kongportals.com/login
• Specifically for SAML, the primary Reply URL (Assertion Consumer Service URL) must be set to the path on your Dev Portal’s custom domain, if applicable. For example: https://example.com/api/v2/developer/authenticate/saml/acs
  • To support the Konnect Portal Editor, you must also set an additional Reply URL (other callable SSO URLs) to the Kong-managed Konnect Portal Editor Preview domain: https://$YOUR_SUBDOMAIN.$GEO.kongportals.com/api/v2/developer/authenticate/saml/acs
• Your IdP must be configured to allow embedding its sign in screen within an iframe. For example, in Okta, you can configure Trusted Origins with your IdP. You should add https://cloud.konghq.com as a Trusted Origin for iframe embedding. This will allow your users to use the IdP login flow in the Konnect Portal Editor preview environment.