Refactor SSO docs to improve readability#61492
Merged
Conversation
ptgott
had a problem deploying
to
docs-amplify
GitHub Actions
Failure
Contributor
|
Amplify deployment status
|
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
cc3f48e to
b3e05c0
Compare
ptgott
had a problem deploying
to
docs-amplify
GitHub Actions
Failure
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
b3e05c0 to
e1b5ccd
Compare
ptgott
had a problem deploying
to
docs-amplify
GitHub Actions
Failure
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
e1b5ccd to
48af357
Compare
ptgott
had a problem deploying
to
docs-amplify
GitHub Actions
Failure
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
48af357 to
af363f0
Compare
ptgott
had a problem deploying
to
docs-amplify
GitHub Actions
Failure
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
af363f0 to
e96de50
Compare
ptgott
had a problem deploying
to
docs-amplify
GitHub Actions
Failure
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
e96de50 to
0721852
Compare
ptgott
added
the
no-changelog
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
0721852 to
8bb918b
Compare
github-actions
bot
requested review from
flyinghermit,
greedy52,
kimlisa,
mmcallister,
r0mant,
ravicious,
smallinsky and
zmb3
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
0d77449 to
fa79a5e
Compare
ptgott
added a commit
that referenced
this pull request
Dec 5, 2025
Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
fa79a5e to
f9860a3
Compare
ptgott
added a commit
that referenced
this pull request
Dec 5, 2025
Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
added a commit
that referenced
this pull request
Dec 5, 2025
Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
added a commit
that referenced
this pull request
Dec 5, 2025
Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
f9860a3 to
75ec7c5
Compare
ptgott
added a commit
that referenced
this pull request
Dec 5, 2025
Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
75ec7c5 to
14887b9
Compare
ptgott
added a commit
that referenced
this pull request
Dec 8, 2025
Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
github-merge-queue bot
pushed a commit
that referenced
this pull request
Dec 8, 2025
Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
added a commit
that referenced
this pull request
Dec 9, 2025
Backports #62026 Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
14887b9 to
105036c
Compare
ptgott
added a commit
that referenced
this pull request
Dec 9, 2025
Backports #62026 Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
added a commit
that referenced
this pull request
Dec 10, 2025
Backports #62026 Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ravicious
approved these changes
Dec 11, 2025
ptgott
added a commit
that referenced
this pull request
Dec 11, 2025
Backports #62026 Make the Zero Trust Access sidebar easier to navigate by reducing noise. Shorten sidebar labels and add a more logical order based on how broadly applicable a given guide is. To limit the scope, this change does not address the Management subsection, which will be reserved for a future change (see #57908). This change does not modify the SSO or Login Rules sections, since #61492 will complete that work instead. Details: - `/zero-trust-access/infrastructure-as-code/`: Put Managing Resources first, since it includes beginner-level how-to instructions for all three IaC tools we support. - Move the Terraform resource import guide to the Terraform subsection. It's only applicable to Terraform, and out of place in the Managing Resources section, in which each page has to do with a single resource type. - Move the IdP Compromise guide. It belongs in the Security section. Also rename the file to more accurately reflect the guide's content. - Move the general HA guide into Deployment Guides, since that section contains other architectural plans for deploying Teleport. The same goes for the Multi-Region Blueprint guide and Proxy Service traffic separation guide. - Move the Argo CD guide to the Agents section, since it's a guide to joining an agent, not deploying a Teleport cluster.
ptgott
force-pushed
the
paul.gottschling/2025-11-10-sso-refactor
branch
from
105036c to
449be11
Compare
The SSO documentation currently consists of: - One long conceptual guide - IdP-specific how-to guides The conceptual guide holds a collection of topics with no unifying theme besides Teleport's SSO support, making it difficult to discover topics for readers who have not made their way through the entire guide. This change aims to improve the discoverability of SSO topics by: - Splitting the conceptual guide into multiple pages - Moving IdP-specific guides into their own subsection - Moving the Login Rules docs, which only make sense if a user is setting up SSO, into the SSO section of the docs. To split the main conceptual guide, this change: - Turns the SSO for MFA section into a how-to guide. This mostly the structure of a how-to guide, but we couldn't use this structure because this text was a section of the conceptual SSO guide. By splitting the SSO guide, we can make this a how-to guide. - Move the "Changing callback address" section into a partial that we can include in the IdP-specific how-to guides, since the level of detail within this section is consistent with those guides. - Move "Working with an external identity". This belongs in Role Templates, and has the wrong level of detail for an overview of SSO. To get this to work, add H3s to the interpolation section of the Role Templates guide. - Move all content re: configuring specific authentication connector fields into the section index page for the IdP-specific guides. - Remove the Troubleshooting section. This text is repeated using a partial in every IdP-specific guide, and is the wrong level of detail for a general overview. - Move the Login Rules example to where we include other Login Rule examples, in the Login Rules guide. - Remove the tabbed examples of authentication connectors from the SSO index page. There is not nearly enough context on this page to help a reader make use of these examples. Instead, refer the reader to the IdP-specific how-to guides. - Move "multiple SSO provider" discussion to its own page.
mmcallister
approved these changes
Dec 18, 2025
Contributor
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
The SSO documentation currently consists of:
The conceptual guide holds a collection of topics with no unifying theme besides Teleport's SSO support, making it difficult to discover topics for readers who have not made their way through the entire guide. This change aims to improve the discoverability of SSO topics by:
To split the main conceptual guide, this change: