[DX-1401] Restructured SSO pages to improve clarity

[andyo-tyk]

User description

Preview Link

https://deploy-preview-4736--tyk-docs.netlify.app/docs/nightly/advanced-configuration/integrate/sso/
https://deploy-preview-4736--tyk-docs.netlify.app/docs/nightly/advanced-configuration/integrate/3rd-party-identity-providers/
https://deploy-preview-4736--tyk-docs.netlify.app/docs/nightly/advanced-configuration/integrate/

Description

https://tyktech.atlassian.net/browse/DX-1401

Restructured the SSO / 3rd Party IdP integration pages to make them easier to find and work with.

---

PR Type

documentation

---

Description

• Restructured SSO documentation to improve clarity and accessibility.
• Added detailed configuration steps for integrating various Identity Providers (IdPs) with Tyk Dashboard.
• Simplified descriptions and provided example configurations for LDAP, custom proxy, and social IdPs.
• Updated menu structure to reflect changes in the documentation.

---

Changes walkthrough 📝

Relevant files

Documentation

10 files integrate.md Restructured integration options for SSO examples.              tyk-docs/content/advanced-configuration/integrate.md Updated integration options to focus on SSO examples using Tyk Identity Broker. Added links to specific IdP integration guides. +7/-7      3rd-party-identity-providers.md Expanded SSO integration methods and configurations.          tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers.md Renamed title to "Single Sign-On integration". Expanded on SSO methods and provided detailed configuration steps. +78/-11  custom.md Simplified custom proxy integration description.                  tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/custom.md Renamed title to "Integrate with Custom Proxy". Simplified the description of the proxy identity provider. +1/-3      ldap.md Expanded LDAP integration details and examples.                    tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/ldap.md Renamed title to "Lightweight Directory Access Protocol (LDAP)". Expanded on LDAP integration details and provided example configurations. +19/-23  social.md Detailed integration with social identity providers.          tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social.md Renamed title to "Integrate with Social Identity Providers". Provided an overview and configuration steps for social IdPs. +26/-17  dashboard-login-with-gplus.md Removed redundant section title for Google+ login.              tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus.md Removed redundant section title. +0/-3      api-auth-mode.md Removed outdated API authentication mode file.                      tyk-docs/content/advanced-configuration/integrate/api-auth-mode.md Removed the file as part of restructuring. +0/-10    sso.md Simplified and restructured SSO documentation.                      tyk-docs/content/advanced-configuration/integrate/sso.md Simplified and restructured the SSO documentation. Provided detailed steps for configuring SSO with Tyk Dashboard. +36/-129 json-web-tokens.md Enhanced JWT introduction and overview.                                    tyk-docs/content/basic-config-and-security/security/authentication-authorization/json-web-tokens.md Moved JWT introduction to the top. Provided a brief overview of JWT's role in SSO. +9/-9      menu.yaml Updated menu structure for SSO and integration docs.          tyk-docs/data/menu.yaml Updated menu structure to reflect new SSO and integration documentation. Added and renamed menu items for better clarity. +46/-58

---

💡 PR-Agent usage:
Comment /help on the PR to get a list of all available PR-Agent tools and their descriptions

[github-actions]

PR Review 🔍

⏱️ Estimated effort to review [1-5]	2, because the PR primarily involves documentation changes and updates to the structure and titles within the documentation. These changes are straightforward and do not involve complex code modifications, making the review process relatively quick and easy.
🧪 Relevant tests	No
⚡ Possible issues	No
🔒 Security concerns	No

Code feedback:

[netlify]

✅ PS. Pls add /docs/nightly to the end of url

Name	Link
🔨 Latest commit	9f29df4
🔍 Latest deploy log	https://app.netlify.com/sites/tyk-docs/deploys/667446658b59f00008ef98cf
😎 Deploy Preview	https://deploy-preview-4736--tyk-docs.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

---

