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
`{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}`
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
+`{{external["http://schemas.microsoft.com/ws/2008/06/identity/claims/windowsaccountname"]}}`
+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 9015e320f7ce..cea87e934d43 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: