Update SSO guides to take into account new commands: tctl sso test, tctl sso configure.

docs/config.json

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

docs/pages/enterprise/sso.mdx

@@ -1,11 +1,11 @@
 ---
-title: SSO for SSH
-description: How to set up single sign-on (SSO) for SSH using Teleport
-h1: Single Sign-On (SSO) for SSH
+title: SSO in Teleport
+description: How to configure Teleport Single Sign-On
+h1: Single Sign-On in Teleport
 ---
 
 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,64 +93,139 @@ 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. We recommend the usage of helper 
+commands to achieve this for [SAML](../setup/reference/cli.mdx#tctl-sso-configure-saml), 
+ [OIDC](../setup/reference/cli.mdx#tctl-sso-configure-oidc) and 
+ [GitHub](../setup/reference/cli.mdx#tctl-sso-configure-github) connectors. 
+ The resulting file `connector.yaml` should be similar to 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!)
+```
+
+</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!)
 ```
 
-- See [examples/resources](https://github.com/gravitational/teleport/tree/master/examples/resources)
-  directory in the Teleport Github repository for examples of possible connectors.
+</TabItem>
+</Tabs>
+
+Note:
+- Manually pasting the XML to `entity_descriptor` field is error prone. We recommend using `tctl sso configure saml -e entity_descriptor.xml ...` command instead.
 - 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.
 
+Test the connector with [`tctl sso test`](../setup/reference/cli.mdx#tctl-sso-test) command:
+
+```bsh
+$ tctl sso test connector.yaml
+```
+
+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
@@ -179,10 +260,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:
 
@@ -236,13 +317,14 @@ SAML and OIDC types:
 
 ## SSO Customization
 
-| Provider | YAML | Example |
-| - | - | - |
-| Github | `display: Github` | ![github](../../img/teleport-sso/github@2x.png) |
+| Provider  | YAML                 | Example                                               |
+|-----------|----------------------|-------------------------------------------------------|
+| Github    | `display: Github`    | ![github](../../img/teleport-sso/github@2x.png)       |
 | Microsoft | `display: Microsoft` | ![microsoft](../../img/teleport-sso/microsoft@2x.png) |
-| Google | `display: Google` | ![google](../../img/teleport-sso/google@2x.png) |
+| Google    | `display: Google`    | ![google](../../img/teleport-sso/google@2x.png)       |
 | BitBucket | `display: Bitbucket` | ![bitbucket](../../img/teleport-sso/bitbucket@2x.png) |
-| OpenID | `display: Okta` | ![Okta](../../img/teleport-sso/openId@2x.png) |
+| OpenID    | `display: Okta`      | ![Okta](../../img/teleport-sso/openId@2x.png)         |
+
 
 ## Troubleshooting
 
@@ -260,8 +342,10 @@ must be able to:
 
 If something is not working, we recommend to:
 
+- Run the connector definition through [`tctl sso test`](../setup/reference/cli.mdx#tctl-sso-test) command.
 - Double-check the host names, tokens and TCP ports in a connector definition.
-
+- Double-check the role mapping in connector definition for possible typos.
+- Verify the configuration on IdP side (callback URLs, claim names, scopes, ...).
 
 ### Using the Web UI