Konnect SSO

Uses: Konnect Platform

Supported IdP providers

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

SSO configuration

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:

Feature	UI setting	API endpoint
Konnect platform	Go to the Authentication Scheme organization settings¹	`/identity-providers`¹
Dev Portal	Go to the Identity settings for your Dev Portal	`/portals/{portalId}/identity-providers`

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.

Configure a Konnect application in Okta

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.

From the Applications section of the Okta console, select Create App Integration and choose OIDC - OpenID Connect with Web Application for the Application type. Provide the following configuration details:

Okta setting	Configuration
Grant type	Authorization Code
Sign-in redirect URIs	Konnect Org: `https://cloud.konghq.com/login` Dev Portal: `https://$YOUR_PORTAL_URL/login`
Sign-out redirect URIs	Konnect Org: `https://cloud.konghq.com/login` Dev Portal: `https://$YOUR_PORTAL_URL/login`

Optional: If you want to map Okta group claims to Konnect Organization or Dev Portal Teams, modify the OpenID Connect ID Token claims in the Application > Sign On section of the Okta configuration, setting the following values:
- Group claims type: Filter
- Group claims filter: Enter groups for the claim name and enter Matches regex as the filter type and .* for the filter value.
This claim specifies which user’s groups to include in the token, in this case the wildcard regex specifies that all groups will be included.

If the authorization server is retrieving additional groups from third-party applications (for example, Google groups), the groups claim will not contain them. If you want to use these third-party groups, the Okta administrator will need to duplicate them directly in Okta or use a custom token to include them in the groups claim.
Assign desired groups and users to the new Okta application.
Locate the following values in the Okta console, which will be used later for the Konnect configuration.
- Client ID: Located in your Application General -> Client Credentials settings.
- Client Secret: Located in your Application General -> Client Secrets settings.
- Issuer URI : The Issuer is typically found in the Security -> API -> Authorization Servers settings. It should look like the following: https://<okta-org-id>.okta.com/oauth2/default

From the Applications section of the Okta console, select Create App Integration and choose SAML 2.0. Provide a name and the following configuration details:

Okta setting	Configuration
Single Sign-On URL	Konnect Org: `https://global.api.konghq.com/v2/authenticate/login_path/saml/acs` Dev Portal: `https://$YOUR_PORTAL_URL/api/v2/developer/authenticate/saml/acs`
Audience URI (SP Entity ID)	`https://cloud.konghq.com/sp/SP_ID`

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

Optional: If you want to use group claims for Konnect developer team mappings, configure a groups attribute claim and fill in the following fields:

Name	Name format	Filter	Filter value
groups	Unspecified	Matches regex	.*

Generate a signing certificate to use in Konnect.
Assign desired groups and users to the new Okta application.

Now you can finish setting up SSO in Konnect.

Enable OIDC

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:

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.
Once the SSO configuration is set, you can enable the OIDC auth method with the /authentication-settings endpoint by setting oidc_auth_enabled: true.
Verify the configuration is valid by logging in at https://cloud.konghq.com/login/$YOUR_LOGIN_PATH.

Team mapping configuration

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:

Feature	UI setting	API endpoint
Konnect platform	Go to the Team Mapping in the Organization settings.	`/identity-provider/team-mappings`
Dev Portal	Click on a Dev Portal and go to Team Mappings in its settings.	`/portals/{portalId}/identity-provider/team-group-mappings`

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.

Konnect Dev Portal Editor considerations

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
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 Dev Portal domain: https://$YOUR_SUBDOMAIN.edge.us.portal.konghq.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.

FAQs

I’m experiencing authentication issues and I have a large number of groups, how do I troubleshoot this?

If users are assigned a very large number of groups (over 150 in most cases), the IdP may send the groups claim in a non-standard manner, causing authentication issues.

To work around this limitation in the IdP, we recommend using group filtering functions provided by the IdP for this purpose. Here are some quick reference guides for common IdPs:

You may need to contact the support team of your identity provider in order to learn how to filter groups emitted for the application.

In the token payload, the groups claim is configured correctly but still appears empty, or it includes some groups but not all when Okta is configured as the IdP. How do I fix this?

This issue might happen if the authorization server is pulling in additional groups from third-party applications, for example, Google groups.

An Okta administrator must duplicate the third-party groups and re-create them directly in Okta. They can do this by exporting the group in CSV format, then importing the CSV file into Okta to populate the new group.

This may happen if the wrong issuer URI was used, for example, the URI from your application’s settings. The issuer URI must be in the following format, where default is the name or ID of the authorization server:

https://example.okta.com/oauth2/default

You can find this URI in your Okta developer account, under Security > API.

How do I debug my integration with Okta?

The Okta console provides a Token Preview feature which will be useful in verifying configuration values for these SSO configuration instructions. If you encounter issues configuring SSO with Okta, start by checking the Token Preview for the Okta application you created.