Prereqs for tctl and enterprise, cloud flow (#12998)

docs/config.json

@@ -53,7 +53,7 @@
           "slug": "/setup/admin/",
           "entries": [
             {
-              "title": "Github SSO",
+              "title": "GitHub SSO",
               "slug": "/setup/admin/github-sso/"
             },
             {

docs/pages/enterprise/sso.mdx

@@ -1,62 +1,90 @@
 ---
 title: SSO for SSH
-description: How to set up single sign-on (SSO) for SSH using Gravitational Teleport
+description: How to set up single sign-on (SSO) for SSH using Teleport
 h1: Single Sign-On (SSO) for SSH
 ---
 
-Users of the Enterprise edition of Teleport can login with SSH, Kubernetes, Databases and Web applications
-through a Single Sign-On (SSO) provider used the rest of the organization.
+Users of the Enterprise edition of Teleport can log in to servers, Kubernetes
+clusters, databases, web applications, and Windows desktops through their
+organization's Single Sign-On (SSO) provider.
+
+<ScopedBlock scope="oss">
+<TileSet>
+    <Tile 
+    icon="bolt"
+    title="Use SSO with Teleport Cloud"
+    href="./sso.mdx/?scope=cloud"
+  >
+    Learn how to use Teleport's SSO integrations in Teleport Cloud.
+    </Tile>
+    <Tile 
+    icon="bolt"
+    title="Use SSO with Teleport Enterprise"
+    href="./sso.mdx/?scope=enterprise"
+  >
+    Learn how to use Teleport's SSO integrations in Teleport Enterprise.
+    </Tile>
+  </TileSet>
+</ScopedBlock>
+
+<ScopedBlock scope={["enterprise", "cloud"]}>
 
 <TileSet>
   <Tile icon="bolt" title="Azure Active Directory (AD)" href="./sso/azuread.mdx">
-    Configure Azure Active Directory SSO for SSH, Kubernetes, Database and Web apps.
+    Configure Azure Active Directory SSO for SSH, Kubernetes, databases, desktops and web apps.
   </Tile>
   <Tile icon="bolt" title="Active Directory (ADFS)" href="./sso/adfs.mdx">
-    Configure Windows Active Directory SSO for SSH, Kubernetes, Database and Web apps.
+    Configure Windows Active Directory SSO for SSH, Kubernetes, databases, desktops and web apps.
   </Tile>
   <Tile icon="bolt" title="Google Workspace" href="./sso/google-workspace.mdx">
-    Configure Gsuite SSO for SSH, Kubernetes, Database and Web apps.
+    Configure Google Workspace SSO for SSH, Kubernetes, databases, desktops and web apps.
   </Tile>
   <Tile icon="bolt" title="GitLab" href="./sso/gitlab.mdx">
-    Configure Gitlab SSO for SSH, Kubernetes, Database and Web apps.
+    Configure GitLab SSO for SSH, Kubernetes, databases, desktops and web apps.
   </Tile>
   <Tile icon="bolt" title="OneLogin" href="./sso/one-login.mdx">
-    Configure OneLogin SSO for SSH, Kubernetes, Database and Web apps.
+    Configure OneLogin SSO for SSH, Kubernetes, databases, desktops and web apps.
   </Tile>
   <Tile icon="bolt" title="OIDC" href="./sso/oidc.mdx">
-    Configure OIDC SSO for SSH, Kubernetes, Database and Web apps.
+    Configure OIDC SSO for SSH, Kubernetes, databases, desktops and web apps.
   </Tile>
   <Tile icon="bolt" title="Okta" href="./sso/okta.mdx">
-    Configure Okta SSO for SSH, Kubernetes, Database and Web apps.
+    Configure Okta SSO for SSH, Kubernetes, databases, desktops and web apps.
   </Tile>
 </TileSet>
 
 ## 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:
-$ tsh login --proxy=proxy.example.com
+```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.
@@ -65,64 +93,132 @@ 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
 
-- Update `/etc/teleport.yaml` on the auth server to set the default
-  authentication connector.
-- 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`.
+Before you can create an authentication connector, you must enable
+authentication via that connector's protocol.
 
-```yaml
-# snippet from /etc/teleport.yaml on the auth server:
-auth_service:
-    # defines the default authentication connector type:
+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)" 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
+      type: saml|oidc
+  ```
+  </TabItem>
+  <TabItem scope={["cloud"]} label="Dynamic Resources (All Editions)">
+  Create a file called `cap.yaml`:
+  ```yaml
+  kind: cluster_auth_preference
+  metadata:
+    name: cluster-auth-preference
+  spec:
     authentication:
-        type: saml
+      # 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>
+
+
+Next, define an authentication connector. Create a file called `connector.yaml`
+based on one of the following examples.
+
+<Tabs>
+<TabItem label="Okta">
+
+```yaml
+(!/examples/resources/okta-connector.yaml!)
 ```
 
-An example of a connector:
+</TabItem>
+<TabItem label="OneLogin">
 
 ```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/onelogin-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="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
@@ -157,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, `[email protected]` 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, `[email protected]` 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:
 
@@ -240,6 +336,7 @@ If something is not working, we recommend to:
 
 - Double-check the host names, tokens and TCP ports in a connector definition.
 
+
 ### Using the Web UI
 
 If you get "access denied" or other login errors, the number one place to check is the Audit
@@ -278,6 +375,7 @@ traits correctly. For a user to see a Node in Teleport, the result of populating
  template variable in a role's `allow.logins` must match at least one of a user's
  `traits.logins`.
 
+
 In this example a user will have usernames `ubuntu`, `debian` and usernames from the SSO trait `logins` for Nodes that have a `env: dev` label.  If the SSO trait username is `bob` then the usernames would include `ubuntu`, `debian`, and `bob`.
 
 ```yaml
@@ -291,3 +389,4 @@ spec:
       'env': 'dev'
 version: v5
 ```
+</ScopedBlock>

docs/pages/enterprise/sso/adfs.mdx

@@ -4,7 +4,7 @@ description: How to configure SSH access with Active Directory Federation Servic
 h1: Single Sign-On with Active Directory Federation Services
 ---
 
-This guide will cover how to configure Active Directory Federation Services
+This guide will explain how to configure Active Directory Federation Services
 ([ADFS](https://en.wikipedia.org/wiki/Active_Directory_Federation_Services)) to be
 a single sign-on (SSO) provider to issue
 SSH credentials to specific groups of users. When used in combination with role
@@ -15,12 +15,33 @@ like:
 - Developers must never SSH into production servers.
 - ... and many others.
 
-<Admonition
-  type="warning"
-  title="Version Warning"
+<ScopedBlock
+  scope={["oss"]}
 >
-  This guide requires a commercial edition of Teleport.
-</Admonition>
+
+  This guide requires Teleport Cloud or Teleport Enterprise.
+
+  View this guide as the user of another Teleport edition:
+
+  <TileSet>
+  <Tile icon="cloud" title="Teleport Cloud" href="./adfs.mdx/?scope=cloud">
+  </Tile>
+  <Tile icon="building" title="Teleport Enterprise" href="./adfs.mdx/?scope=enterprise">
+  </Tile>
+  </TileSet>
+
+</ScopedBlock>
+
+<ScopedBlock scope={["cloud", "enterprise"]}>
+
+## Prerequisites
+
+- ADFS installation 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/commercial-prereqs-tabs.mdx!)
+
+(!docs/pages/includes/tctl.mdx!)
 
 (!docs/pages/includes/enterprise/samlauthentication.mdx!)
 
@@ -186,3 +207,5 @@ automatically in a browser.
 ## Troubleshooting
 
 (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!)
+
+</ScopedBlock>