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 1/7] 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 }}
+
+