[v9] Includes Audit Log into common sso Troubleshooting (#12565)

* Includes Audit Log into common sso Troubleshooting
gravitational · May 12, 2022 · adf6b39 · adf6b39
1 parent b76add8
commit adf6b39
Show file tree

Hide file tree

Showing 2 changed files with 83 additions and 65 deletions.
diff --git 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:
 
+<ScopedBlock scope={["oss","enterprise"]}>
 - Ensure that HTTP/TLS certificates are configured properly for both Teleport
   proxy and the SSO provider.
+</ScopedBlock>
 - 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.
+
+![Audit Log Entry for SSO Login error](../../img/sso/teleportauditlogssofailed.png)
+
+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
@@ -1,10 +1,7 @@
-<Tabs>
-<TabItem label="Self-Hosted" scope={["oss","enterprise"]}>
-
 ### 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.
 
 ![Audit Log Entry for SSO Login error](../../../img/sso/teleportauditlogssofailed.png)
 
@@ -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.
-
-<Admonition
-  type="Note"
-  title="Note"
->
-  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.
-</Admonition>
-
-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.
-</TabItem>
-<TabItem label="Teleport Cloud" scope={["cloud"]}>
-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.
-
-![Audit Log Entry for SSO Login error](../../../img/sso/teleportauditlogssofailed.png)
-
-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
 ```
-</TabItem>
-</Tabs>