From 5bbc1de47d9684f54bdb44cbd319beeca40ea835 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Mon, 4 Nov 2024 15:56:32 -0600 Subject: [PATCH 01/10] Create includes for generic SSO, okta SSO Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_data/docs_nav_konnect.yml | 8 +- app/_includes/md/konnect/generic-sso.md | 119 ++++++++++++ app/_includes/md/konnect/okta-sso.md | 80 ++++++++ .../access-and-approval/okta-idp.md | 12 ++ .../dev-portal/access-and-approval/sso.md | 17 +- app/konnect/org-management/okta-idp.md | 167 +---------------- app/konnect/org-management/sso.md | 175 +----------------- app/konnect/reference/sso.md | 62 +++++++ 8 files changed, 304 insertions(+), 336 deletions(-) create mode 100644 app/_includes/md/konnect/generic-sso.md create mode 100644 app/_includes/md/konnect/okta-sso.md create mode 100644 app/konnect/dev-portal/access-and-approval/okta-idp.md create mode 100644 app/konnect/reference/sso.md diff --git a/app/_data/docs_nav_konnect.yml b/app/_data/docs_nav_konnect.yml index f41d96732e71..4d030fea1b23 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: /org-management/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 SSO attribute mapping + url: /reference/sso/ diff --git a/app/_includes/md/konnect/generic-sso.md b/app/_includes/md/konnect/generic-sso.md new file mode 100644 index 000000000000..237532e15416 --- /dev/null +++ b/app/_includes/md/konnect/generic-sso.md @@ -0,0 +1,119 @@ + + +## 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%} +{% if include.desc == "Konnect Org" %} +1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization**, and then **Auth Settings**. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 provider** for **OIDC**. + +1. Paste the issuer URI from your IdP in the **Issuer URI** box. + +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. + +{% if include.desc == "Konnect Org" %} +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 (`/`). +{% 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. + +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 + +{% if include.desc == "Konnect Org" %} +1. Log in to {{site.konnect_saas}}, click {% konnect_icon organizations %} **Organization**, and then select **Auth Settings**. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 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 your IdP. 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 + +{:.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://9963d2bcc58e.us.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 000000000000..1069718c6318 --- /dev/null +++ b/app/_includes/md/konnect/okta-sso.md @@ -0,0 +1,80 @@ + +## Prerequisites + +* Ensure that any users that need to use the Dev Portal SSO have been added to your IdP tenant +* 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` + * **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 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: 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: 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: + + | Name | Name format | Filter | Filter Value | + |---------|--------------|-----------------|--------------| + | groups | Unspecified | Matches regex | .* | + +1. Select **I'm an Okta customer adding an internal app**. + +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 %} \ 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 000000000000..09db7392933d --- /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/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 5741a79814da..9c3aa6038a15 100644 --- a/app/konnect/dev-portal/access-and-approval/sso.md +++ b/app/konnect/dev-portal/access-and-approval/sso.md @@ -1,8 +1,20 @@ --- -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 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/okta-idp/). + +{% include_cached /md/konnect/generic-sso.md desc='Dev Portal' %} + +## Related links + +* [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) +* [IdP SSO attribute mapping reference](/konnect/reference/sso) + + \ 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 7dbe17307d46..ea1609683f11 100644 --- a/app/konnect/org-management/okta-idp.md +++ b/app/konnect/org-management/okta-idp.md @@ -8,170 +8,9 @@ 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/) - -## 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 %} +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/). +{% include_cached /md/konnect/okta-sso.md desc='Konnect Org' %} ## Set up {{site.konnect_short_name}} @@ -357,4 +196,4 @@ you can add it to your Okta dashboard. * [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 831e9b23f658..c47b5a614838 100644 --- a/app/konnect/org-management/sso.md +++ b/app/konnect/org-management/sso.md @@ -1,176 +1,15 @@ --- -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 +{% include_cached /md/konnect/generic-sso.md desc='Konnect Org' %} -* {{site.konnect_short_name}} must be added to your IdP as an application -* Claims are set up in your IdP +## Related links - -## 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**. - -1. Click **Configure provider** for **OIDC**. - -1. Paste the issuer URI from your IdP in the **Issuer URI** box. - -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/sso/) +* [IdP SSO attribute mapping reference](/konnect/reference/sso) \ No newline at end of file diff --git a/app/konnect/reference/sso.md b/app/konnect/reference/sso.md new file mode 100644 index 000000000000..38d54ac95410 --- /dev/null +++ b/app/konnect/reference/sso.md @@ -0,0 +1,62 @@ +--- +title: IdP SSO attribute mapping reference +--- + +This reference doc 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 %} + +## Related links + +* [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) +* [Configure generic SSO for Dev Portal](/konnect/dev-portal/sso/) \ No newline at end of file From 9c6891af75fb4e70db86663b81149585610eb675 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 5 Nov 2024 11:14:58 -0600 Subject: [PATCH 02/10] Update Okta SSO include with more feature rendering Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/md/konnect/okta-sso.md | 161 +++++++++++++++++++++- app/konnect/org-management/okta-idp.md | 180 ------------------------- 2 files changed, 160 insertions(+), 181 deletions(-) diff --git a/app/_includes/md/konnect/okta-sso.md b/app/_includes/md/konnect/okta-sso.md index 1069718c6318..0790af2cc27d 100644 --- a/app/_includes/md/konnect/okta-sso.md +++ b/app/_includes/md/konnect/okta-sso.md @@ -77,4 +77,163 @@ Optionally, if you want to use team mappings, you must configure Okta to include 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 %} \ No newline at end of file +{% 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**, and then **Auth Settings**. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In a separate browser tab, open [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 provider** for **OIDC**. + +1. In Okta, locate your issuer URI. The issuer URI varies depending on if you're using an [org authorization server](https://developer.okta.com/docs/concepts/auth-servers/#org-authorization-server) or a [custom authorization server](https://developer.okta.com/docs/concepts/auth-servers/#custom-authorization-server) + * Org authorization server issuer URI example: `https://{yourOktaOrg}` + * Custom authorization server issuer URI example: `https://example.okta.com/oauth2/default` + +1. Paste the issuer URI from Okta in the **Provider URI** 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. 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 (`/`). +{% endif %} +1. Click **Save**. +1. From the list of authentication providers, open the context menu and **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**, and then **Auth Settings**. +{% endif %} +{% if include.desc == "Dev Portal" %} +1. In a separate browser tab, open [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 provider** 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. For example: `examplepath`. + + {{site.konnect_short_name}} Dev Portal uses this string to generate a custom login + URL for your Dev Portal. + + 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. 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)** 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. Close the configuration dialog and click **Enable** on your SAML provider. + +{% endnavtab %} +{% endnavtabs %} + +{% if include.desc == "Dev Portal" %} +### Map {{site.konnect_short_name}} Dev Portal teams to Okta groups + +In the {{site.konnect_short_name}} Dev Portal, you can map existing developer teams from a third-party identity provider (IdP) and their permissions to elements in {{site.konnect_short_name}}. With teams mapped from an IdP, the developers and permissions are mapped automatically in {{site.konnect_short_name}} so you don’t have to manually copy over each team of developers. For more information about how to configure this, see [Add Developer Teams from Identity Providers](/konnect/dev-portal/access-and-approval/add-teams/). +{% endif %} +{% if include.desc == "Konnect Org" %} +### 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**. +{% 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. + +1. Test the SSO configuration by navigating to the callback URL for your Dev Portal. For example: `https://9963d2bcc58e.us.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/portal/), 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. + +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/org-management/okta-idp.md b/app/konnect/org-management/okta-idp.md index ea1609683f11..dab81730956b 100644 --- a/app/konnect/org-management/okta-idp.md +++ b/app/konnect/org-management/okta-idp.md @@ -12,186 +12,6 @@ This topic covers configuring Okta. For generic instructions on configuring SAML {% include_cached /md/konnect/okta-sso.md desc='Konnect Org' %} -## 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**. - ## 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/) From 445c7b2f0a63f0d3a0e38d8ad09457199c048bb9 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 5 Nov 2024 11:22:43 -0600 Subject: [PATCH 03/10] Remove old content from generic SSO for Dev Portal, not going to use it since it was generic anyways Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- .../dev-portal/access-and-approval/sso.md | 130 +----------------- app/konnect/reference/sso.md | 3 + 2 files changed, 8 insertions(+), 125 deletions(-) diff --git a/app/konnect/dev-portal/access-and-approval/sso.md b/app/konnect/dev-portal/access-and-approval/sso.md index 9c3aa6038a15..9d98f4401564 100644 --- a/app/konnect/dev-portal/access-and-approval/sso.md +++ b/app/konnect/dev-portal/access-and-approval/sso.md @@ -3,19 +3,7 @@ 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 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/okta-idp/). - -{% include_cached /md/konnect/generic-sso.md desc='Dev Portal' %} - -## Related links - -* [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) -* [IdP SSO attribute mapping reference](/konnect/reference/sso) - - \ No newline at end of file +* [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) +* [IdP SSO attribute mapping reference](/konnect/reference/sso) \ No newline at end of file diff --git a/app/konnect/reference/sso.md b/app/konnect/reference/sso.md index 38d54ac95410..85623aed27e3 100644 --- a/app/konnect/reference/sso.md +++ b/app/konnect/reference/sso.md @@ -53,6 +53,9 @@ Attribute mapping for KeyCloak configuration: | Valid redirect URI | `callback_url` | | App Federation Metadata Url | `idp_metadata_url` | +{% endnavtab %} +{% navtab Auth0 %} + {% endnavtab %} {% endnavtabs %} From 91b061400bbad5db27d94a47cc795f0e0ef2f979 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 5 Nov 2024 11:37:08 -0600 Subject: [PATCH 04/10] Fix broken links Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/konnect/dev-portal/access-and-approval/okta-idp.md | 2 +- app/konnect/dev-portal/access-and-approval/sso.md | 2 +- app/konnect/org-management/sso.md | 2 +- app/konnect/reference/sso.md | 2 +- 4 files changed, 4 insertions(+), 4 deletions(-) diff --git a/app/konnect/dev-portal/access-and-approval/okta-idp.md b/app/konnect/dev-portal/access-and-approval/okta-idp.md index 09db7392933d..389b04b13366 100644 --- a/app/konnect/dev-portal/access-and-approval/okta-idp.md +++ b/app/konnect/dev-portal/access-and-approval/okta-idp.md @@ -7,6 +7,6 @@ You can set up single sign-on (SSO) access to Dev Portals through Okta using Ope 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/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/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 9d98f4401564..061a5ce657f4 100644 --- a/app/konnect/dev-portal/access-and-approval/sso.md +++ b/app/konnect/dev-portal/access-and-approval/sso.md @@ -3,7 +3,7 @@ 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 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/okta-idp/). +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: diff --git a/app/konnect/org-management/sso.md b/app/konnect/org-management/sso.md index c47b5a614838..19912b34f9e5 100644 --- a/app/konnect/org-management/sso.md +++ b/app/konnect/org-management/sso.md @@ -11,5 +11,5 @@ If you want to configure Okta, please see the [Okta configuration guide](/konnec ## Related links -* [Configure generic SSO for Dev Portal](/konnect/dev-portal/sso/) +* [Configure generic SSO for Dev Portal](/konnect/dev-portal/access-and-approval/sso/) * [IdP SSO attribute mapping reference](/konnect/reference/sso) \ No newline at end of file diff --git a/app/konnect/reference/sso.md b/app/konnect/reference/sso.md index 85623aed27e3..3ff89a03a7d3 100644 --- a/app/konnect/reference/sso.md +++ b/app/konnect/reference/sso.md @@ -62,4 +62,4 @@ Attribute mapping for KeyCloak configuration: ## Related links * [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) -* [Configure generic SSO for Dev Portal](/konnect/dev-portal/sso/) \ No newline at end of file +* [Configure generic SSO for Dev Portal](/konnect/dev-portal/access-and-approval/sso/) \ No newline at end of file From 806bd67e351d98411f6a11970461b9acbe7220be Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 5 Nov 2024 14:28:32 -0600 Subject: [PATCH 05/10] Make changes after testing portal OIDC, org OIDC, and org SAML Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/md/konnect/generic-sso.md | 4 +- app/_includes/md/konnect/okta-sso.md | 83 +++++++++++++------------ 2 files changed, 45 insertions(+), 42 deletions(-) diff --git a/app/_includes/md/konnect/generic-sso.md b/app/_includes/md/konnect/generic-sso.md index 237532e15416..7ef3a34c52a2 100644 --- a/app/_includes/md/konnect/generic-sso.md +++ b/app/_includes/md/konnect/generic-sso.md @@ -11,7 +11,7 @@ {% navtabs %} {% navtab OIDC%} {% if include.desc == "Konnect Org" %} -1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization**, and then **Auth Settings**. +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/portal/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. @@ -57,7 +57,7 @@ The {{site.konnect_short_name}} SAML integration allows you to configure various * Keycloak {% if include.desc == "Konnect Org" %} -1. Log in to {{site.konnect_saas}}, click {% konnect_icon organizations %} **Organization**, and then select **Auth Settings**. +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/portal/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. diff --git a/app/_includes/md/konnect/okta-sso.md b/app/_includes/md/konnect/okta-sso.md index 0790af2cc27d..7fcab902e1ae 100644 --- a/app/_includes/md/konnect/okta-sso.md +++ b/app/_includes/md/konnect/okta-sso.md @@ -15,22 +15,19 @@ Optionally, if you want to use team mappings, you must configure Okta to include * **Grant type**: Authorization Code * **Sign-in redirect URIs**: `https://cloud.konghq.com/login` * **Sign-out redirect URIs**: `https://cloud.konghq.com/login` + * **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. -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: +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 - ---|--- - 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`. + | Field | Value | + | ---|--- | + | Group claims type | Filter | + | Group claims filter | `groups`, select **Matches regex** from the drop-down, then enter `.*` in the field. - 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. +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 @@ -41,14 +38,6 @@ Optionally, if you want to use team mappings, you must configure Okta to include 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 SAML %} @@ -58,19 +47,17 @@ Optionally, if you want to use team mappings, you must configure Okta to include 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 | + | Name | Name format | Value | + |------------|--------------|----------------| + | `firstName` | Unspecified | user.firstName | + | `lastName` | Unspecified | user.lastName | + | `email` | Unspecified | user.email | 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: - | Name | Name format | Filter | Filter Value | - |---------|--------------|-----------------|--------------| - | groups | Unspecified | Matches regex | .* | - -1. Select **I'm an Okta customer adding an internal app**. + | Name | Name format | Filter | Filter Value | + |---------|--------------|-----------------|--------------| + | groups | Unspecified | Matches regex | .* | 1. [Add users to the Okta application](https://help.okta.com/en-us/content/topics/users-groups-profiles/usgp-assign-apps.htm). @@ -85,18 +72,19 @@ Optionally, if you want to use team mappings, you must configure Okta to include {% navtabs %} {% navtab OIDC %} {% if include.desc == "Konnect Org" %} -1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization**, and then **Auth Settings**. +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/portal/), 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 provider** for **OIDC**. -1. In Okta, locate your issuer URI. The issuer URI varies depending on if you're using an [org authorization server](https://developer.okta.com/docs/concepts/auth-servers/#org-authorization-server) or a [custom authorization server](https://developer.okta.com/docs/concepts/auth-servers/#custom-authorization-server) - * Org authorization server issuer URI example: `https://{yourOktaOrg}` - * Custom authorization server issuer URI example: `https://example.okta.com/oauth2/default` +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 URI** field in {{site.konnect_short_name}}. +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. @@ -122,7 +110,7 @@ application into {{site.konnect_saas}}. {% endnavtab %} {% navtab SAML %} {% if include.desc == "Konnect Org" %} -1. In [{{site.konnect_saas}}](https://cloud.konghq.com/login), click {% konnect_icon organizations %} **Organization**, and then **Auth Settings**. +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/portal/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. @@ -143,10 +131,9 @@ application into {{site.konnect_saas}}. * The path does not require a slash (`/`). {% endif %} 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. 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 {% if include.desc == "Dev Portal" %}Dev Portal callback URL{% endif %}{% if include.desc == "Konnect Org" %}{{site.konnect_short_name}} login URI{% endif %}. -1. Close the configuration dialog and click **Enable** on your SAML provider. +1. Close the configuration dialog and click **Enable SAML** from the context menu. {% endnavtab %} {% endnavtabs %} @@ -157,7 +144,7 @@ application into {{site.konnect_saas}}. In the {{site.konnect_short_name}} Dev Portal, you can map existing developer teams from a third-party identity provider (IdP) and their permissions to elements in {{site.konnect_short_name}}. With teams mapped from an IdP, the developers and permissions are mapped automatically in {{site.konnect_short_name}} so you don’t have to manually copy over each team of developers. For more information about how to configure this, see [Add Developer Teams from Identity Providers](/konnect/dev-portal/access-and-approval/add-teams/). {% endif %} {% if include.desc == "Konnect Org" %} -### Map {{site.konnect_short_name}} teams to Okta groups +### (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 @@ -185,6 +172,16 @@ Any changes to the mapped Okta groups on the Okta side are reflected in * 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. @@ -193,7 +190,7 @@ in Okta to locate the Okta groups you want to map. 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: +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. @@ -216,6 +213,7 @@ in Okta to locate the Okta groups you want to map. {:.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://9963d2bcc58e.us.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 @@ -223,6 +221,10 @@ 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/portal/), 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. @@ -231,6 +233,7 @@ You can now manage your organization's user permissions entirely from the IdP ap 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) | From dde09f87c96e25cad5539bb97af4ca627eebc319 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 5 Nov 2024 14:30:08 -0600 Subject: [PATCH 06/10] Fix wrong link in nav file Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_data/docs_nav_konnect.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/app/_data/docs_nav_konnect.yml b/app/_data/docs_nav_konnect.yml index 4d030fea1b23..8299784fb0ef 100644 --- a/app/_data/docs_nav_konnect.yml +++ b/app/_data/docs_nav_konnect.yml @@ -186,7 +186,7 @@ - text: Configure generic SSO for Dev Portal url: /dev-portal/access-and-approval/sso/ - text: Configure Okta SSO - url: /org-management/okta-idp/ + 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 From b0a5c78929edd65a21541448261983060415a975 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Tue, 5 Nov 2024 15:35:37 -0600 Subject: [PATCH 07/10] Small updates to feature rendering Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/md/konnect/okta-sso.md | 10 +++++++--- 1 file changed, 7 insertions(+), 3 deletions(-) diff --git a/app/_includes/md/konnect/okta-sso.md b/app/_includes/md/konnect/okta-sso.md index 7fcab902e1ae..fb7fd6994783 100644 --- a/app/_includes/md/konnect/okta-sso.md +++ b/app/_includes/md/konnect/okta-sso.md @@ -1,7 +1,8 @@ ## Prerequisites - +{% if include.desc == "Dev Portal" %} * Ensure that any users that need to use the Dev Portal SSO have been added to your IdP tenant +{% 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. @@ -19,15 +20,17 @@ Optionally, if you want to use team mappings, you must configure Okta to include 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. + 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 @@ -173,6 +176,7 @@ Any changes to the mapped Okta groups on the Okta side are reflected in 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: From 71ddf6674212341e4cdfeddfee4eb2956e69c63e Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 6 Nov 2024 12:56:51 -0600 Subject: [PATCH 08/10] Apply revisions from format and grammar review Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/md/konnect/generic-sso.md | 17 ++++++++------ app/_includes/md/konnect/okta-sso.md | 30 +++++++++++++++---------- app/konnect/org-management/sso.md | 2 +- app/konnect/reference/sso.md | 7 ++---- 4 files changed, 31 insertions(+), 25 deletions(-) diff --git a/app/_includes/md/konnect/generic-sso.md b/app/_includes/md/konnect/generic-sso.md index 7ef3a34c52a2..7439b3f78c65 100644 --- a/app/_includes/md/konnect/generic-sso.md +++ b/app/_includes/md/konnect/generic-sso.md @@ -17,13 +17,13 @@ 1. In [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 provider** for **OIDC**. +1. Click **Configure** for OIDC. -1. Paste the issuer URI from your IdP in the **Issuer URI** box. +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** box. +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** box. +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. For example: `examplepath`. @@ -45,7 +45,7 @@ * `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. -1. After clicking **Save**, close the configuration dialog and click **Enable on your OIDC provider**. +1. After clicking **Save**, close the configuration dialog and from the OIDC context menu, click **Enable OIDC**. {% endnavtab %} {% navtab SAML %} @@ -63,10 +63,11 @@ The {{site.konnect_short_name}} SAML integration allows you to configure various 1. In [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 provider** under **SAML**. +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 the unique string that matches the one in your IdP. For example: `examplepath`. {{site.konnect_short_name}} uses this string to generate a custom login @@ -76,8 +77,10 @@ The {{site.konnect_short_name}} SAML integration allows you to configure various * 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. +1. In {{site.konnect_short_name}}, close the configuration dialog and click **Enable SAML** from the context menu. {% endnavtab %} {% endnavtabs %} @@ -91,7 +94,7 @@ Test the SSO configuration by navigating to the login URI based on the organizat {% endif %} {% if include.desc == "Dev Portal" %} -Test the SSO configuration by navigating to the callback URL for your Dev Portal. For example: `https://9963d2bcc58e.us.portal.konghq.com/login`. +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. diff --git a/app/_includes/md/konnect/okta-sso.md b/app/_includes/md/konnect/okta-sso.md index fb7fd6994783..2d227e8bdcc5 100644 --- a/app/_includes/md/konnect/okta-sso.md +++ b/app/_includes/md/konnect/okta-sso.md @@ -1,11 +1,13 @@ ## Prerequisites {% if include.desc == "Dev Portal" %} -* Ensure that any users that need to use the Dev Portal SSO have been added to your IdP tenant +* 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. +* Optionally, if you want to use team mappings, you must configure Okta to include group attributes. ## Configure an application and group claims in Okta @@ -14,8 +16,8 @@ Optionally, if you want to use team mappings, you must configure Okta to include 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` + * **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. @@ -56,11 +58,13 @@ Optionally, if you want to use team mappings, you must configure Okta to include | `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/), 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: | 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). @@ -81,7 +85,7 @@ Optionally, if you want to use team mappings, you must configure Okta to include 1. In a separate browser tab, open [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 provider** for **OIDC**. +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 %}. @@ -108,8 +112,7 @@ application into {{site.konnect_saas}}. * The path can be any alphanumeric string. * The path does not require a slash (`/`). {% endif %} -1. Click **Save**. -1. From the list of authentication providers, open the context menu and **Enable OIDC**. +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" %} @@ -118,7 +121,7 @@ application into {{site.konnect_saas}}. {% if include.desc == "Dev Portal" %} 1. In a separate browser tab, open [{{site.konnect_short_name}} Dev Portal](https://cloud.konghq.com/portal/), 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 provider** for **SAML**. +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" %} @@ -136,13 +139,13 @@ application into {{site.konnect_saas}}. 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 {% if include.desc == "Dev Portal" %}Dev Portal callback URL{% endif %}{% if include.desc == "Konnect Org" %}{{site.konnect_short_name}} login URI{% endif %}. -1. Close the configuration dialog and click **Enable SAML** from the context menu. +1. In {{site.konnect_short_name}}, close the configuration dialog and click **Enable SAML** from the context menu. {% endnavtab %} {% endnavtabs %} {% if include.desc == "Dev Portal" %} -### Map {{site.konnect_short_name}} Dev Portal teams to Okta groups +### (Optional) Map {{site.konnect_short_name}} Dev Portal teams to Okta groups In the {{site.konnect_short_name}} Dev Portal, you can map existing developer teams from a third-party identity provider (IdP) and their permissions to elements in {{site.konnect_short_name}}. With teams mapped from an IdP, the developers and permissions are mapped automatically in {{site.konnect_short_name}} so you don’t have to manually copy over each team of developers. For more information about how to configure this, see [Add Developer Teams from Identity Providers](/konnect/dev-portal/access-and-approval/add-teams/). {% endif %} @@ -218,12 +221,15 @@ in Okta to locate the Okta groups you want to map. > **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://9963d2bcc58e.us.portal.konghq.com/login`. +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/portal/), 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" %} diff --git a/app/konnect/org-management/sso.md b/app/konnect/org-management/sso.md index 19912b34f9e5..6cecaa53a702 100644 --- a/app/konnect/org-management/sso.md +++ b/app/konnect/org-management/sso.md @@ -12,4 +12,4 @@ If you want to configure Okta, please see the [Okta configuration guide](/konnec ## Related links * [Configure generic SSO for Dev Portal](/konnect/dev-portal/access-and-approval/sso/) -* [IdP SSO attribute mapping reference](/konnect/reference/sso) \ No newline at end of file +* [IdP SSO attribute mapping reference](/konnect/reference/sso): 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/sso.md b/app/konnect/reference/sso.md index 3ff89a03a7d3..830c7a513fff 100644 --- a/app/konnect/reference/sso.md +++ b/app/konnect/reference/sso.md @@ -53,13 +53,10 @@ Attribute mapping for KeyCloak configuration: | Valid redirect URI | `callback_url` | | App Federation Metadata Url | `idp_metadata_url` | -{% endnavtab %} -{% navtab Auth0 %} - {% endnavtab %} {% endnavtabs %} ## Related links -* [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) -* [Configure generic SSO for Dev Portal](/konnect/dev-portal/access-and-approval/sso/) \ No newline at end of file +* [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 From 1c1ff410973cb49cea9732f17ab1d57bd6eba2c9 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Wed, 6 Nov 2024 15:39:13 -0600 Subject: [PATCH 09/10] Small fixes after testing Dev Portal SAML Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_includes/md/konnect/generic-sso.md | 4 ++-- app/_includes/md/konnect/okta-sso.md | 10 +++++----- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/app/_includes/md/konnect/generic-sso.md b/app/_includes/md/konnect/generic-sso.md index 7439b3f78c65..0d5373c32e20 100644 --- a/app/_includes/md/konnect/generic-sso.md +++ b/app/_includes/md/konnect/generic-sso.md @@ -14,7 +14,7 @@ 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/portal/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +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. @@ -60,7 +60,7 @@ The {{site.konnect_short_name}} SAML integration allows you to configure various 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/portal/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +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. diff --git a/app/_includes/md/konnect/okta-sso.md b/app/_includes/md/konnect/okta-sso.md index 2d227e8bdcc5..97098d017762 100644 --- a/app/_includes/md/konnect/okta-sso.md +++ b/app/_includes/md/konnect/okta-sso.md @@ -59,7 +59,7 @@ | `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/), 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: +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 | |---------|--------------|-----------------|--------------| @@ -82,7 +82,7 @@ 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/portal/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +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. @@ -119,7 +119,7 @@ application into {{site.konnect_saas}}. 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/portal/), click the Dev Portal you want to configure SSO for, click **Settings** in the sidebar and then click the **Identity** tab. +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. @@ -138,7 +138,7 @@ application into {{site.konnect_saas}}. {% 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 {% 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, 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 %}. 1. In {{site.konnect_short_name}}, close the configuration dialog and click **Enable SAML** from the context menu. {% endnavtab %} @@ -228,7 +228,7 @@ in Okta to locate the Okta groups you want to map. 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/portal/), click the Dev Portal you configured SSO for and click **Developers** in the sidebar. +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 %} From 95104cedb123563d461776f9fc4f40d6b1e45d10 Mon Sep 17 00:00:00 2001 From: Diana <75819066+cloudjumpercat@users.noreply.github.com> Date: Fri, 8 Nov 2024 15:09:03 -0600 Subject: [PATCH 10/10] Apply SME feedback Signed-off-by: Diana <75819066+cloudjumpercat@users.noreply.github.com> --- app/_data/docs_nav_konnect.yml | 4 +- app/_includes/md/konnect/generic-sso.md | 62 ++++++++++++++++--- app/_includes/md/konnect/okta-sso.md | 24 +++---- .../dev-portal/access-and-approval/sso.md | 2 +- app/konnect/org-management/sso.md | 28 ++++++++- .../{sso.md => saml-idp-mappings.md} | 4 +- 6 files changed, 95 insertions(+), 29 deletions(-) rename app/konnect/reference/{sso.md => saml-idp-mappings.md} (96%) diff --git a/app/_data/docs_nav_konnect.yml b/app/_data/docs_nav_konnect.yml index 8299784fb0ef..05daaba04b56 100644 --- a/app/_data/docs_nav_konnect.yml +++ b/app/_data/docs_nav_konnect.yml @@ -427,5 +427,5 @@ url: /reference/audit-logs/ - text: Verify audit log signatures url: /reference/verify-signatures/ - - text: IdP SSO attribute mapping - url: /reference/sso/ + - 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 index 0d5373c32e20..247c9ea37f65 100644 --- a/app/_includes/md/konnect/generic-sso.md +++ b/app/_includes/md/konnect/generic-sso.md @@ -10,6 +10,13 @@ ## 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 %} @@ -26,10 +33,7 @@ 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. For example: `examplepath`. - - {{site.konnect_short_name}} uses this string to generate a custom login - URL for your organization. +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*. @@ -44,7 +48,29 @@ * `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 %} @@ -68,10 +94,7 @@ The {{site.konnect_short_name}} SAML integration allows you to configure various 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 the unique string that matches the one in your IdP. For example: `examplepath`. - - {{site.konnect_short_name}} uses this string to generate a custom login - URL for your organization. +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. @@ -80,6 +103,29 @@ The {{site.konnect_short_name}} SAML integration allows you to configure various {% 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 %} diff --git a/app/_includes/md/konnect/okta-sso.md b/app/_includes/md/konnect/okta-sso.md index 97098d017762..701e56049f3b 100644 --- a/app/_includes/md/konnect/okta-sso.md +++ b/app/_includes/md/konnect/okta-sso.md @@ -50,7 +50,7 @@ * **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: In the **Attribute Statements**, add the following three attributes: +1. Optional: To include additional user attributes beyond authentication, add the following three attributes in the **Attribute Statements**: | Name | Name format | Value | |------------|--------------|----------------| @@ -101,10 +101,7 @@ 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. For example: `examplepath`. - - {{site.konnect_short_name}} uses this string to generate a custom login - URL for your organization. +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*. @@ -112,6 +109,9 @@ application into {{site.konnect_saas}}. * 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 %} @@ -125,10 +125,7 @@ application into {{site.konnect_saas}}. 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. For example: `examplepath`. - - {{site.konnect_short_name}} Dev Portal uses this string to generate a custom login - URL for your Dev Portal. +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*. @@ -139,16 +136,13 @@ application into {{site.konnect_saas}}. 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 == "Dev Portal" %} -### (Optional) Map {{site.konnect_short_name}} Dev Portal teams to Okta groups - -In the {{site.konnect_short_name}} Dev Portal, you can map existing developer teams from a third-party identity provider (IdP) and their permissions to elements in {{site.konnect_short_name}}. With teams mapped from an IdP, the developers and permissions are mapped automatically in {{site.konnect_short_name}} so you don’t have to manually copy over each team of developers. For more information about how to configure this, see [Add Developer Teams from Identity Providers](/konnect/dev-portal/access-and-approval/add-teams/). -{% endif %} {% if include.desc == "Konnect Org" %} ### (Optional) Map {{site.konnect_short_name}} teams to Okta groups diff --git a/app/konnect/dev-portal/access-and-approval/sso.md b/app/konnect/dev-portal/access-and-approval/sso.md index 061a5ce657f4..71992d7810a4 100644 --- a/app/konnect/dev-portal/access-and-approval/sso.md +++ b/app/konnect/dev-portal/access-and-approval/sso.md @@ -17,4 +17,4 @@ Keep the following in mind when configuring SSO for Dev Portal: ## Related links * [Configure generic SSO for a Konnect Org](/konnect/org-management/sso/) -* [IdP SSO attribute mapping reference](/konnect/reference/sso) \ No newline at end of file +* [IdP SAML attribute mapping reference](/konnect/reference/saml-idp-mappings/) \ No newline at end of file diff --git a/app/konnect/org-management/sso.md b/app/konnect/org-management/sso.md index 6cecaa53a702..1cff082b65f5 100644 --- a/app/konnect/org-management/sso.md +++ b/app/konnect/org-management/sso.md @@ -7,9 +7,35 @@ As an alternative to {{site.konnect_saas}}’s native authentication, you can se If you want to configure Okta, please see the [Okta configuration guide](/konnect/org-management/okta-idp/). +## Map {{site.konnect_short_name}} teams to Okta groups + +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. + +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. + {% include_cached /md/konnect/generic-sso.md desc='Konnect Org' %} ## Related links * [Configure generic SSO for Dev Portal](/konnect/dev-portal/access-and-approval/sso/) -* [IdP SSO attribute mapping reference](/konnect/reference/sso): Learn how Azure, Oracle Cloud, and KeyCloak attributes map to {{site.konnect_short_name}}. \ No newline at end of file +* [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/sso.md b/app/konnect/reference/saml-idp-mappings.md similarity index 96% rename from app/konnect/reference/sso.md rename to app/konnect/reference/saml-idp-mappings.md index 830c7a513fff..cbff56857e1d 100644 --- a/app/konnect/reference/sso.md +++ b/app/konnect/reference/saml-idp-mappings.md @@ -1,8 +1,8 @@ --- -title: IdP SSO attribute mapping reference +title: IdP SAML attribute mapping reference --- -This reference doc contains provider specific information and attribute mapping tables necessary for configuring SSO. +This reference doc contains provider specific information and attribute mapping tables necessary for configuring SSO with SAML. {% navtabs %} {% navtab Azure %}