To edit notification comments on pull requests, go to your Netlify site configuration.

[github-actions]

PR Code Suggestions ✨

Category	Suggestion	Score
Security	Add security recommendations for handling the nonce parameter in SSO To enhance the security of the SSO implementation, consider explicitly mentioning the need for secure handling of the nonce parameter. This should include recommendations for generating a secure nonce and ensuring that it is used correctly to prevent replay attacks. tyk-docs/content/advanced-configuration/integrate/sso.md [73] -Both APIs' `/sso` endpoints will generate a temporary authentication token, valid for 60 seconds, that can be used to log in to the `/tap` endpoint, or to the portal using the `<portal-url>/sso` endpoint, providing the token via the `nonce` query param. +Both APIs' `/sso` endpoints will generate a temporary authentication token, valid for 60 seconds, that can be used to log in to the `/tap` endpoint, or to the portal using the `<portal-url>/sso` endpoint. It is crucial to securely generate and handle the `nonce` query parameter to prevent replay attacks. Ensure that the nonce is used correctly and securely in your implementation. Suggestion importance[1-10]: 10 Why: This suggestion is crucial for enhancing the security of the SSO implementation. It provides important recommendations for securely handling the nonce parameter, which helps prevent replay attacks and ensures a more secure authentication process.	10
	Add a warning about the security implications of default admin rights in SSO It's recommended to clarify the implications of granting admin rights by default when logging in via SSO. This could be a security risk if not properly managed. Consider adding a warning or note about the potential risks and the importance of configuring permissions carefully. tyk-docs/content/advanced-configuration/integrate/sso.md [36] -Logging in via SSO will grant the user **admin** rights in Tyk Dashboard, giving the user full access to configure and control the Dashboard. +Logging in via SSO will grant the user **admin** rights in Tyk Dashboard by default, giving the user full access to configure and control the Dashboard. **Warning:** Admin rights can pose a security risk if not properly managed. It is crucial to configure user permissions carefully to ensure secure operation. Suggestion importance[1-10]: 9 Why: This suggestion addresses a significant security concern by warning users about the potential risks of granting admin rights by default. It emphasizes the importance of configuring permissions carefully, which is crucial for maintaining secure operations.	9
Enhancement	Replace "Google+" with "Google" to reflect the current status of the platform It's recommended to avoid using the term "Google+" as it has been discontinued by Google. Instead, focus on other active social platforms or general Google authentication methods. tyk-docs/content/advanced-configuration/integrate.md [15] -- [Google+]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus" >}}) +- [Google]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-google" >}}) Suggestion importance[1-10]: 9 Why: The suggestion is accurate and reflects the current status of the Google+ platform, which has been discontinued. Updating the reference to "Google" ensures the documentation remains relevant and accurate.	9
	Update references from "Google+" to "Google" in the social providers list Update the documentation to remove references to "Google+" and replace them with "Google" to ensure the documentation remains up-to-date with current available services. tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social.md [15] -- Google+ +- Google Suggestion importance[1-10]: 9 Why: This suggestion correctly identifies the need to update the documentation to reflect the discontinuation of Google+. It ensures that users are not misled by outdated references.	9
	Update or remove the Google+ integration page to align with current Google authentication services Since Google+ is no longer available, consider removing or updating this page to reflect integration with Google's current authentication services instead of Google+. tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus.md [15] -- [Google+]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus" >}}) +- [Google]({{< ref "advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-google" >}}) Suggestion importance[1-10]: 9 Why: The suggestion is valid as it addresses the need to update or remove references to Google+ in favor of current Google authentication services, ensuring the documentation is accurate and up-to-date.	9
	Provide direct links or clear paths to the documentation for required API headers To avoid potential confusion and improve the documentation's clarity, consider providing a direct link or a clear path to the documentation or settings for the admin-auth and authorization headers required by the Tyk Dashboard Admin API and Tyk Dashboard API respectively. tyk-docs/content/advanced-configuration/integrate/sso.md [70-71] -- the Tyk Dashboard Admin API requires an `admin-auth` header which should match the `admin-secret` parameter in `tyk_analytics.conf` -- the Tyk Dashboard API requires an `authorization` header which should match the user authentication token +- the Tyk Dashboard Admin API requires an `admin-auth` header. Ensure this matches the `admin-secret` parameter in `tyk_analytics.conf`. For more details, see [Configuration Settings](link-to-configuration). +- the Tyk Dashboard API requires an `authorization` header. This should match the user authentication token. For more details, see [User Authentication](link-to-authentication). Suggestion importance[1-10]: 8 Why: This suggestion improves the clarity and usability of the documentation by providing direct links or clear paths to the relevant settings. It helps users quickly find the necessary information, reducing potential confusion.	8
	Simplify the URL path for Keycloak SSO to enhance clarity and consistency Remove redundancy in the path for Keycloak SSO login. The path includes both 'product-stack' and 'advanced-configurations', which might be simplified to align with other paths. tyk-docs/data/menu.yaml [415-418] - title: "Log in to Tyk Dashboard using Keycloak" - path: /product-stack/tyk-dashboard/advanced-configurations/sso/dashboard-login-keycloak-sso + path: /tyk-stack/tyk-manager/sso/dashboard-login-keycloak category: Page show: True Suggestion importance[1-10]: 6 Why: The suggestion aims to simplify the URL path, which can improve clarity and consistency. However, it is not critical and the existing path is functional.	6
