diff --git a/docs/pages/admin-guides/access-controls/sso/adfs.mdx b/docs/pages/admin-guides/access-controls/sso/adfs.mdx
index b75d19bc9b37..d65c7e22bce0 100644
--- a/docs/pages/admin-guides/access-controls/sso/adfs.mdx
+++ b/docs/pages/admin-guides/access-controls/sso/adfs.mdx
@@ -130,9 +130,10 @@ The login
 <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.
+attribute and use that field as an allowed login for each user. Since the name
+of the attribute contains characters besides letters, numbers, and underscores,
+you must use double quotes (`"`) and square brackets (`[]`) around the name of
+the attribute.
 
 ## Step 3/3. Create a SAML connector
 
diff --git a/docs/pages/admin-guides/access-controls/sso/azuread.mdx b/docs/pages/admin-guides/access-controls/sso/azuread.mdx
index 3d488c583bcd..44cd2ba25d8f 100644
--- a/docs/pages/admin-guides/access-controls/sso/azuread.mdx
+++ b/docs/pages/admin-guides/access-controls/sso/azuread.mdx
@@ -173,10 +173,7 @@ $ tctl create -f azure-connector.yaml
 Create a Teleport role resource that will use external username data from the
 Azure AD connector to determine which Linux logins to allow on a host.
 
-Users with the following `dev` role are only allowed to log in to nodes with
-the `access: relaxed` Teleport label. They can log in as either `ubuntu` or a
-username that is passed in from the Azure AD connector. Users with this role can't
-obtain admin access to Teleport.
+Create a file called `dev.yaml` with the following content:
 
 ```yaml
 kind: role
@@ -187,12 +184,27 @@ spec:
   options:
     max_session_ttl: 24h
   allow:
-    logins: [ "{{external.username}}", ubuntu ]
+    # only allow login as either ubuntu or the 'windowsaccountname' claim
+    logins: [ '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}', ubuntu ]
     node_labels:
       access: relaxed
 ```
 
-Replace `ubuntu` with the Linux login available on your servers.
+Users with the `dev` role are only allowed to log in to nodes with the `access:
+relaxed` Teleport label. They can log in as either `ubuntu` or a username that
+is passed in from the Azure AD connector using the `windowsaccountname`
+attribute.
+
+The login
+<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`
+attribute and use that field as an allowed login for each user. Since the name
+of the attribute contains characters besides letters, numbers, and underscores,
+you must use double quotes (`"`) and square brackets (`[]`) around the name of
+the attribute.
+
+Create the role:
 
 ```code
 $ tctl create dev.yaml
diff --git a/docs/pages/reference/access-controls/roles.mdx b/docs/pages/reference/access-controls/roles.mdx
index 267c8c03057b..48737637e555 100644
--- a/docs/pages/reference/access-controls/roles.mdx
+++ b/docs/pages/reference/access-controls/roles.mdx
@@ -558,7 +558,6 @@ logins:
    - '{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}'
 ```
 
-
 In role templates, you can refer to these variables using the following two
 formats, where `trait` is the name of the trait:
 
@@ -570,7 +569,14 @@ attribute or OIDC claim called `trait`.
 
 You can specify an external trait in dot syntax if it begins with a letter and
 contains only letters, numbers, and underscores. Otherwise, you must use bracket
-syntax to specify a trait.
+syntax to specify a trait. 
+
+When using Azure AD or ADFS as your IdP, you must use bracket notation, as these
+IdPs assign attribute keys to URLs such as the following:
+
+```text
+http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname
+```
 
 Common examples of external traits available through an identity provider
 include the following: