Docs: Update ADFS SSO guide

docs/pages/access-controls/sso.mdx

@@ -453,7 +453,7 @@ flow. These provider-specific changes can be enabled by setting the
 values to match your identity provider:
 
 - `adfs` (SAML): Required for compatibility with Active Directory (ADFS); refer
-  to the full [ADFS guide](./sso/adfs.mdx#create-teleport-roles) for details.
+  to the full [ADFS guide](./sso/adfs.mdx#step-23-create-teleport-roles) for details.
 - `netiq` (OIDC): Used to enable NetIQ-specific ACR value processing; refer to
   the [OIDC guide](./sso/oidc.mdx#optional-acr-values) for details.
 - `ping` (SAML and OIDC): Required for compatibility with Ping Identity (including

docs/pages/access-controls/sso/adfs.mdx

@@ -1,15 +1,14 @@
 ---
 title: SSO with Active Directory Federation Services
-description: How to configure SSH access with Active Directory Federation Services using Teleport
+description: How to configure Teleport access with Active Directory Federation Services
 h1: Single Sign-On with 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
-based access control (RBAC), it allows SSH administrators to define policies
-like:
+a single sign-on (SSO) provider to issue login credentials to specific groups
+of users. When used in combination with role based access control (RBAC), it
+allows Teleport administrators to define policies like:
 
 - Only members of "DBA" group can SSH into machines running PostgreSQL.
 - Developers must never SSH into production servers.
@@ -23,42 +22,49 @@ like:
 
 - (!docs/pages/includes/tctl.mdx!)
 
-(!docs/pages/includes/enterprise/samlauthentication.mdx!)
-
-## Configure ADFS
+## Step 1/3. Configure ADFS
 
 You'll need to configure ADFS to export claims about a user (Claims Provider
 Trust in ADFS terminology) and you'll need to configure ADFS to trust
 Teleport (a Relying Party Trust in ADFS terminology).
 
-For Claims Provider Trust configuration, you'll need to specify at least the
-following two incoming claims: `Name ID` and `Group`. `Name ID` should be a
-mapping of the LDAP Attribute `E-Mail-Addresses` to `Name ID`. A group
-membership claim should be used to map users to roles (for example to
-separate normal users and admins).
+For Claims Provider Trust configuration, open the **AD FS** management window.
+Under **Claims Provider Trusts**, right-click on **Active Directory** and
+select **Edit Claim Rules**. You'll need to specify at least the following two
+incoming claims: `Name ID` and `Group`.
+
+- `Name ID` should be a mapping of the LDAP Attribute `E-Mail-Addresses` to
+  `Name ID`.
+
+  ![Name ID Configuration](../../../img/adfs-1.png)
+
+- A group membership claim should be used to map users to roles (for example to
+  separate normal users and admins).
 
-![Name ID Configuration](../../../img/adfs-1.png)
-![Group Configuration](../../../img/adfs-2.png)
+  ![Group Configuration](../../../img/adfs-2.png)
 
-In addition, if you are using dynamic roles (see below), it may be useful to map
-the LDAP Attribute `SAM-Account-Name` to `Windows account name` and create
-another mapping of `E-Mail-Addresses` to `UPN`.
+- If you are using dynamic roles (see below), it may be useful to map the LDAP
+  Attribute `SAM-Account-Name` to `Windows account name`:
 
-![WAN Configuration](../../../img/adfs-3.png)
-![UPN Configuration](../../../img/adfs-4.png)
+  ![WAN Configuration](../../../img/adfs-3.png)
+
+- And create another mapping of `E-Mail-Addresses` to `UPN`:
+
+  ![UPN Configuration](../../../img/adfs-4.png)
 
 You'll also need to create a Relying Party Trust. Use the below information to
-help guide you through the Wizard. Note that for development purposes we recommend
-using `https://localhost:3080/v1/webapi/saml/acs` as the Assertion Consumer
-Service (ACS) URL, but for production you'll want to change this to a domain
-that can be accessed by other users as well.
+help guide you through the Wizard.
 
-- Create a claims aware trust.
+- Create a Relaying Party Trust:
+  ![Add a Claims Provider Trust](../../../img/adfs-add-provider-trust.png)
 - Enter data about the relying party manually.
 - Set the display name to something along the lines of `Teleport`.
 - Skip the token encryption certificate.
-- Select *"Enable support for SAML 2.0 Web SSO protocol"* and set the URL to `https://localhost:3080/v1/webapi/saml/acs`.
-- Set the relying party trust identifier to `https://localhost:3080/v1/webapi/saml/acs` as well.
+- Select *"Enable support for SAML 2.0 Web SSO protocol"* and set the URL to
+  `https://teleport.example.com/v1/webapi/saml/acs`, replacing the domain name
+  with your Teleport proxy URL.
+- Set the relying party trust identifier to
+  `https://teleport.example.com/v1/webapi/saml/acs` as well.
 - For access control policy select *"Permit everyone"*.
 
 Once the Relying Party Trust has been created, update the Claim Issuance Policy
@@ -72,7 +78,7 @@ associated with it. To check this open Server Manager then
 *"Tools -> Active Directory Users and Computers"* and select the user and right
 click and open properties. Make sure the email address field is filled out.
 
-## Create Teleport roles
+## Step 2/3. Create Teleport roles
 
 Let's create two Teleport roles: one for administrators and the other for
 normal users. You can create them using the `tctl create {file name}` CLI command
@@ -121,17 +127,24 @@ This role declares:
   re-configure the Teleport cluster.
 
 The login
-`{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}`
+<nobr>`{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}`</nobr>
 configures Teleport to look at the
 `http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname`
 ADFS claim and use that field as an allowed login for each user. Note the
 double quotes (`"`) and square brackets (`[]`) around the claim name—these are
 important.
 
-Next, create a SAML connector [resource](../../reference/resources.mdx):
+## Step 3/3. Create a SAML connector
 
-```yaml
-(!examples/resources/adfs-connector.yaml!)
+Create a SAML connector resource using `tctl`:
+
+```code
+$ tctl sso configure saml --acs https://teleport.example.com/v1/webapi/saml/acs \
+  --preset adfs \
+  --entity-descriptor https://adfs.example.com/FederationMetadata/2007-06/FederationMetadata.xml \
+  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,Administrators,editor \
+  --attributes-to-roles http://schemas.xmlsoap.org/claims/Group,Users,access \
+  > adfs.yaml
 ```
 
 The `acs` field should match the value you set in ADFS earlier and you can
@@ -143,19 +156,27 @@ name is `http://schemas.xmlsoap.org/claims/Group` with a value of *"admins"*
 to the *"admin"* role. Groups with the value *"users"* is being mapped to the
 *"users"* role.
 
-## Export the signing key
+You can test this connector before applying it (`cat adfs.yaml | tctl sso test`),
+but until we complete the next step the authentication process will not complete.
+
+Apply the connector:
+
+```code
+$ tctl create -f adfs.yaml
+```
+
+### Export the signing key
 
 For the last step, you'll need to export the signing key:
 
 ```code
-$ tctl saml export adfs
+$ tctl saml export adfs > saml.cer
 ```
 
-Save the output to a file named `saml.crt`, return back to ADFS, open the
-"Relying Party Trust" and add this file as one of the signature verification
-certificates.
+Copy `saml.cer`, to ADFS server, open the "Relying Party Trust" and add this
+file as one of the signature verification certificates:
 
-## Testing
+![adfs-add-teleport-cert.png](../../../img/adfs-add-teleport-cert.png)
 
 The Web UI will now contain a new button: "Login with MS Active Directory". The CLI is
 the same as before:
@@ -175,6 +196,8 @@ automatically in a browser.
   can be passed via `tsh login --auth=connector_name`
 </Admonition>
 
+(!docs/pages/includes/enterprise/samlauthentication.mdx!)
+
 ## Troubleshooting
 
 (!docs/pages/includes/sso/loginerrortroubleshooting.mdx!)