diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx
index 8ee92d2386702..75c569e2d969e 100644
--- a/docs/pages/enterprise/sso.mdx
+++ b/docs/pages/enterprise/sso.mdx
@@ -227,8 +227,10 @@ SAML and OIDC types:
Troubleshooting SSO configuration can be challenging. Usually a Teleport administrator
must be able to:
+
- Ensure that HTTP/TLS certificates are configured properly for both Teleport
proxy and the SSO provider.
+
- Be able to see what SAML/OIDC claims and values are getting exported and passed
by the SSO provider to Teleport.
- Be able to see how Teleport maps the received claims to role mappings as defined
@@ -237,5 +239,55 @@ must be able to:
If something is not working, we recommend to:
- Double-check the host names, tokens and TCP ports in a connector definition.
-- Look into Teleport's audit log for claim mapping problems. It is usually stored on the
- auth server in the `/var/lib/teleport/log` directory.ad
+
+### Using the Web UI
+
+If you get "access denied" or other login errors, the number one place to check is the Audit
+Log. You can access it in the **Activity** tab of the Teleport Web UI.
+
+
+
+Example of a user being denied because the role `clusteradmin` wasn't set up:
+
+```json
+{
+ "code": "T1001W",
+ "error": "role clusteradmin is not found",
+ "event": "user.login",
+ "method": "oidc",
+ "success": false,
+ "time": "2019-06-15T19:38:07Z",
+ "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"
+}
+```
+
+### Teleport does not show the expected Nodes
+
+When Teleport's Auth Service receives a request to list Teleport Nodes,
+it only returns the Nodes that a user is authorized to access.
+
+A user's Teleport roles must grant the user explicit access to Nodes with a particular label
+ before the user can view those Nodes. The Auth Service compares the user's
+`traits.logins` with the `allow` and `deny` rules defined in each of the user's roles.
+If the user's logins match a role's `allow` and `deny` rules, and a Node's labels match
+the keys and values listed within a role's `node_labels` field, then the Auth Service will
+list the Node in response to the user's request.
+
+When configuring SSO, ensure that the identity provider is populating each user's
+traits correctly. For a user to see a Node in Teleport, the result of populating a
+ 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
+kind: role
+metadata:
+ name: example-role
+spec:
+ allow:
+ logins: ['{{external.logins}}', ubuntu, debian]
+ node_labels:
+ 'env': 'dev'
+version: v5
+```
diff --git a/docs/pages/includes/sso/loginerrortroubleshooting.mdx b/docs/pages/includes/sso/loginerrortroubleshooting.mdx
index d294b001d4360..39e98fbc6d4ab 100644
--- a/docs/pages/includes/sso/loginerrortroubleshooting.mdx
+++ b/docs/pages/includes/sso/loginerrortroubleshooting.mdx
@@ -1,10 +1,7 @@
-
-
-
### Using the Web UI
If you get "access denied" or other login errors, the number one place to check is the Audit
-Log on the Teleport Auth Server. You can access it in the **Activity** tab of the Teleport Web UI.
+Log. You can access it in the **Activity** tab of the Teleport Web UI.
@@ -21,63 +18,32 @@ Example of a user being denied because the role `clusteradmin` wasn't set up:
"uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"
}
```
-
-### On the Auth Service host
-You can monitor Audit Log file entries and process logs on the Teleport Auth Server.
-The Audit Log is located in `/var/lib/teleport/log` by
-default and it will contain a detailed reason why a user's login was denied.
-
-
- If you are using a Teleport storage configuration that does not store log entries locally, this will not appear. You can look at the `teleport`
-process logs to see `ERROR` and `INFO` entries.
-
-
-Example of a user being denied because the role `clusteradmin` wasn't set up:
-
-
-```json
-{
- "code": "T1001W",
- "error": "role clusteradmin is not found",
- "event": "user.login",
- "method": "oidc",
- "success": false,
- "time": "2019-06-15T19:38:07Z",
- "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"
-}
-```
-
-Some errors (like filesystem permissions or a misconfigured network) can be
-diagnosed using Teleport's `stderr` log, which is usually available via:
-
-```code
-$ sudo journalctl -fu teleport
-```
-
-If you wish to increase the verbosity of Teleport's logs, you can pass the
-[`--debug`](../../setup/reference/cli.mdx#teleport-start) flag to the `teleport start` command.
-
-
-If you get "access denied" or other login errors, the number one place to check is the Audit
-Log on the Teleport Auth Server. You can access it in the **Activity** tab of the Teleport Web UI.
-
-
-
-Example of a user being denied because the role `clusteradmin` wasn't set up:
-
-```json
-{
- "code": "T1001W",
- "error": "role clusteradmin is not found",
- "event": "user.login",
- "method": "oidc",
- "success": false,
- "time": "2019-06-15T19:38:07Z",
- "uid": "cd9e45d0-b68c-43c3-87cf-73c4e0ec37e9"
-}
+### Teleport does not show the expected Nodes
+When Teleport's Auth Service receives a request to list Teleport Nodes,
+it only returns the Nodes that a user is authorized to access.
+
+A user's Teleport roles must grant the user explicit access to Nodes with a particular label
+ before the user can view those Nodes. The Auth Service compares the user's
+`traits.logins` with the `allow` and `deny` rules defined in each of the user's roles.
+
+If the user's logins match a role's `allow` and `deny` rules, and a Node's labels match
+the keys and values listed within a role's `node_labels` field, then the Auth Service will
+list the Node in response to the user's request.
+
+When configuring SSO, ensure that the identity provider is populating each user's
+traits correctly. For a user to see a Node in Teleport, the result of populating a
+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
+kind: role
+metadata:
+ name: example-role
+spec:
+ allow:
+ logins: ['{{external.logins}}', ubuntu, debian]
+ node_labels:
+ 'env': 'dev'
+version: v5
```
-
-