Consistency	Standardize the terminology for user actions across menu items Ensure consistency in the use of "Log in" and "Login" across the menu items. The term "Log in" is generally used as a verb, and "Login" as a noun or adjective. It is recommended to use "Log in" when referring to the action of accessing the dashboard. tyk-docs/data/menu.yaml [427-430] -- title: "Login in to Tyk Dashboard using LDAP" +- title: "Log in to Tyk Dashboard using LDAP" path: /advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib category: Page show: True Suggestion importance[1-10]: 9 Why: The suggestion correctly identifies an inconsistency in terminology and provides a clear improvement to maintain consistency and professionalism in the documentation.	9
Possible issue	Correct a spelling error in the menu title to enhance professionalism Correct the spelling error in the title from "Login in" to "Log in" for LDAP configuration to maintain professionalism and accuracy. tyk-docs/data/menu.yaml [427-430] -- title: "Login in to Tyk Dashboard using LDAP" +- title: "Log in to Tyk Dashboard using LDAP" path: /advanced-configuration/integrate/3rd-party-identity-providers/dashboard-login-ldap-tib category: Page show: True Suggestion importance[1-10]: 9 Why: The suggestion addresses a clear spelling error, improving the professionalism and accuracy of the documentation.	9
Documentation	Clarify the transition from Google+ to Google for users referencing older documentation Consider adding a note or section that clarifies the transition from Google+ to Google authentication methods, providing guidance for users who might still be looking for Google+ specific documentation. tyk-docs/content/advanced-configuration/integrate/3rd-party-identity-providers/social.md [15] -- Google+ +- Google (previously Google+) Suggestion importance[1-10]: 8 Why: This suggestion is useful for users who might still be looking for Google+ specific documentation. It provides clarity on the transition to current Google authentication methods, enhancing the overall user experience.	8
Maintainability	Replace HTML tags with markdown spacing for better readability To improve readability and maintainability, consider removing the redundant tags and instead use markdown spacing techniques. Multiple consecutive line breaks can be replaced with a single blank line to achieve the same visual separation in markdown. tyk-docs/content/advanced-configuration/integrate/sso.md [17-18] -<br> -<br> + Suggestion importance[1-10]: 7 Why: This suggestion improves the readability and maintainability of the documentation by replacing HTML tags with markdown spacing techniques. While it is a minor change, it enhances the overall quality of the documentation.	7
	Improve the consistency of URL paths for SSO configurations Update the path for the Google+ login to reflect a more consistent directory structure based on other SSO configurations. The current path seems to be overly nested and inconsistent with other paths. tyk-docs/data/menu.yaml [423-426] - title: "Log in to Tyk Dashboard with Google+" - path: /advanced-configuration/integrate/3rd-party-identity-providers/social/dashboard-login-with-gplus + path: /tyk-stack/tyk-manager/sso/dashboard-login-googleplus category: Page show: True Suggestion importance[1-10]: 7 Why: The suggestion improves the consistency of URL paths, which enhances maintainability. However, the existing path is not incorrect, so this is a minor improvement.	7

