diff --git a/app/_data/docs_nav_konnect.yml b/app/_data/docs_nav_konnect.yml index f41d96732e7..05daaba04b5 100644 --- a/app/_data/docs_nav_konnect.yml +++ b/app/_data/docs_nav_konnect.yml @@ -183,8 +183,10 @@ url: /dev-portal/access-and-approval/add-teams/ - text: Manage Application Registrations url: /dev-portal/access-and-approval/manage-app-connections/ - - text: Configure SSO for Dev Portal + - text: Configure generic SSO for Dev Portal url: /dev-portal/access-and-approval/sso/ + - text: Configure Okta SSO + url: /dev-portal/access-and-approval/okta-idp/ - text: Application Lifecycle url: /dev-portal/applications/application-overview/ - text: Register and create an application as a developer @@ -272,7 +274,7 @@ url: /org-management/org-switcher/ - text: Configure Generic SSO url: /org-management/sso/ - - text: Configure Okta + - text: Configure Okta SSO url: /org-management/okta-idp/ - text: Login Sessions Reference url: /org-management/sessions-reference/ @@ -425,3 +427,5 @@ url: /reference/audit-logs/ - text: Verify audit log signatures url: /reference/verify-signatures/ + - text: IdP SAML attribute mapping + url: /reference/saml-idp-mappings/ diff --git a/app/_includes/md/konnect/generic-sso.md b/app/_includes/md/konnect/generic-sso.md new file mode 100644 index 00000000000..247c9ea37f6 --- /dev/null +++ b/app/_includes/md/konnect/generic-sso.md @@ -0,0 +1,168 @@ + + +## Prerequisites + +* {{site.konnect_short_name}} must be added to your IdP as an application +* Users that need to use SSO are added to your IdP tenant +* Claims are set up in your IdP + + +## Set up SSO in {{site.konnect_short_name}} +{% navtabs %} +{% navtab OIDC%} +The {{site.konnect_short_name}} OIDC integration allows you to configure various identity providers. While technically any OIDC-compliant provider can be used, the following have been verified: + +* Okta +* Azure Active Directory +* Oracle Identity Cloud Service +* Keycloak + +{% if include.desc == "Konnect Org" %} +1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization** > **Settings**, and then click the **Authentication Scheme** tab. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portals/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +{% endif %} + +1. Click **Configure** for OIDC. + +1. Paste the issuer URI from your IdP in the **Issuer URI** field. + +1. Paste the client ID from your IdP in the **Client ID** field. + +1. Paste the client secret from your IdP in the **Client Secret** field. + +{% if include.desc == "Konnect Org" %} +1. 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 {{site.konnect_short_name}} 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 (`/`). +{% endif %} + +1. Optional: You can configure custom IdP-specific behaviors in the **Advanced Settings** of the OIDC configuration form. The following options are available: + * **Scopes**: Specify the list of scopes {{site.konnect_short_name}} requests from the IdP. By default, {{site.konnect_short_name}} requests the `openid`, `email`, and `profile` scopes. The `openid` scope is required and cannot be removed. + * **Claim Mappings**: Customize the mapping of required attributes to a different claim in the `id_token` {{site.konnect_short_name}} receives from the IdP. By default, {{site.konnect_short_name}} requires three attributes: Name, Email, and Groups. The values in these attributes are mapped as follows: + * `name`: Used as the {{site.konnect_short_name}} account's `full_name`. + * `email`: Used as the {{site.konnect_short_name}} account's `email`. + * `groups`: Used to map users to teams defined in the team mappings upon login. +{% if include.desc == "Dev Portal" %} +1. Optional: [Map existing developer teams from IdP groups to {{site.konnect_short_name}} Dev Portal teams](/konnect/dev-portal/access-and-approval/add-teams/). +{% endif %} +{% if include.desc == "Konnect Org" %} +1. Optional: To map existing teams from IdP groups to {{site.konnect_short_name}}, do the following: + 1. Configure group claims in your IdP application. Be sure to add the following to the scope: `openid`, `email`, `profile` + 1. In {{site.konnect_saas}}, go to {% konnect_icon organizations %} **Organization** > **Settings**, click the **Team Mappings** tab and do at least one of the following: + + * To manage user and team memberships in {{site.konnect_short_name}} 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 {{site.konnect_short_name}} teams, select the **IdP Mapping Enabled** checkbox and enter your Okta groups in the relevant fields. + + Each {{site.konnect_short_name}} 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 {{site.konnect_short_name}}. You can hover + over the info (`i`) icon beside each field to learn more about the team, or + see the [teams reference](/konnect/org-management/teams-and-roles/teams-reference/) + for more information. + + You must have at least one group mapped to save configuration changes. + + 1. Click **Save**. +{% endif %} +1. After clicking **Save**, close the configuration dialog and from the OIDC context menu, click **Enable OIDC**. +{% endnavtab %} +{% navtab SAML %} + +The {{site.konnect_short_name}} SAML integration allows you to configure various identity providers. While technically any SAML-compliant provider can be used, the following have been verified: + +* Okta +* Azure Active Directory +* Oracle Identity Cloud Service +* Keycloak + +{% if include.desc == "Konnect Org" %} +1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization** > **Settings**, and then click the **Authentication Scheme** tab. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portals/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +{% endif %} + +1. Click **Configure** for SAML. + +1. Enter the **Metadata URL** from your IdP in the **IDP Metadata URL** field. + +{% if include.desc == "Konnect Org" %} +1. In the **Login Path** field, 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 {{site.konnect_short_name}} organizations. + * The path can be any alphanumeric string. + * The path does not require a slash (`/`). +{% endif %} + +1. After clicking **Save**, configure the SP Entity ID and Login URL on your SAML IdP. +{% if include.desc == "Dev Portal" %} +1. Optional: [Map existing developer teams from IdP groups to {{site.konnect_short_name}} Dev Portal teams](/konnect/dev-portal/access-and-approval/add-teams/). +{% endif %} +{% if include.desc == "Konnect Org" %} +1. Optional: To map existing teams from IdP groups to {{site.konnect_short_name}}, do the following: + 1. Configure group claims in your IdP application. Be sure to add the following to the scope: `openid`, `email`, `profile` + 1. In {{site.konnect_saas}}, go to {% konnect_icon organizations %} **Organization** > **Settings**, click the **Team Mappings** tab and do at least one of the following: + + * To manage user and team memberships in {{site.konnect_short_name}} 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 {{site.konnect_short_name}} teams, select the **IdP Mapping Enabled** checkbox and enter your Okta groups in the relevant fields. + + Each {{site.konnect_short_name}} 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 {{site.konnect_short_name}}. You can hover + over the info (`i`) icon beside each field to learn more about the team, or + see the [teams reference](/konnect/org-management/teams-and-roles/teams-reference/) + for more information. + + You must have at least one group mapped to save configuration changes. + + 1. Click **Save**. +{% endif %} +1. In {{site.konnect_short_name}}, close the configuration dialog and click **Enable SAML** from the context menu. +{% endnavtab %} +{% endnavtabs %} + +## Test and apply the configuration + +{:.important} +> **Important:** Keep built-in authentication enabled while you are testing IdP authentication. Only disable built-in authentication after successfully testing IdP authentication. + +{% if include.desc == "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/examplepath`, where `examplepath` is the unique login path string set in the previous steps. +{% endif %} + +{% if include.desc == "Dev Portal" %} +Test the SSO configuration by navigating to the callback URL for your Dev Portal. For example: `https://{portalId}.{region}.portal.konghq.com/login`. +{% endif %} + +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. + +## Troubleshooting + +
Troubleshooting authentication issues with large numbers of groups + +{% capture large_group_auth %} +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: +* [Azure group filtering](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#group-filtering) +* [Okta group filtering](https://support.okta.com/help/s/article/How-to-send-certain-groups-that-the-user-is-assigned-to-in-one-Group-attribute-statement) + +You may need to contact the support team of your identity provider in order to learn how to filter groups emitted for the application. +{% endcapture %} + +{{ large_group_auth | markdownify }} + +
+ diff --git a/app/_includes/md/konnect/okta-sso.md b/app/_includes/md/konnect/okta-sso.md new file mode 100644 index 00000000000..701e56049f3 --- /dev/null +++ b/app/_includes/md/konnect/okta-sso.md @@ -0,0 +1,246 @@ + +## Prerequisites +{% if include.desc == "Dev Portal" %} +* Ensure that any users that need to use the Dev Portal SSO are added to Okta +{% endif %} +{% if include.desc == "Konnect Org" %} +* Ensure that any users that need to use {{site.konnect_short_name}} SSO are added to Okta +{% endif %} +* To set up Okta single sign-on (SSO) for {{site.konnect_short_name}}, you need access to an Okta admin account and a {{site.konnect_short_name}} 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 + +{% navtabs %} +{% navtab OIDC %} +1. Create a [new OIDC application in Okta](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) to manage {{site.konnect_saas}} 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 {{site.konnect_saas}} account. + +{% if include.desc == "Dev Portal" %} +1. Optional: If you want to use group claims for Konnect [developer team mappings](/konnect/dev-portal/access-and-approval/add-teams/), click the **Sign On** tab in Okta for your application to [configure a `groups` claim](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/#add-a-groups-claim-for-the-org-authorization-server) and configure the following fields: + + | Field | Value | + | ---|--- | + | Group claims type | Filter | + | Group claims filter | `groups`, select **Matches regex** from the drop-down, then enter `.*` in the field. +{% endif %} + + 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. + + {:.important} + > 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. + +1. [Add users to the Okta application](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-apps.htm). + +{% endnavtab %} +{% navtab SAML %} + +1. Create a [new SAML 2.0 application in Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard_saml.htm?cshid=ext_Apps_App_Integration_Wizard-saml) to manage {{site.konnect_saas}} 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` + +1. 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 | + +{% if include.desc == "Dev Portal" %} +1. Optional: If you want to use group claims for Konnect [developer team mappings](/konnect/dev-portal/access-and-approval/add-teams/), [configure a groups attribute claim](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/#add-a-groups-claim-for-a-custom-authorization-server) and fill in the following fields: + + | Name | Name format | Filter | Filter Value | + |---------|--------------|-----------------|--------------| + | groups | Unspecified | Matches regex | .* | +{% endif %} + +1. [Add users to the Okta application](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-apps.htm). + +1. [Generate a signing certificate](https://help.okta.com/en-us/content/topics/apps/manage-signing-certificates.htm) to use in {{site.konnect_short_name}}. + +{% endnavtab %} +{% endnavtabs %} + +## Set up {{site.konnect_short_name}} + +### Provide Okta connection details +{% navtabs %} +{% navtab OIDC %} +{% if include.desc == "Konnect Org" %} +1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization** > **Settings**, and then click the **Authentication Scheme** tab. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In a separate browser tab, open [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portals/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +{% endif %} + +1. Click **Configure** for OIDC. + +1. 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 {% if include.desc == "Dev Portal" %}Dev Portal callback URL{% endif %}{% if include.desc == "Konnect Org" %}{{site.konnect_short_name}} login URI{% endif %}. + +1. In Okta, locate your issuer URI in your authorization server settings. It should look like the following: `https://{yourOktaOrg}.okta.com/oauth2/default` + +1. Paste the issuer URI from Okta in the **Provider URL** field in {{site.konnect_short_name}}. + +1. In Okta, copy your client ID and client secret from your {{site.konnect_short_name}} application. + +1. Paste the **Client ID** and **Client Secret** from your Okta +application into {{site.konnect_saas}}. + + See the [Okta developer documentation](https://developer.okta.com/docs/guides/find-your-app-credentials/findcreds/) + to learn more about client credentials in Okta. +{% if include.desc == "Konnect Org" %} +1. 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 {{site.konnect_short_name}} 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 (`/`). +{% endif %} +{% if include.desc == "Dev Portal" %} +1. Optional: [Map existing developer teams from Okta groups to {{site.konnect_short_name}} Dev Portal teams](/konnect/dev-portal/access-and-approval/add-teams/). +{% endif %} +1. After clicking **Save**, close the configuration dialog and from the OIDC context menu, click **Enable OIDC**. +{% endnavtab %} +{% navtab SAML %} +{% if include.desc == "Konnect Org" %} +1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization** > **Settings**, and then click the **Authentication Scheme** tab. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In a separate browser tab, open [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portals/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +{% endif %} +1. Click **Configure** for SAML. + +1. 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://.okta.com/app/exkgzjkl0kUZB06Ky5d7/sso/saml/metadata` +{% if include.desc == "Konnect Org" %} +1. 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 {{site.konnect_short_name}} 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 (`/`). +{% endif %} +1. Click **Save**. +1. Copy the **Single Sign-On URL** and **Audience URI** that display after you configured SAML SSO. +1. 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 {% if include.desc == "Dev Portal" %}Dev Portal{% endif %}{% if include.desc == "Konnect Org" %}{{site.konnect_short_name}}{% endif %}. +{% if include.desc == "Dev Portal" %} +1. Optional: [Map existing developer teams from Okta groups to {{site.konnect_short_name}} Dev Portal teams](/konnect/dev-portal/access-and-approval/add-teams/). +{% endif %} +1. In {{site.konnect_short_name}}, close the configuration dialog and click **Enable SAML** from the context menu. + +{% endnavtab %} +{% endnavtabs %} +{% if include.desc == "Konnect Org" %} +### (Optional) Map {{site.konnect_short_name}} teams to Okta groups + +By mapping Okta groups to [{{site.konnect_short_name}} teams](/konnect/org-management/teams-and-roles/), +you can manage a user's {{site.konnect_short_name}} team membership directly through +Okta group membership. + +After mapping is set up: +* Okta users belonging to the mapped groups can log in to {{site.konnect_short_name}}. +* When a user logs into {{site.konnect_short_name}} with their Okta account +for the first time, +{{site.konnect_short_name}} automatically provisions an account with the +relevant roles. +* If your org already has non-admin {{site.konnect_short_name}} 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 +{{site.konnect_short_name}}, +but cannot edit their team membership from the {{site.konnect_short_name}} 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 +{{site.konnect_saas}}. For example: +* Removing a user from a group in Okta also deactivates their +{{site.konnect_short_name}} account. +* Moving a user from one group to another changes their team in {{site.konnect_short_name}} +to align with the new group-to-team mapping. + +1. [Configure a custom authorization server](https://help.okta.com/en-us/content/topics/security/api-config-auth-server.htm). + + {:.important} + > **Important:** Using the Okta API to set up group claims with a custom authorization server is an additional paid Okta feature. +1. [Navigate to the Token Preview tab](https://help.okta.com/en-us/content/topics/security/api-config-test.htm) 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. +1. Refer to the [token preview](#test-claims-and-find-groups-for-mapping) +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](#set-up-claims-in-okta) setup step for details. + +1. In {{site.konnect_saas}}, go to {% konnect_icon organizations %} **Organization** > **Settings**, click the **Team Mappings** tab and do at least one of the following: + + * To manage user and team memberships in {{site.konnect_short_name}} 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 {{site.konnect_short_name}} teams, select the **IdP Mapping Enabled** checkbox and enter your Okta groups in the relevant fields. + + Each {{site.konnect_short_name}} 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 {{site.konnect_short_name}}. You can hover + over the info (`i`) icon beside each field to learn more about the team, or + see the [teams reference](/konnect/org-management/teams-and-roles/teams-reference/) + for more information. + + You must have at least one group mapped to save configuration changes. + +1. Click **Save**. +{% endif %} + +## Test and apply the configuration + +{:.important} +> **Important:** Keep built-in authentication enabled while you are testing IdP authentication. Only disable built-in authentication after successfully testing IdP authentication. + +{% if include.desc == "Dev Portal" %} +1. Test the SSO configuration by navigating to the callback URL for your Dev Portal. For example: `https://{portalId}.{region}.portal.konghq.com/login`. + + You will see the Okta sign in window if your configuration is set up correctly. +1. Using an account that belongs to one of the groups you just mapped, log +in with your Okta credentials. + + If a group-to-team mapping exists, the user is automatically provisioned with a {{site.konnect_saas}} Dev Portal developer account with the relevant team membership. +1. In [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portals/), click the Dev Portal you configured SSO for and click **Developers** in the sidebar. + + You should see a list of users in this org, including a new entry for the user you used to log in. +{% endif %} +{% if include.desc == "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/examplepath`, where `examplepath` is the unique login path string set in the previous steps. +{% endif %} + +You can now manage your organization's user permissions entirely from the IdP application. + +## (Optional) Enable {{site.konnect_saas}}{% if include.desc == "Dev Portal" %} Dev Portal{% endif %} as a dashboard app in Okta + +If you want your users to have easy access to {{site.konnect_saas}}{% if include.desc == "Dev Portal" %} Dev Portal{% endif %} 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. {% if include.desc == "Dev Portal" %}You can find the URI in {{site.konnect_saas}} by going to your Dev Portal, clicking **Settings**, clicking the **Identity** tab, and then clicking **Configure provider** next to your authentication method.{% endif %}{% if include.desc == "Konnect Org" %}You can find the URI in {{site.konnect_saas}} by going to **Settings** > **Identity Management**.{% endif %}| \ No newline at end of file diff --git a/app/konnect/dev-portal/access-and-approval/okta-idp.md b/app/konnect/dev-portal/access-and-approval/okta-idp.md new file mode 100644 index 00000000000..389b04b1336 --- /dev/null +++ b/app/konnect/dev-portal/access-and-approval/okta-idp.md @@ -0,0 +1,12 @@ +--- +title: Set Up SSO with Okta +badge: enterprise +--- + +You can set up single sign-on (SSO) access to Dev Portals through Okta using OpenID Connect or SAML. These authentication methods allow developers to log in to a Dev Portal using their Okta credentials without needing a separate login. + +You cannot mix authenticators in a {{site.konnect_saas}} Dev Portal. With Okta authentication enabled, all developers will log in to the Dev Portal through Okta. + +This topic covers configuring Okta. For generic instructions on configuring SAML or OIDC for use with other identity providers, see the [generic SSO guide](/konnect/dev-portal/access-and-approval/sso/). + +{% include_cached /md/konnect/okta-sso.md desc='Dev Portal' %} \ No newline at end of file diff --git a/app/konnect/dev-portal/access-and-approval/sso.md b/app/konnect/dev-portal/access-and-approval/sso.md index 5741a79814d..71992d7810a 100644 --- a/app/konnect/dev-portal/access-and-approval/sso.md +++ b/app/konnect/dev-portal/access-and-approval/sso.md @@ -1,9 +1,9 @@ --- -title: Configure SSO for Dev Portal +title: Configure generic SSO for Dev Portal content_type: how-to --- -You can configure single sign-on (SSO) for {{site.konnect_short_name}} Dev Portal with OIDC. This allows developers to log in to Dev Portals by using their SSO credentials. This guide provides information about how to configure SSO for Okta, Azure AD, and Auth0, but you can use IdPs other than the ones listed as long as they follow the OIDC standard for SSO. +You can configure single sign-on (SSO) for {{site.konnect_short_name}} Dev Portal with OIDC. This allows developers to log in to Dev Portals by using their IdP credentials, without needing a separate login. This topic covers configuring SSO for use with various identity providers. If you want to configure Okta, please see the [Okta configuration guide](/konnect/dev-portal/access-and-approval/okta-idp/). Keep the following in mind when configuring SSO for Dev Portal: @@ -12,116 +12,9 @@ Keep the following in mind when configuring SSO for Dev Portal: * 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. * Dev Portal SSO is different than the [SSO for {{site.konnect_short_name}}](/konnect/org-management/oidc-idp). If you want to use SSO to log in to {{site.konnect_short_name}}, you must configure that separately. -## Prerequisites +{% include_cached /md/konnect/generic-sso.md desc='Dev Portal' %} -* Ensure that any users that need to use the Dev Portal SSO have been added to your IdP tenant -* An application for {{site.konnect_short_name}} configured in your IdP. - * [Okta](https://help.okta.com/en-us/content/topics/apps/apps_app_integration_wizard.htm) - * [Azure AD](https://learn.microsoft.com/graph/toolkit/get-started/add-aad-app-registration) - * [Auth0](https://auth0.com/docs/get-started/auth0-overview/create-applications) +## Related links - -## Configure an application and group claims in your IdP -{% navtabs %} -{% navtab Azure %} - -1. In [Azure](https://portal.azure.com/), [register an application](https://learn.microsoft.com/en-us/entra/identity-platform/quickstart-register-app?tabs=certificate) for {{site.konnect_short_name}}. Configure the following settings: - * **Redirect URI**: `https://cloud.konghq.com/login` - * Create a client secret and save the secret value. - -1. [Use the OIDC well-known discovery endpoint](https://learn.microsoft.com/en-us/azure/active-directory-b2c/secure-api-management?tabs=app-reg-ga#get-a-token-issuer-endpoint) to find and save the `issuer` value. - The `issuer` value will be used as the provider URL when configuring SSO in {{site.konnect_short_name}}. - -1. [Add a group claim](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims?tabs=appui#configure-groups-optional-claims). Enable all the group types settings and select **Group ID** for each setting in the token properties type. - -1. [Configure an optional claim](https://learn.microsoft.com/en-us/entra/identity-platform/optional-claims?tabs=appui#configure-optional-claims-in-your-application) with **ID** as the token type and **email** as the claim. - -{% endnavtab %} -{% navtab Okta %} - -1. Create a [new OIDC application in Okta](https://help.okta.com/oie/en-us/content/topics/apps/apps_app_integration_wizard_oidc.htm) to manage {{site.konnect_saas}} account integration. Configure the following settings: - * **Application Type**: Web Application - * **Grant type**: Authorization Code - * **Sign-in redirect URIs**: `https://cloud.konghq.com/login` - * **Sign-out redirect URIs**: `https://cloud.konghq.com/login` - - Leave this page open. You'll need the connection details here to configure your {{site.konnect_saas}} account. - -1. (Optional) If you want to use group claims for Konnect [developer team mappings](/konnect/dev-portal/access-and-approval/add-teams/), click the **Claims** tab in Okta to [configure a `groups` claim](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/main/#add-a-groups-claim-for-a-custom-authorization-server) and fill 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. - - {:.important} - > 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. - -1. [Add users to the Okta application](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-apps.htm). - -1. Test ID token claims and find groups for mapping. Configure the following claims settings: - * **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 {{site.konnect_short_name}} 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 {{site.konnect_short_name}}. Take note of these groups. - -{% endnavtab %} -{% navtab Auth0 %} -Kong offers OIDC support to allow Single-Sign-on for {{site.konnect_short_name}} and the Dev Portal. This guide shows you how to configure Auth0 for Dev Portal SSO. - -1. [Create an application in Auth0](https://auth0.com/docs/get-started/auth0-overview/create-applications/machine-to-machine-apps) and configure the following settings: - * **Application Type**: Machine to Machine Applications - * **Authorized API**: Auth0 Management API - * **Permissions**: Authorize the application for at least one permission, for example: `read:client_grants`. - This permission can be revoked later if desired, but one permission is required to create the application. - -1. [Configure the Auth0 application settings](https://auth0.com/docs/get-started/applications/application-settings): - * **Application Login URI**: `https://cloud.konghq.com/login` - * **Allowed Callback URLs**: `https://cloud.konghq.com/login` - * **Grant Types**: Authorization Code - -1. Create a login [action in Auth0](https://auth0.com/docs/customize/actions/write-your-first-action#create-an-action) and enter the following in the Actions Code Editor: - - ```js - exports.onExecutePostLogin = async (event, api) => { - if (event.authorization) { - // This transforms the ISO 8601 Timestamp string into the seconds integer representation that is expected for the OIDC standard, - // allowing the Konnect SSO validation to accept the format of the `updated_at` property when parsing the token claim. - api.idToken.setCustomClaim('updated_at', Math.floor(new Date(event.user.updated_at).getTime()/1000)) - } - }; - ``` - - {:.note} - > **Important:** This section is required because the Auth0 API implementation isn't inline with the OIDC standard for the `updated_at` token claim value. - -1. Deploy the action by dragging it from the Start to Complete step in the [Login Flow](https://auth0.com/docs/customize/actions/write-your-first-action#deploy-the-action). -{% endnavtab %} -{% endnavtabs %} - -## Configure SSO in {{site.konnect_short_name}} - -From the [{{site.konnect_short_name}} Dev Portal settings](https://cloud.konghq.com/portal/portal-settings), click the **Identity** tab and then click **Configure provider** for **OIDC**. Enter the values from your IdP application. - -This table maps the {{site.konnect_short_name}} values to the corresponding IdP values: - -| {{site.konnect_short_name}} value | Azure value | Okta value | Auth0 value | -| ----------- | ----------- | ----------- | ----------- | -| Provider URL | The value stored in the `issuer` variable. | The issuer URI for the authorization server. It should look something like this: `https://example.okta.com/oauth2/default` | Your Auth0 tenant's **Domain** with a leading `https://` and trailing slash `/`, e.g., `https://..auth0.com/` | -| Client ID | Your Azure application ID. | The **Client ID** in your Okta application. | Your Auth0 application's **Client ID** value. | -| Client Secret | Azure client secret.| The **Client Secret** in your Okta application. | Your Auth0 application's **Client Secret** value. | - -You can test your configuration by navigating to the Dev Portal and using your IdP credentials to log in. \ No newline at end of file +* [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) +* [IdP SAML attribute mapping reference](/konnect/reference/saml-idp-mappings/) \ No newline at end of file diff --git a/app/konnect/org-management/okta-idp.md b/app/konnect/org-management/okta-idp.md index 7dbe17307d4..dab81730956 100644 --- a/app/konnect/org-management/okta-idp.md +++ b/app/konnect/org-management/okta-idp.md @@ -8,353 +8,12 @@ As an alternative to {{site.konnect_saas}}’s native authentication, you can se You cannot mix authenticators in {{site.konnect_saas}}. With Okta authentication enabled, all non-admin {{site.konnect_short_name}} users will log in through Okta. Only the {{site.konnect_short_name}} org owner can continue to log in with {{site.konnect_short_name}}'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](/konnect/org-management/sso/) +This topic covers configuring Okta. For generic instructions on configuring SAML or OIDC for use with other identity providers, see the [generic SSO guide](/konnect/org-management/sso/). -## Prerequisites and overview of steps - -To set up Okta single sign-on (SSO) for {{site.konnect_short_name}}, you need access to an Okta admin account and a {{site.konnect_short_name}} 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 -{% navtabs %} -{% navtab OIDC %} -Create a new application in Okta to manage {{site.konnect_saas}} account integration. - -1. Sign in to your [Okta admin account](https://okta.com/login/). -1. In the sidebar, click **Applications > Applications**, then click **Create App Integration**. -1. Select the application type: - - 1. For the **Sign-in method**, select **OIDC - OpenID Connect**. - 1. For the **Application Type**, select **Web Application**. - 1. Click **Next**. - -1. Configure the application: - 1. In the **App integration name** box, enter a unique name for your application. - 1. For the **Grant type**, ensure the **Authorization Code** checkbox is selected. - 1. For both the **Sign-in redirect URIs** and - **Sign-out redirect URIs** boxes, enter: `https://cloud.konghq.com/login` - 1. In the **Assignments** pane, for **Controlled access**, choose your preferred access level for this application. - -1. Click **Save**. - - Leave this page open. You'll need the connection details here to configure your {{site.konnect_saas}} account. - -**Optionally** set up claims in Okta to have Okta send the correct information to your {{site.konnect_short_name}} org, set up claims to extract that information. - -1. Open your Okta account in a new browser tab. - -1. In the sidebar, select **Security > API**. - -1. Choose the authorization server you wish to configure. - -1. Click the **Claims** tab to configure the `groups` claim. - -1. Click **ID**, then click **Add Claim**. - -1. 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. - - {:.important} - > 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. - -1. Click **Create**. - -If you have problems setting up these claims, refer to the Okta documentation -for troubleshooting: -* [Adding a `groups` claim](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/add-groups-claim-custom-as/) -* [Adding a custom claim](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-custom-claim/) - -{% endnavtab %} -{% navtab SAML %} - -Create a new application in Okta to manage the {{site.konnect_saas}} account integration. - -1. Sign in to your [Okta admin account](https://okta.com/login/). -2. In the sidebar, click **Applications > Applications**, then click **Create App Integration**. -1. Select the application type: - - 1. For the **Sign-in method**, select **SAML 2.0**. - 1. Click **Next**. - -1. 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**. - 1. 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` - 1. 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 | - 1. Optional: In the **Group Attributes**, add the following attribute: - - | Name | Name format | Filter | Filter Value | - |---------|--------------|-----------------|--------------| - | groups | Unspecified | Matches regex | .* | - 1. Click **Next**. - 1. On the **Feedback** page, select **I’m an Okta customer adding an internal app** and click **Finish**. -{% endnavtab %} -{% endnavtabs %} - -## Add a user to your application -{% navtabs %} -{% navtab OIDC %} -1. In the sidebar of your Okta account, click **Applications > Applications**. - -1. Select the {{site.konnect_short_name}} application. - -1. Click the **Assignments** tab. - -1. Click **Assign > Assign to People**, and then click **Assign** next to the name of the users you want to add. - -1. Optional: In the dialog, enter additional information about the user. - -1. Click **Save and Go Back**. - -1. Click **Done**. - -Test claims and find mapping groups: - -1. In the sidebar of your Okta account, click **Security > API**. - -1. Select the authorization server that you want to configure. - -1. Click the **Token Preview** tab. - -1. Enter your client in the **OAuth/OIDC client** box. This is the name you created previously for your Okta application. - -1. In the **Grant Type** menu, select **Authorization Code**. - -1. In the **User** menu, select an Okta user that is assigned to the {{site.konnect_short_name}} application to test the claim with. - -1. In the **Scope** box, enter `openid`, `email`, and `profile`. - -1. Click **Preview Token**. - -1. In the generated preview, ensure that the `groups` -value is present. - -1. From the list of groups in the preview, identify groups that you want to use in -{{site.konnect_short_name}}. Take note of these groups. - -{% endnavtab %} -{% navtab SAML %} - -1. In the sidebar of your Okta account, click **Applications > Applications**. - -1. Select the {{site.konnect_short_name}} application. - -1. Click the **Assignments** tab. - -1. Click **Assign > Assign to People**, and then click **Assign** next to the name of the users you want to add. - -1. Optional: In the dialog, enter additional information about the user. - -1. Click **Save and Go Back**. - -1. Click **Done**. -{% endnavtab %} -{% endnavtabs %} - - -## Set up {{site.konnect_short_name}} - -### Provide Okta connection details -{% navtabs %} -{% navtab OIDC %} -1. In another separate browser tab, log in to [{{site.konnect_saas}}](https://cloud.konghq.com). -1. Click {% konnect_icon organizations %} **Organization** > **Settings**, then **Authentication Schemes**. -1. Click **Configure provider** for **OIDC**. - -1. In Okta, locate your issuer URI. - 1. Go to **Security** > **API**. - 1. 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} - > Note: Do not use the issuer URI from your application's settings. That - URI is incomplete: `https://example.okta.com`. - -1. Paste the issuer URI from Okta in the **Issuer URI** box in {{site.konnect_short_name}}. - -1. In Okta, copy your client ID and client secret by going to **Applications > Applications** and selecting your {{site.konnect_short_name}} application. - -1. Paste the **Client ID** and **Client Secret** from your Okta -application into {{site.konnect_saas}}. - - See the [Okta developer documentation](https://developer.okta.com/docs/guides/find-your-app-credentials/findcreds/) - to learn more about client credentials in Okta. - -1. In the **Organization Login Path** box, enter a unique string. For example: `examplepath`. - - {{site.konnect_short_name}} uses this string to generate a custom login - URL for your organization. - - Requirements: - * The path must be unique *across all {{site.konnect_short_name}} 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 (`/`). - -1. Click **Save**. -1. From the list of authentication providers, open the context menu and **Enable OIDC**. -{% endnavtab %} -{% navtab SAML %} -1. In another separate browser tab, log in to [{{site.konnect_saas}}](https://cloud.konghq.com). -1. Click {% konnect_icon organizations %} **Organization** > **Settings**, then **Authentication Schemes**. -1. Click **Configure provider** for **SAML**. - -1. 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://.okta.com/app/exkgzjkl0kUZB06Ky5d7/sso/saml/metadata - -1. In the **Login Path** box, enter a unique string. For example: `examplepath`. - - {{site.konnect_short_name}} uses this string to generate a custom login - URL for your organization. - - Requirements: - * The path must be unique *across all {{site.konnect_short_name}} 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 (`/`). - - -1. Click **Save**. -1. From the list of authentication providers, open the context menu and **Enable SAML**. -1. Close the configuration dialog and click **Enable** on your SAML provider. -1. In Okta update the placeholder **Single Sign-On URL** and **Audience URI (SP Entity ID)** that you set in the previous section. -1. Close the configuration dialog and click **Enable** on your SAML provider. - -{% endnavtab %} -{% endnavtabs %} - -### Map {{site.konnect_short_name}} teams to Okta groups - - -By mapping Okta groups to [{{site.konnect_short_name}} teams](/konnect/org-management/teams-and-roles/), -you can manage a user's {{site.konnect_short_name}} team membership directly through -Okta group membership. - -After mapping is set up: -* Okta users belonging to the mapped groups can log in to {{site.konnect_short_name}}. -* When a user logs into {{site.konnect_short_name}} with their Okta account -for the first time, -{{site.konnect_short_name}} automatically provisions an account with the -relevant roles. -* If your org already has non-admin {{site.konnect_short_name}} 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 -{{site.konnect_short_name}}, -but cannot edit their team membership from the {{site.konnect_short_name}} 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 -{{site.konnect_saas}}. For example: -* Removing a user from a group in Okta also deactivates their -{{site.konnect_short_name}} account. -* Moving a user from one group to another changes their team in {{site.konnect_short_name}} -to align with the new group-to-team mapping. - -1. Refer to the [token preview](#test-claims-and-find-groups-for-mapping) -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](#set-up-claims-in-okta) setup step for details. - -1. In {{site.konnect_saas}}, go to {% konnect_icon organizations %} **Organization > Auth Settings > Team Mappings** and do at least one of the following: - - * To manage user and team memberships in {{site.konnect_short_name}} 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 {{site.konnect_short_name}} teams, select the **IdP Mapping Enabled** checkbox and enter your Okta groups in the relevant fields. - - Each {{site.konnect_short_name}} 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 {{site.konnect_short_name}}. You can hover - over the info (`i`) icon beside each field to learn more about the team, or - see the [teams reference](/konnect/org-management/teams-and-roles/teams-reference/) - for more information. - - You must have at least one group mapped to save configuration changes. - -1. Click **Save**. - -## Test and apply the configuration {#test-the-integration} - -{:.important} -> **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 {{site.konnect_short_name}} organization's login URI. - -1. Paste the URI into a browser address bar. An Okta login page should appear. - -1. 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 {{site.konnect_saas}} account with the relevant team membership. - -1. 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} -> **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 {{site.konnect_saas}} as a dashboard app in Okta - -If you want your users to have easy access to {{site.konnect_saas}} alongside their other apps, -you can add it to your Okta dashboard. - -1. Log in to your [Okta admin account](https://okta.com/login/). -1. Click **Applications > Applications**, then select your {{site.konnect_saas}} Okta application. -1. On **General** tab, click **Edit** for the **General Settings** pane. -1. In the **Application** section, click the **Implicit (hybrid)** checkbox for the **Grant type**. -1. In the **Login** section: - 1. In the **Login Initiated by** menu, select **Either Okta or App**. - 1. For the **Application Visibility**, click the **Display application icon to users** checkbox. - 1. In the **Initiate login URI** box, enter your organization's login URI. You can - find the URI in {{site.konnect_saas}} by going to - **Settings** > **Identity Management**. -1. Click **Save**. +{% include_cached /md/konnect/okta-sso.md desc='Konnect Org' %} ## Okta reference docs * [Build an Okta SSO integration](https://developer.okta.com/docs/guides/build-sso-integration/openidconnect/overview/) * [Create claims in Okta](https://developer.okta.com/docs/guides/customize-authz-server/create-claims/) * [Groups claim](https://developer.okta.com/docs/guides/customize-tokens-groups-claim/add-groups-claim-custom-as/) -* [Custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-custom-claim/) +* [Custom claims](https://developer.okta.com/docs/guides/customize-tokens-returned-from-okta/add-custom-claim/) diff --git a/app/konnect/org-management/sso.md b/app/konnect/org-management/sso.md index 831e9b23f65..1cff082b65f 100644 --- a/app/konnect/org-management/sso.md +++ b/app/konnect/org-management/sso.md @@ -1,176 +1,41 @@ --- -title: Configure Generic SSO +title: Configure generic SSO for a Konnect Org --- -As an alternative to {{site.konnect_saas}}’s native authentication, you can set up single sign-on (SSO) access to {{site.konnect_short_name}} using OpenID Connect or SAML. This authentication method allows your users to log in to {{site.konnect_saas}} using their IdP credentials, without needing a separate login. This topic covers configuring SSO for use with various identity providers. +As an alternative to {{site.konnect_saas}}’s native authentication, you can set up single sign-on (SSO) access to {{site.konnect_short_name}} using OpenID Connect or SAML. This authentication method allows your users to log in to {{site.konnect_saas}} using their IdP credentials, without needing a separate login. This topic covers configuring SSO for use with various identity providers. -If you want to configure Okta, please see the [Okta configuration guide](/konnect/org-management/sso/). +If you want to configure Okta, please see the [Okta configuration guide](/konnect/org-management/okta-idp/). -## Prerequisites +## Map {{site.konnect_short_name}} teams to Okta groups -* {{site.konnect_short_name}} must be added to your IdP as an application -* Claims are set up in your IdP +Before you enable SSO, you have the option to map Okta groups to [{{site.konnect_short_name}} teams](/konnect/org-management/teams-and-roles/). By doing this, you can manage a user's {{site.konnect_short_name}} team membership directly through Okta group membership. +After mapping is set up: +* Okta users belonging to the mapped groups can log in to {{site.konnect_short_name}}. +* When a user logs into {{site.konnect_short_name}} with their Okta account +for the first time, +{{site.konnect_short_name}} automatically provisions an account with the +relevant roles. +* If your org already has non-admin {{site.konnect_short_name}} 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 +{{site.konnect_short_name}}, +but cannot edit their team membership from the {{site.konnect_short_name}} side. To +manage automatically-created users, adjust user permissions through Okta, or +adjust the team mapping. -## Set up SSO in {{site.konnect_short_name}} -{% navtabs %} -{% navtab OIDC%} -1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization**, and then **Auth Settings**. +Any changes to the mapped Okta groups on the Okta side are reflected in +{{site.konnect_saas}}. For example: +* Removing a user from a group in Okta also deactivates their +{{site.konnect_short_name}} account. +* Moving a user from one group to another changes their team in {{site.konnect_short_name}} +to align with the new group-to-team mapping. -1. Click **Configure provider** for **OIDC**. +{% include_cached /md/konnect/generic-sso.md desc='Konnect Org' %} -1. Paste the issuer URI from your IdP in the **Issuer URI** box. +## Related links -1. Paste the client ID from your IdP in the **Client ID** box. - -1. Paste the client secret from your IdP in the **Client Secret** box. - -1. In the **Organization Login Path** box, enter a unique string. For example: `examplepath`. - - {{site.konnect_short_name}} uses this string to generate a custom login - URL for your organization. - - Requirements: - * The path must be unique *across all {{site.konnect_short_name}} 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 (`/`). - -1. After clicking Save, close the configuration dialog and click Enable on your OIDC provider. -{% endnavtab %} -{% navtab SAML %} - -The {{site.konnect_short_name}} SAML integration allows you to configure various identity providers. While technically any SAML-compliant provider can be used, the following have been verified: - -* Okta -* Azure Active Directory -* Oracle Identity Cloud Service -* Keycloak - -1. Log in to {{site.konnect_saas}}, click {% konnect_icon organizations %} **Organization**, and then select **Auth Settings**. - -1. Click **Configure provider** under **SAML**. - -1. Enter the **Metadata URL** from your IdP in the **IDP Metadata URL** field. - -1. In the **Login Path** field, enter the unique string that matches the one in Okta. For example: `examplepath`. - - {{site.konnect_short_name}} uses this string to generate a custom login - URL for your organization. - - Requirements: - * The path must be unique across all {{site.konnect_short_name}} organizations. - * The path can be any alphanumeric string. - * The path does not require a slash (`/`). - -1. After clicking **Save**, configure the SP Entity ID and Login URL on your SAML IdP. -{% endnavtab %} -{% endnavtabs %} -## Test and apply the configuration -{% navtabs %} -{% navtab OIDC%} -{:.important} -> **Important:** Keep built-in authentication enabled while you are testing IdP authentication. Only disable built-in authentication after successfully testing IdP authentication. - -You can 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 steps above. - -If your configuration is set up correctly, you will see the IdP sign-in page. - -You can now manage your organization's user permissions entirely from the IdP -application. -{% endnavtab %} -{% navtab SAML %} -{:.important} -> **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. - -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. -{% endnavtab %} -{% endnavtabs %} - -## Reference - -### Provider specific SAML configuration - -The following section contains provider specific information and attribute mapping tables necessary for configuring SSO. -{% navtabs %} -{% navtab Azure %} -* When adding an enterprise application, note that OIDC uses app registration. -* Remove the namespace from the claim name in Azure. You can do this by checking **Customize** on the group claim. -* Using groups maps to the Group ID by default. - -Attribute mapping for Azure configuration: - -| Azure | Konnect | -|---------------------------------------------|--------------------------| -| Identifier (Entity ID) | `sp_entity_id` | -| Reply URL (Assertion Consumer Service URL) | `callback_url` | -| App Federation Metadata Url | `idp_metadata_url` | -| `user.email` | `email` | -| `user.givenname` | `firstname` | -| `user.surname` | `lastname` | -| `user.groups` | `groups` | -| `user.principalname` | Unique user identifier | - - -{% endnavtab %} -{% navtab Oracle Cloud %} - - -* When configuring the Name ID format in Oracle Cloud, make sure to set it to `transient`. -* You will need to manually upload the signing certificate from `sp_metadata_url`. - - `cert.pem` must use the `X509Certificate` value for signing. - -Attribute mapping for Oracle Cloud configuration: - -| Oracle Cloud | Konnect | -|---------------------------------------------|--------------------------| -| Entity ID | `sp_entity_id` | -| Assertion consumer URL | `callback_url` | -| App Federation Metadata Url | `idp_metadata_url` | - - - - - -{% endnavtab %} -{% navtab KeyCloak %} - -* You will need to manually upload the signing certificate from `sp_metadata_url`. - - `cert.pem` must use the `X509Certificate` value for signing. -* Go to **Realm Settings** in Keycloak to locate your metadata endpoint. The `sp_metadata_url` for {{site.konnect_short_name}} will be:`http:///realms/konnect/protocol/saml/descriptor` - -Attribute mapping for KeyCloak configuration: - -| KeyCloak | Konnect | -|---------------------------------------------|--------------------------| -| Client ID | `sp_entity_id` | -| Valid redirect URI | `callback_url` | -| App Federation Metadata Url | `idp_metadata_url` | - -{% endnavtab %} -{% endnavtabs %} - - -### Advanced OIDC settings - -You can configure custom IdP-specific behaviors in the **Advanced Settings** of the OIDC configuration form. The following options are available: - -1. **Scopes**: Specify the list of scopes {{site.konnect_short_name}} requests from the IdP. By default, {{site.konnect_short_name}} requests the `openid`, `email`, and `profile` scopes. The `openid` scope is required and cannot be removed. -2. **Claim Mappings**: Customize the mapping of required attributes to a different claim in the `id_token` {{site.konnect_short_name}} receives from the IdP. By default, {{site.konnect_short_name}} requires three attributes: Name, Email, and Groups. The values in these attributes are mapped as follows: - - `name`: Used as the {{site.konnect_short_name}} account's `full_name`. - - `email`: Used as the {{site.konnect_short_name}} account's `email`. - - `groups`: Used to map users to teams defined in the team mappings upon login. - -### Authentication issues with large numbers of groups - -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: -* [Azure group filtering](https://learn.microsoft.com/en-us/azure/active-directory/hybrid/connect/how-to-connect-fed-group-claims#group-filtering) -* [Okta group filtering](https://support.okta.com/help/s/article/How-to-send-certain-groups-that-the-user-is-assigned-to-in-one-Group-attribute-statement) - -You may need to contact the support team of your identity provider in order to learn how to filter groups emitted for the application. +* [Configure generic SSO for Dev Portal](/konnect/dev-portal/access-and-approval/sso/) +* [IdP SAML attribute mapping reference](/konnect/reference/saml-idp-mappings/): Learn how Azure, Oracle Cloud, and KeyCloak attributes map to {{site.konnect_short_name}}. \ No newline at end of file diff --git a/app/konnect/reference/saml-idp-mappings.md b/app/konnect/reference/saml-idp-mappings.md new file mode 100644 index 00000000000..cbff56857e1 --- /dev/null +++ b/app/konnect/reference/saml-idp-mappings.md @@ -0,0 +1,62 @@ +--- +title: IdP SAML attribute mapping reference +--- + +This reference doc contains provider specific information and attribute mapping tables necessary for configuring SSO with SAML. + +{% navtabs %} +{% navtab Azure %} +* When adding an enterprise application, note that OIDC uses app registration. +* Remove the namespace from the claim name in Azure. You can do this by checking **Customize** on the group claim. +* Using groups maps to the Group ID by default. + +Attribute mapping for Azure configuration: + +| Azure | Konnect | +|---------------------------------------------|--------------------------| +| Identifier (Entity ID) | `sp_entity_id` | +| Reply URL (Assertion Consumer Service URL) | `callback_url` | +| App Federation Metadata Url | `idp_metadata_url` | +| `user.email` | `email` | +| `user.givenname` | `firstname` | +| `user.surname` | `lastname` | +| `user.groups` | `groups` | +| `user.principalname` | Unique user identifier | + +{% endnavtab %} +{% navtab Oracle Cloud %} + +* When configuring the Name ID format in Oracle Cloud, make sure to set it to `transient`. +* You will need to manually upload the signing certificate from `sp_metadata_url`. + - `cert.pem` must use the `X509Certificate` value for signing. + +Attribute mapping for Oracle Cloud configuration: + +| Oracle Cloud | Konnect | +|---------------------------------------------|--------------------------| +| Entity ID | `sp_entity_id` | +| Assertion consumer URL | `callback_url` | +| App Federation Metadata Url | `idp_metadata_url` | + +{% endnavtab %} +{% navtab KeyCloak %} + +* You will need to manually upload the signing certificate from `sp_metadata_url`. + - `cert.pem` must use the `X509Certificate` value for signing. +* Go to **Realm Settings** in Keycloak to locate your metadata endpoint. The `sp_metadata_url` for {{site.konnect_short_name}} will be:`http:///realms/konnect/protocol/saml/descriptor` + +Attribute mapping for KeyCloak configuration: + +| KeyCloak | Konnect | +|---------------------------------------------|--------------------------| +| Client ID | `sp_entity_id` | +| Valid redirect URI | `callback_url` | +| App Federation Metadata Url | `idp_metadata_url` | + +{% endnavtab %} +{% endnavtabs %} + +## Related links + +* [Configure generic SSO for a {{site.konnect_short_name}} org](/konnect/org-management/sso/) +* [Configure generic SSO for a Dev Portal](/konnect/dev-portal/access-and-approval/sso/) \ No newline at end of file