gravitational · ptgott · May 26, 2022 · May 26, 2022
diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx
@@ -5,7 +5,7 @@ h1: Single Sign-On (SSO) for SSH
 ---
 
 Users of the Enterprise edition of Teleport can log in to servers, Kubernetes
-clusters, databases, web applications, and Windows desktops through your
+clusters, databases, web applications, and Windows desktops through their
 organization's Single Sign-On (SSO) provider.
 
 <ScopedBlock scope="oss">
@@ -55,30 +55,36 @@ organization's Single Sign-On (SSO) provider.
 
 ## How does SSO work?
 
-Users need to execute the following command login in the CLI or login using UI:
+Execute the following command to log in to your Teleport cluster using the CLI.
 
-```bsh
-# this command will automatically open the default web browser and take a user
-# through the login process with an SSO provider:
+```code
+# This command will automatically open the default web browser and take a user
+# through the login process with an SSO provider
 $ tsh login --proxy=proxy.example.com --auth=github
+```
 
-# output:
+The command opens a browser window and shows a URL the user can visit in the
+terminal to complete their SSO flow:
+
+```text
 If browser window does not open automatically, open it by clicking on the link:
 http://127.0.0.1:45235/055a310a-1099-43ea-8cf6-ffc41d88ad1f
 ```
 
-Teleport will wait for up to 3 minutes for a user to authenticate. If authentication
-succeeds, Teleport will retrieve an SSH and X.509 certificates and will store them in
-`~/.tsh/keys/proxy.example.com` directory. The tool will also will add SSH cert to an
-SSH agent if there's one running.
+Teleport will wait for up to 3 minutes for a user to authenticate. If
+authentication succeeds, Teleport will retrieve SSH and X.509 certificates and
+store them in the `~/.tsh/keys/<clustername>` directory. The tool will also will
+add SSH cert to an SSH agent if there's one running.
 
 ## Configuring SSO
 
-Teleport works with SSO providers by relying on a concept called
-*"authentication connector"*. An auth connector is a plugin which controls how
-a user logs in and which group he or she belongs to.
+Teleport works with SSO providers by relying on the concept of an
+**authentication connector**. An authentication connector is a plugin that
+controls how a user logs in and which group they belong to.
+
+### Supported connectors
 
-The following connectors are supported:
+The following authentication connectors are supported:
 
 - `local` connector type uses the built-in user database. This database can be
   manipulated by the `tctl users` command.
@@ -87,21 +93,22 @@ The following connectors are supported:
 - `oidc` connector type uses the [OpenID Connect protocol](https://en.wikipedia.org/wiki/OpenID_Connect)
   to authenticate users and query their group membership.
 
-To configure SSO, a Teleport administrator must:
+### Creating an authentication connector
+
+Before you can create an authentication connector, you must enable
+authentication via that connector's protocol.
 
-- Update the default authentication type.
-- Define the connector [resource](../setup/reference/resources.mdx) and save it into
-  a YAML file (like `connector.yaml`).
-- Create the connector using `tctl create connector.yaml`.
+To set the default authentication type as `saml` or `oidc`, <ScopedBlock
+scope={["oss", "enterprise"]}>either modify your Auth Service configuration file
+or </ScopedBlock>create a `cluster_auth_preference` resource.
 
-To set the default authentication type as `saml` or `oidc`, <ScopedBlock scope={["oss", "enterprise"]}>either modify your Auth Service configuration file or </ScopedBlock>create a `cluster_auth_preference` resource.
 <Tabs>
-  <TabItem label="Static Config (Self-Hosted)">
+  <TabItem label="Static Config (Self-Hosted)" scope={["oss", "enterprise"]}>
  Update `/etc/teleport.yaml` in the `auth_service` section and restart the `teleport` daemon.
   ```yaml
   auth_service:
     authentication:
