[v18] Refactor SSO docs to improve readability

docs/config.json

@@ -202,7 +202,7 @@
     },
     {
       "source": "/enterprise/sso/google-workspace/",
-      "destination": "/zero-trust-access/sso/google-workspace/",
+      "destination": "/zero-trust-access/sso/integrate-idp/google-workspace/",
       "permanent": true
     },
     {
@@ -242,7 +242,7 @@
     },
     {
       "source": "/setup/admin/github-sso/",
-      "destination": "/zero-trust-access/sso/github-sso/",
+      "destination": "/zero-trust-access/sso/integrate-idp/github-sso/",
       "permanent": true
     },
     {
@@ -931,47 +931,47 @@
     },
     {
       "source": "/admin-guides/access-controls/sso/adfs/",
-      "destination": "/zero-trust-access/sso/adfs/",
+      "destination": "/zero-trust-access/sso/integrate-idp/adfs/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/azuread/",
-      "destination": "/zero-trust-access/sso/entra-id/",
+      "destination": "/zero-trust-access/sso/integrate-idp/entra-id/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/github-sso/",
-      "destination": "/zero-trust-access/sso/github-sso/",
+      "destination": "/zero-trust-access/sso/integrate-idp/github-sso/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/gitlab/",
-      "destination": "/zero-trust-access/sso/gitlab/",
+      "destination": "/zero-trust-access/sso/integrate-idp/gitlab/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/google-workspace/",
-      "destination": "/zero-trust-access/sso/google-workspace/",
+      "destination": "/zero-trust-access/sso/integrate-idp/google-workspace/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/keycloak/",
-      "destination": "/zero-trust-access/sso/keycloak/",
+      "destination": "/zero-trust-access/sso/integrate-idp/keycloak/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/oidc/",
-      "destination": "/zero-trust-access/sso/oidc/",
+      "destination": "/zero-trust-access/sso/integrate-idp/oidc/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/okta/",
-      "destination": "/zero-trust-access/sso/okta/",
+      "destination": "/zero-trust-access/sso/integrate-idp/okta/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/sso/one-login/",
-      "destination": "/zero-trust-access/sso/one-login/",
+      "destination": "/zero-trust-access/sso/integrate-idp/one-login/",
       "permanent": true
     },
     {
@@ -1236,12 +1236,12 @@
     },
     {
       "source": "/admin-guides/access-controls/login-rules/guide/",
-      "destination": "/zero-trust-access/authentication/login-rules/guide/",
+      "destination": "/zero-trust-access/sso/login-rules/guide/",
       "permanent": true
     },
     {
       "source": "/admin-guides/access-controls/login-rules/",
-      "destination": "/zero-trust-access/authentication/login-rules/",
+      "destination": "/zero-trust-access/sso/login-rules/",
       "permanent": true
     },
     {
@@ -1691,12 +1691,12 @@
     },
     {
       "source": "/zero-trust-access/access-controls/login-rules/guide/",
-      "destination": "/zero-trust-access/authentication/login-rules/guide/",
+      "destination": "/zero-trust-access/sso/login-rules/guide/",
       "permanent": true
     },
     {
       "source": "/zero-trust-access/access-controls/login-rules/",
-      "destination": "/zero-trust-access/authentication/login-rules/",
+      "destination": "/zero-trust-access/sso/login-rules/",
       "permanent": true
     },
     {
@@ -1726,7 +1726,7 @@
     },
     {
       "source": "/zero-trust-access/sso/azuread/",
-      "destination": "/zero-trust-access/sso/entra-id/",
+      "destination": "/zero-trust-access/sso/integrate-idp/entra-id/",
       "permanent": true
     },
     {
@@ -2857,6 +2857,63 @@
     {
       "source": "/enroll-resources/application-access/introduction/",
       "destination": "/enroll-resources/application-access/",
+      "source": "/zero-trust-access/sso/adfs/",
+      "destination": "/zero-trust-access/sso/integrate-idp/adfs/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/entra-id-oidc/",
+      "destination": "/zero-trust-access/sso/integrate-idp/entra-id-oidc/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/entra-id/",
+      "destination": "/zero-trust-access/sso/integrate-idp/entra-id/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/github-sso/",
+      "destination": "/zero-trust-access/sso/integrate-idp/github-sso/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/gitlab/",
+      "destination": "/zero-trust-access/sso/integrate-idp/gitlab/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/google-workspace/",
+      "destination": "/zero-trust-access/sso/integrate-idp/google-workspace/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/keycloak/",
+      "destination": "/zero-trust-access/sso/integrate-idp/keycloak/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/oidc/",
+      "destination": "/zero-trust-access/sso/integrate-idp/oidc/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/okta/",
+      "destination": "/zero-trust-access/sso/integrate-idp/okta/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/sso/one-login/",
+      "destination": "/zero-trust-access/sso/integrate-idp/one-login/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/authentication/login-rules/guide/",
+      "destination": "/zero-trust-access/sso/login-rules/guide/",
+      "permanent": true
+    },
+    {
+      "source": "/zero-trust-access/authentication/login-rules/",
+      "destination": "/zero-trust-access/sso/login-rules/",
       "permanent": true
     },
     {

docs/pages/connect-your-client/teleport-clients/tsh.mdx

@@ -303,7 +303,7 @@ This allows you to authenticate just once, maybe at the beginning of the day. Su
   It is recommended to always use [`tsh login`](../../reference/cli/tsh.mdx#tsh-login) before using any other `tsh` commands. This allows users to omit `--proxy` flag in subsequent tsh commands. For example `tsh ssh user@host` will work.
 </Admonition>
 
-A Teleport cluster can be configured for multiple user identity sources. For example, a cluster may have a local user called `admin` while regular users should [authenticate via GitHub](../../zero-trust-access/sso/github-sso.mdx). In this case, you have to pass `--auth` flag to `tsh login` to specify which identity storage to use:
+A Teleport cluster can be configured for multiple user identity sources. For example, a cluster may have a local user called `admin` while regular users should [authenticate via GitHub](../../zero-trust-access/sso/integrate-idp/github-sso.mdx). In this case, you have to pass `--auth` flag to `tsh login` to specify which identity storage to use:
 
 <Tabs>
 <TabItem scope={["oss", "enterprise"]} label="Self-Hosted">

docs/pages/enroll-resources/application-access/configuration/controls.mdx

@@ -146,9 +146,9 @@ for more information on enabling access to Azure managed identities.
 - Learn about using [JWT tokens](../jwt/introduction.mdx) to implement access
   controls in your application.
 - Integrate with your identity provider:
-  - [OIDC](../../../zero-trust-access/sso/oidc.mdx)
-  - [ADFS](../../../zero-trust-access/sso/adfs.mdx)
-  - [Microsoft Entra ID](../../../zero-trust-access/sso/entra-id.mdx)
-  - [Google Workspace](../../../zero-trust-access/sso/google-workspace.mdx)
-  - [Onelogin](../../../zero-trust-access/sso/one-login.mdx)
-  - [Okta](../../../zero-trust-access/sso/okta.mdx)
+  - [OIDC](../../../zero-trust-access/sso/integrate-idp/oidc.mdx)
+  - [ADFS](../../../zero-trust-access/sso/integrate-idp/adfs.mdx)
+  - [Microsoft Entra ID](../../../zero-trust-access/sso/integrate-idp/entra-id.mdx)
+  - [Google Workspace](../../../zero-trust-access/sso/integrate-idp/google-workspace.mdx)
+  - [Onelogin](../../../zero-trust-access/sso/integrate-idp/one-login.mdx)
+  - [Okta](../../../zero-trust-access/sso/integrate-idp/okta.mdx)

docs/pages/feature-matrix.mdx

@@ -134,7 +134,7 @@ and non-human identities.
 | User & Group Provisioning & Deprovisioning (SCIM & Custom Protocols), including Okta, Microsoft Entra ID, and SailPoint | ✔ | ✔ | ✖ |
 | [Access Monitoring & Response](identity-governance/access-monitoring.mdx): Detect overly broad privileges and inspect sessions that are not using strong protection, such as multi-factor authentication or device trust. Alert on access violations and purge unused permissions with automated access rules. | ✔ | ✔ | ✖ |
 | [Okta integration](identity-governance/integrations/okta/okta.mdx): Configure Teleport to import and grant access to Okta applications and user groups. | ✔ | ✔ | ✖ |
-| Microsoft Entra ID directory synchronization and SSO [integration](zero-trust-access/sso/entra-id.mdx) | ✔ | ✔ | ✖ |
+| Microsoft Entra ID directory synchronization and SSO [integration](zero-trust-access/sso/integrate-idp/entra-id.mdx) | ✔ | ✔ | ✖ |
 
 ## Teleport Identity Security
 

docs/pages/identity-governance/integrations/aws-iam-identity-center/migrating-identity-center-from-okta-to-teleport.mdx

@@ -105,7 +105,7 @@ Specifically:
 ### Step 1/6. Install Okta SAML connector
 
 Install Okta SAML connector into Teleport as per the Teleport
-[Okta as an SSO provider](../../../zero-trust-access/sso/okta.mdx) guide.
+[Okta as an SSO provider](../../../zero-trust-access/sso/integrate-idp/okta.mdx) guide.
 
 <Admonition type="note">
  For the integration to function properly, both AWS IAM Identity Center and Teleport must view the

docs/pages/identity-governance/integrations/entra-id/getting-started.mdx

@@ -187,6 +187,6 @@ importing resources from Entra ID to Teleport.
 - [Configure Access](configure-access.mdx) for Entra ID users.
 - Configure [group filters](advanced-options.mdx#group-filters). 
 - Learn more about [Access List](../../access-lists/access-lists.mdx) management.
-- Take a deeper look into setting up [Entra ID auth connector](../../../zero-trust-access/sso/entra-id.mdx). 
+- Take a deeper look into setting up [Entra ID auth connector](../../../zero-trust-access/sso/integrate-idp/entra-id.mdx). 
 - Learn how the [Identity Security integration with Entra ID](../../../identity-security/integrations/entra-id.mdx) works. 
 - See [FAQs](faq.mdx) related to the Teleport Entra ID integration. 

docs/pages/identity-governance/integrations/entra-id/setup/manual-installation.mdx

@@ -116,6 +116,6 @@ After you enter these values, Entra ID plugin will be installed with the OIDC Id
 - [Configure Access](../configure-access.mdx) for Entra ID users.
 - Configure [group filters](../advanced-options.mdx#group-filters). 
 - Learn more about [Access List](../../../access-lists/access-lists.mdx) management.
-- Take a deeper look into setting up [Entra ID auth connector](../../../../zero-trust-access/sso/entra-id.mdx). 
+- Take a deeper look into setting up [Entra ID auth connector](../../../../zero-trust-access/sso/integrate-idp/entra-id.mdx). 
 - Learn how the [Identity Security integration with Entra ID](../../../../identity-security/integrations/entra-id.mdx) works. 
 - See [FAQs](../faq.mdx) related to the Teleport Entra ID integration. 

docs/pages/identity-governance/integrations/entra-id/setup/terraform.mdx

@@ -232,6 +232,6 @@ plugin service that imports users and groups from Entra ID to Teleport.
 
 - Learn how to [configure access](../configure-access.mdx) for Entra ID users.
 - Configure [group filters](../advanced-options.mdx#group-filters). 
-- Take a deeper look into setting up [Entra ID auth connector](../../../../zero-trust-access/sso/entra-id.mdx). 
+- Take a deeper look into setting up [Entra ID auth connector](../../../../zero-trust-access/sso/integrate-idp/entra-id.mdx). 
 - Learn how the [Identity Security integration with Entra ID](../../../../identity-security/integrations/entra-id.mdx) works. 
 - See [FAQs](../faq.mdx) related to the Teleport Entra ID integration. 

docs/pages/identity-governance/integrations/okta/guided-sso.mdx

@@ -20,7 +20,7 @@ perform required actions within Okta.
 If you do not plan to enroll additional components of the guided Okta
 integration, you can set up only the Okta SSO integration - called an
 authentication connector - by following [Authentication With Okta as an SSO
-Provider](../../../zero-trust-access/sso/okta.mdx).
+Provider](../../../zero-trust-access/sso/integrate-idp/okta.mdx).
 
 ## Prerequisites
 
@@ -36,7 +36,7 @@ Provider](../../../zero-trust-access/sso/okta.mdx).
   the integration is hardcoded as `okta`. If you have a connector named `okta`
   and you'd like to use a different one, you'll have to create your connector
   manually following [Authentication With Okta as an SSO Provider
-  ](../../../zero-trust-access/sso/okta.mdx).
+  ](../../../zero-trust-access/sso/integrate-idp/okta.mdx).
 
 - (!docs/pages/includes/tctl.mdx!)
 

docs/pages/includes/sso/change-callback.mdx

@@ -0,0 +1,29 @@
+The callback address can be changed if calling back to a remote machine
+instead of the local machine is required:
+
+```code
+# --bind-addr sets the host and port tsh will listen on, and --callback changes
+# what link is displayed to the user
+$ tsh login --proxy=proxy.example.com --auth=github --bind-addr=localhost:1234 --callback https://remote.machine:1234
+```
+
+For this to work the hostname or CIDR of the remote machine that will be used for
+the callback will need to be allowed via your auth connector's `client_redirect_settings`:
+
+```yaml
+kind: oidc
+metadata:
+  name: example-connector
+spec:
+  client_redirect_settings:
+    # a list of hostnames allowed for HTTPS client redirect URLs
+    # can be a regex pattern
+    allowed_https_hostnames:
+      - remote.machine
+      - '*.app.github.dev'
+      - '^\d+-[a-zA-Z0-9]+\.foo.internal$'
+    # a list of CIDRs allowed for HTTP or HTTPS client redirect URLs
+    insecure_allowed_cidr_ranges:
+      - '192.168.1.0/24'
+      - '2001:db8::/96'
+```

docs/pages/includes/sso/next-step-traits.mdx

@@ -39,5 +39,5 @@ If you need to transform your IdP user data before you include it in Teleport
 roles, you can do so using **Login Rules**. Login Rules allow you to include
 external traits within Teleport roles even if your IdP provides user data in a
 different format than the one expected by Teleport. Read more about [Login
-Rules](../../zero-trust-access/authentication/login-rules/login-rules.mdx).
+Rules](../../zero-trust-access/sso/login-rules/login-rules.mdx).
 

docs/pages/index.mdx

@@ -48,7 +48,7 @@ import listBulletsSvg from "@site/src/components/Icon/teleport-svg/list-bullets.
     },
     { 
       label: "Set up SSO with GitHub", 
-      href: "./zero-trust-access/sso/github-sso/" 
+      href: "./zero-trust-access/sso/integrate-idp/github-sso/" 
     },
     { 
       label: "Set up Slack Access Request Plugin", 

docs/pages/reference/access-controls/authentication.mdx

@@ -178,7 +178,7 @@ spec:
 version: v2
 ```
 
-See [GitHub OAuth 2.0](../../zero-trust-access/sso/github-sso.mdx) for details on how to configure it.
+See [GitHub OAuth 2.0](../../zero-trust-access/sso/integrate-idp/github-sso.mdx) for details on how to configure it.
 
 ### SAML
 
@@ -226,7 +226,7 @@ auth_service:
     type: github
 ```
 
-See [GitHub OAuth 2.0](../../zero-trust-access/sso/github-sso.mdx) for details on how to configure it.
+See [GitHub OAuth 2.0](../../zero-trust-access/sso/integrate-idp/github-sso.mdx) for details on how to configure it.
 
 ### SAML
 
@@ -268,7 +268,7 @@ auth_service:
     type: github
 ```
 
-See [GitHub OAuth 2.0](../../zero-trust-access/sso/github-sso.mdx) for details on how to configure it.
+See [GitHub OAuth 2.0](../../zero-trust-access/sso/integrate-idp/github-sso.mdx) for details on how to configure it.
 
 </TabItem>
 </Tabs>

docs/pages/reference/access-controls/login-rules.mdx

@@ -11,7 +11,7 @@ tags:
 
 This page provides details on the expression language that powers Login Rules.
 To learn how to add the first login rule to your cluster, checkout out the
-[Login Rules Guide](../../zero-trust-access/authentication/login-rules/guide.mdx).
+[Login Rules Guide](../../zero-trust-access/sso/login-rules/guide.mdx).
 
 ## YAML specification
 
@@ -811,7 +811,7 @@ claims using the given [jsonpath query](https://support.smartbear.com/alertsite/
 This is intended for use with traditionally unmapped arbitrary JSON claims which are
 used in some custom OIDC solutions.
 
-See [this guide](../../zero-trust-access/sso/sso.mdx#using-an-oidc-provider-with-arbitrary-non-standard-json-claims) for more context.
+See [this guide](../../zero-trust-access/sso/login-rules/guide.mdx#using-an-oidc-provider-with-arbitrary-non-standard-json-claims) for more context.
 
 #### Arguments
 

docs/pages/reference/architecture/relay.mdx

@@ -68,7 +68,7 @@ You can configure a default Relay address on a per-user basis using the `default
 - Directly for each [local user](../../zero-trust-access/rbac-get-started/users.mdx)
 - Passed by the SSO provider for [SSO users](../../zero-trust-access/sso/sso.mdx)
 - Granted through an [Access List](../../identity-governance/access-lists/access-lists.mdx)
-- Added by a [Login Rule](../../zero-trust-access/authentication/login-rules/login-rules.mdx)
+- Added by a [Login Rule](../../zero-trust-access/sso/login-rules/login-rules.mdx)
 
 When using `tsh ssh`:
 

docs/pages/reference/cli/tctl.mdx

@@ -1450,7 +1450,7 @@ The following flags are specific to Google Workspace:
 | `--google-acc-uri` | URI of your service account credentials file. Example: `file:///var/lib/teleport/gworkspace-creds.json`.|
 | `--google-acc`      | String containing Google service account credentials.                                                  |
 | `--google-admin`   | Email of a Google admin to impersonate.                                                                |
-| `--google-legacy`  | Flag to select groups with direct membership filtered by domain (legacy behavior). <br/>Disabled by default. [More info](../../zero-trust-access/sso/google-workspace.mdx) |
+| `--google-legacy`  | Flag to select groups with direct membership filtered by domain (legacy behavior). <br/>Disabled by default. [More info](../../zero-trust-access/sso/integrate-idp/google-workspace.mdx) |
 | `--google-id`      | Shorthand for setting the `--id` flag to `<GOOGLE_WORKSPACE_CLIENT_ID>.apps.googleusercontent.com`     |
 
 ### Global flags

docs/pages/reference/infrastructure-as-code/teleport-resources/teleport-resources.mdx

@@ -56,7 +56,7 @@ Here's the list of resources currently exposed via [`tctl`](../../cli/tctl.mdx):
 | node | A registered SSH node. The same record is displayed via `tctl nodes ls`. |
 | windows_desktop | A registered Windows desktop. |
 | cluster | A trusted cluster. See [here](../../../zero-trust-access/deploy-a-cluster/trustedclusters.mdx) for more details on connecting clusters together. |
-| [login_rule](login-rules.mdx) | A Login Rule, see the [Login Rules guide](../../../zero-trust-access/authentication/login-rules/login-rules.mdx) for more info. |
+| [login_rule](login-rules.mdx) | A Login Rule, see the [Login Rules guide](../../../zero-trust-access/sso/login-rules/login-rules.mdx) for more info. |
 | [device](device.mdx) | A Teleport Trusted Device, see the [Device Trust guide](../../../identity-governance/device-trust/guide.mdx) for more info. |
 | [ui_config](ui-config.mdx) | Configuration for the Web UI served by the Proxy Service. |
 | [vnet_config](vnet-config.mdx) | Configuration for the cluster's VNet options. |