[andyo-tyk]

Add precision for Tyk Classic Developer Portal

[OldStubbsy]

A huge improvement!

[sredxny]

if this is specific for open-id then worth to let the user know that they need to add openid and email in the scopes if they want to pull the user information? (so we can check if the user already exists in the dashboard, display the correct name etc)

[carlostyk]

@sredxny @andyo-tyk This is a very good point - I was not aware of this since in the UI the scopes are placed as optional and I was getting a generic email and not the one from the user I was logging in with.

[sredxny]

no configuration is required and it is readily available for use. is not 100% accurate, even tought it's simpler now anyway customers need to ensure that TIB is enabled in the configs: identity_broker.enabled

[sredxny]

I think we must mention that sso must be enabled for the organisation, we enable this in the database and set sso_enabled:true for the given org

[sredxny]

also, you can limit that only registered users (in the dashboard database) can use and perform the authentication flow with a profile by setting SSOOnlyForRegisteredUsers:true, this only works for sso into the dashboard, not classic portal.

[sredxny]

so, if someone doesn't exists in the dashboard database but they logged in successfully into the idp anyway the dashboard will deny the access

[sredxny]

maybe here is a good place to talk about user groups mapping? and custom_user_group_field?

[carlostyk]

I would add some raw schema examples. I was not aware of some of the configurations like the scopes ones as those were optional. @sredxny share one with me that was pretty interesting.

I haven't been using a lot SSO so I am not able to give much feedback on missing things like the ones shared by @sredxny.

I can say that the information looks much better.

We also just found out some feedback that we are missing SAML configuration steps apart from the video that we have.

Duplicated

[letzya]

@andyo-tyk looks like there are lots of unresolved conversations (haven't checked them TBH), please let us know when it's ready for a DX review (changed to draft for now). We might not have time to accommodate it today but please let us know if it's an urgent matter.

[JRWu]

Content looks good, requesting minor changes.

[JRWu]

These schemas seem to reference broken links on xmlsoap

[JRWu]

These schemas seem to reference broken links on xmlsoap

[JRWu]

These schemas seem to reference broken links on xmlsoap

[dcs3spp]

PR LGTM, I have made minor suggestions and where possible committed them to the PR. Once peer approval given will merge and release

[dcs3spp]

Is this a URL?

[letzya]

@dcs3spp @andyo-tyk would we be good to explain what sso means or do we have it somewhere else and I missed it?

Update:
After reading this I see we have content here https://deploy-preview-4736--tyk-docs.netlify.app/docs/nightly/advanced-configuration/integrate/sso/ - have you considered moving this page from the "reference" tab to the JTBD section in API management?

...also there's another place that explains sso - https://tyk.io/docs/tyk-cloud/teams--users/single-sign-on/#what-is-sso, Should we consolidate it to one and link to it?

[letzya]

Also, we put it under the planning phase but it's not really clear why. We should explain what the JTBD is and how it's part of the planning phase. (could be in a separate PR, but it's needed as it's not trivial to connect the dots when one reads it.

[letzya]

@andyo-tyk will you have time to go through Sredny's @sredxny suggestions? this is very old and has conflicts now