-# Set as saml or oidc
+      # Set as saml or oidc
       type: saml|oidc
   ```
   </TabItem>
@@ -113,62 +120,105 @@ To set the default authentication type as `saml` or `oidc`, <ScopedBlock scope={
     name: cluster-auth-preference
   spec:
     authentication:
-# set as saml or oidc
+      # set as saml or oidc
       type: saml|oidc
   version: v2
   ```
 
   Create the resource:
 
+  <ScopedBlock scope={["oss", "enterprise"]}>
+
+  ```code
+  # Log in to your cluster with tsh so you can run tctl commands.
+  # You can also run tctl directly on the Auth Service host.
+  $ tsh login --proxy=teleport.example.com --user=myuser
+  $ tctl create -f cap.yaml
+  ```
+
+  </ScopedBlock>
+  <ScopedBlock scope={["cloud"]}>
+
   ```code
+  # Log in to your cluster with tsh so you can run tctl commands.
+  $ tsh login --proxy=mytenant.teleport.sh --user=myuser
   $ tctl create -f cap.yaml
   ```
+
+  </ScopedBlock>
   </TabItem>
 </Tabs>
 
 
-An example of a connector:
+Next, define an authentication connector. Create a file called `connector.yaml`
+based on one of the following examples.
+
+<Tabs>
+<TabItem label="Okta">
 
 ```yaml
-# connector.yaml
-kind: saml
-version: v2
-metadata:
-  name: corporate
-spec:
-  # display allows to set the caption of the "login" button
-  # in the Web interface
-  display: "Okta"
-
-  acs: https://teleport-proxy.example.com:3080/v1/webapi/saml/acs
-  attributes_to_roles:
-    - {name: "groups", value: "okta-admin", roles: ["access"]}
-    - {name: "groups", value: "okta-dev", roles: ["dev"]}
-
-     # note that wildcards can also be used. the next line instructs Teleport
-     # to assign "access" role to any user who has the SAML attribute that begins with "admin":
-     - { name: "group", value: "admin*", roles: ["access"] }
-     # regular expressions with capture are also supported. the next line instructs Teleport
-     # to assign users to roles `admin-1` if his SAML "group" attribute equals 'ssh_admin_1':
-     - { name: "group", value: "^ssh_admin_(.*)$", roles: ["admin-$1"] }
-
-  entity_descriptor: |
-    <paste SAML XML contents here>
+(!/examples/resources/okta-connector.yaml!)
 ```
 
-- See [examples/resources](https://github.com/gravitational/teleport/tree/master/examples/resources)
-  directory in the Teleport Github repository for examples of possible connectors.
-- You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch the entity descriptor from
-  your IDP. Though, we recommend "pinning" the entity descriptor by including the XML rather than fetching from a URL.
+</TabItem>
+<TabItem label="OneLogin">
+
+```yaml
+(!/examples/resources/onelogin-connector.yaml!)
+```
+
+</TabItem>
+<TabItem label="OIDC">
+
+```yaml
+(!/examples/resources/oidc-connector.yaml!)
+```
+
+</TabItem>
+<TabItem label="Google Workspace">
+
+```yaml
+(!/examples/resources/gworkspace-connector-inline.yaml!)
+```
+
+</TabItem>
+<TabItem label="ADFS">
+
+```yaml
+(!/examples/resources/adfs-connector.yaml!)
+```
+
+</TabItem>
+<TabItem label="SAML">
+
+```yaml
+(!/examples/resources/saml-connector.yaml!)
+```
+
+</TabItem>
+</Tabs>
+
+
+You may use `entity_descriptor_url`, in lieu of `entity_descriptor`, to fetch
+the entity descriptor from your IDP. 
+
+We recommend "pinning" the entity descriptor by including the XML rather than
+fetching from a URL.
+
+Create the connector: 
+
+```code
+$ tctl create -f connector.yaml
+```
 
 ### User Logins
 
 Often it is required to restrict SSO users to their unique UNIX logins when they
-connect to Teleport nodes. To support this:
+connect to Teleport Nodes. To support this:
 
-- Use the SSO provider to create a field called *"unix_login"* (you can use another name).
-- Make sure it's exposed as a claim via SAML/OIDC.
-- Update a Teleport SSH role to include `{{external.unix_login}}` variable into the list of allowed logins:
+- Use the SSO provider to create a field called `unix_login` (you can use another name).
+- Make sure the `unix_login` field is exposed as a claim via SAML/OIDC.
+- Update a Teleport role to include the `{{external.unix_login}}` variable in the list of allowed logins:
 
 ```yaml
 kind: role
@@ -203,10 +253,10 @@ At this time, the `spec.provider` field should not be set for any other identity
 ## Working with External Email Identity
 
 Along with sending groups, an SSO provider will also provide a user's email address.
-In many organizations, the username that a person uses to log into a system is the
-same as the first part of their email address - the 'local' part. For example, `dave.smith@acme.com` might log in with the username `dave.smith`. Teleport provides an easy way to extract the first part of an email address so it can be used as a username - this is the `{{email.local}}` function.
+In many organizations, the username that a person uses to log in to a system is the
+same as the first part of their email address, the "local" part. For example, `dave.smith@acme.com` might log in with the username `dave.smith`. Teleport provides an easy way to extract the first part of an email address so it can be used as a username. This is the `{{email.local}}` function.
 
-If the email claim from the identity provider (which can be accessed via `{{external.email}}`) is sent and contains an email address, you can extract the 'local' part of the email address before the @ sign like this: `{{email.local(external.email)}}`
+If the email claim from the identity provider (which can be accessed via `{{external.email}}`) is sent and contains an email address, you can extract the "local" part of the email address before the @ sign like this: `{{email.local(external.email)}}`
 
 Here's how this looks in a Teleport role:
 

diff --git a/docs/pages/enterprise/sso/adfs.mdx b/docs/pages/enterprise/sso/adfs.mdx
@@ -40,7 +40,9 @@ like:
 
 - Teleport role with access to maintaining `saml` resources.  This is available in the default `editor` role.
 
-(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!)
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
+
+(!docs/pages/includes/tctl.mdx!)
 
 (!docs/pages/includes/enterprise/samlauthentication.mdx!)
 

diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx
@@ -40,8 +40,9 @@ Before you get started you’ll need:
 - To create at least two security groups in Azure AD and assign one or more users to each group
 - Teleport role with access to maintaining `saml` resources.  This is available in the default `editor` role.
 
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
-(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!)
+(!docs/pages/includes/tctl.mdx!)
 
 (!docs/pages/includes/enterprise/samlauthentication.mdx!)
 

diff --git a/docs/pages/enterprise/sso/gitlab.mdx b/docs/pages/enterprise/sso/gitlab.mdx
@@ -39,10 +39,9 @@ like:
 - At least two groups in GitLab with users assigned.
 - Teleport role with access to maintaining `oidc` resources.  This is available in the default `editor` role.
 
-(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!)
-
-(!docs/pages/includes/sso/tctlconnection.mdx!)
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
 
+(!docs/pages/includes/tctl.mdx!)
 
 ## Enable default OIDC authentication
 

diff --git a/docs/pages/enterprise/sso/google-workspace.mdx b/docs/pages/enterprise/sso/google-workspace.mdx
@@ -42,7 +42,9 @@ Before you get started you’ll need:
 - Ability to set up Google Workspace groups.
 - Teleport role with access to maintaining `oidc` resources.  This is available in the default `editor` role.
 
-(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!)
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
+
+(!docs/pages/includes/tctl.mdx!)
 
 ## Step 1/4. Enable default OIDC authentication
 

diff --git a/docs/pages/enterprise/sso/oidc.mdx b/docs/pages/enterprise/sso/oidc.mdx
@@ -35,9 +35,11 @@ administrators to define policies like:
 ## Prerequisites
 
 - Admin access to the SSO/IdP being integrated with users assigned to groups/roles.
-- Teleport role with access to maintaining `oidc` resources.  This is available in the default `editor` role.
+- Teleport role with access to maintaining `oidc` resources. This is available in the default `editor` role.
 
-(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!)
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
+
+(!docs/pages/includes/tctl.mdx!)
 
 ## Enable default OIDC authentication
 

diff --git a/docs/pages/enterprise/sso/okta.mdx b/docs/pages/enterprise/sso/okta.mdx
@@ -39,7 +39,9 @@ like:
 - Okta account with admin access. Your account must include users and at least two groups.
 - Teleport role with access to maintaining `saml` resources.  This is available in the default `editor` role.
 
-(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!)
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
+
+(!docs/pages/includes/tctl.mdx!)
 
 (!docs/pages/includes/enterprise/samlauthentication.mdx!)
 

diff --git a/docs/pages/enterprise/sso/one-login.mdx b/docs/pages/enterprise/sso/one-login.mdx
@@ -37,7 +37,9 @@ like:
 - One Login account with admin access and users assigned to at least two groups.
 - Teleport role with access to maintaining `saml` resources.  This is available in the default `editor` role.
 
-(!docs/pages/includes/enterprise/ent-user-prereqs.mdx!)
+(!docs/pages/includes/commercial-prereqs-tabs.mdx!)
+
+(!docs/pages/includes/tctl.mdx!)
 
 (!docs/pages/includes/enterprise/samlauthentication.mdx!)
 

diff --git a/docs/pages/includes/edition-prereqs-tabs.mdx b/docs/pages/includes/edition-prereqs-tabs.mdx
@@ -9,7 +9,7 @@ files in partials, this partial uses relative URL paths instead.
 - A running Teleport cluster. For details on how to set this up, see one of our
   [Getting Started](/docs/getting-started) guides. 
 
-- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=) on a Desktop or administrative access on the Teleport Auth Service machine.
+- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=).
 
   ```code
   $ tctl version
@@ -24,26 +24,39 @@ files in partials, this partial uses relative URL paths instead.
 </TabItem>
 <TabItem
   scope={["enterprise"]} label="Enterprise">
-- Installed Enterprise version of Teleport (downloaded via the [Enterprise dashboard](https://dashboard.gravitational.com/web/login)).
-- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=) on a Desktop or administrative access on the Teleport Auth Service machine.
-You can download these by visiting the
+
+- A running Teleport cluster. For details on how to set this up, see our Enterprise
+  [Getting Started](/docs/enterprise/getting-started) guide.
+
+- The `tctl` admin tool and `tsh` client tool version >= (=teleport.version=),
+  which you can download by visiting the
   [customer portal](https://dashboard.gravitational.com/web/login).
+
   ```code
   $ tctl version
   # Teleport v(=teleport.version=) go(=teleport.golang=)
+
+  $ tsh version
+  # Teleport v(=teleport.version=) go(=teleport.golang=)
   ```
+
 </TabItem>
 <TabItem scope={["cloud"]}
   label="Teleport Cloud">
-- Teleport Cloud account (sign up for a [free trial](https://goteleport.com/signup)).
 
-- The `tctl` admin client version >= (=cloud.version=).
+- A Teleport Cloud account. If you do not have one, visit the
+  [sign up page](https://goteleport.com/signup/) to begin your free trial.
 
-  You can download this from [Teleport Cloud Downloads](/docs/cloud/downloads).
+- The `tctl` admin tool and `tsh` client tool version >= (=cloud.version=).
+  To download these tools, visit the [Downloads](/docs/cloud/downloads) page.
 
   ```code
   $ tctl version
   # Teleport v(=cloud.version=) go(=teleport.golang=)
+
+  $ tsh version
+  # Teleport v(=cloud.version=) go(=teleport.golang=)
   ```
+
 </TabItem>
-</Tabs>
+</Tabs>