From 8c2ced7e2bd14e6456b2eedf55c3b92a9242396e Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Thu, 23 Jun 2022 13:22:56 -0400 Subject: [PATCH] Add context to "tsh ls" in docs (#12583) * Add context to "tsh ls" in docs Fixes #7051 - Create a partial for how the Teleport Auth Service filters Nodes based on user roles/logins in response to queries. - Add the partial to provide context for example commands that include "tsh ls". - Make our existing text on Teleport's authorization checks clearer by enumerating the checks in the order they are executed in services.RoleSet.CheckAccess. Note that this does not change guides that instruct the user to create a new user and role, since a user following these guides will see the correct "tsh ls" output. * Respond to PR feedback --- docs/pages/cloud/getting-started.mdx | 6 ++++++ docs/pages/enterprise/getting-started.mdx | 12 +++++++++--- docs/pages/enterprise/sso.mdx | 11 +---------- docs/pages/includes/node-logins.mdx | 17 +++++++++++++++++ .../includes/sso/loginerrortroubleshooting.mdx | 10 +--------- docs/pages/machine-id/getting-started.mdx | 6 ++++++ docs/pages/machine-id/guides/ansible.mdx | 6 ++++++ docs/pages/server-access/guides/tsh.mdx | 6 ++++++ docs/pages/setup/reference/cli.mdx | 6 ++++++ 9 files changed, 58 insertions(+), 22 deletions(-) create mode 100644 docs/pages/includes/node-logins.mdx diff --git a/docs/pages/cloud/getting-started.mdx b/docs/pages/cloud/getting-started.mdx index ee3621ef045ec..86c7d8db5e9c9 100644 --- a/docs/pages/cloud/getting-started.mdx +++ b/docs/pages/cloud/getting-started.mdx @@ -60,6 +60,12 @@ $ tsh ls $ tsh ssh root@myserver ``` +
+ +(!docs/pages/includes/node-logins.mdx!) + +
+ Type exit to end this session. Happy Teleporting! ## Next Steps diff --git a/docs/pages/enterprise/getting-started.mdx b/docs/pages/enterprise/getting-started.mdx index bc37037956f1a..8a3cc345bd0d1 100644 --- a/docs/pages/enterprise/getting-started.mdx +++ b/docs/pages/enterprise/getting-started.mdx @@ -325,16 +325,22 @@ store it in `~/.tsh/keys/` directory. With a certificate in place, Joe can now interact with the Teleport cluster: ```code -# SSH into any host behind the proxy (Unix user 'joe' should already exist on the node): -$ tsh ssh joe@node.example.com - # See what hosts are available behind the proxy: $ tsh ls +# SSH into any host behind the proxy (Unix user 'joe' should already exist on the node): +$ tsh ssh joe@node.example.com + # Log out (this will remove the user certificate from ~/.tsh) $ tsh logout ``` +
+ +(!docs/pages/includes/node-logins.mdx!) + +
+ ## Configuring SSO The local account is good for administrative purposes but regular users of diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx index bd36dd414ddf5..a1864fc9d6970 100644 --- a/docs/pages/enterprise/sso.mdx +++ b/docs/pages/enterprise/sso.mdx @@ -382,22 +382,13 @@ Example of a user being denied because the role `clusteradmin` wasn't set up: ### 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. +(!docs/pages/includes/node-logins.mdx!) 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 diff --git a/docs/pages/includes/node-logins.mdx b/docs/pages/includes/node-logins.mdx new file mode 100644 index 0000000000000..b46e29eb54eae --- /dev/null +++ b/docs/pages/includes/node-logins.mdx @@ -0,0 +1,17 @@ +When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to +display Nodes in the Web UI or via `tsh ls`), it only returns the Nodes that the +current user is authorized to view. + +For each Node in the user's Teleport cluster, the Auth Service applies the +following checks in order and, if one check fails, hides the Node from the user: + +- None of the user's roles contain a `deny` rule that matches the Node's labels. +- None of the user's roles contain a `deny` rule that matches the user's login. +- At least one of the user's roles contains an `allow` rule that matches the + Node's labels. +- At least one of the user's roles contains an `allow` rule that matches the + user's login. + +If you are not seeing Nodes when expected, make sure that your user's roles +include the appropriate `allow` and `deny` rules as documented in the +[Teleport Access Controls Reference](../access-controls/reference.mdx). \ No newline at end of file diff --git a/docs/pages/includes/sso/loginerrortroubleshooting.mdx b/docs/pages/includes/sso/loginerrortroubleshooting.mdx index c7744f79347a2..6aa4aef8f656f 100644 --- a/docs/pages/includes/sso/loginerrortroubleshooting.mdx +++ b/docs/pages/includes/sso/loginerrortroubleshooting.mdx @@ -37,15 +37,7 @@ Example of a user being denied because the role `clusteradmin` wasn't set up: ### 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. +(!docs/pages/includes/node-logins.mdx!) 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 diff --git a/docs/pages/machine-id/getting-started.mdx b/docs/pages/machine-id/getting-started.mdx index 340c8d74776aa..b50dfec040c33 100644 --- a/docs/pages/machine-id/getting-started.mdx +++ b/docs/pages/machine-id/getting-started.mdx @@ -274,6 +274,12 @@ Node Name Address Labels node-name 127.0.0.1:3022 arch=x86_64,group=api-servers ``` +
+ +(!docs/pages/includes/node-logins.mdx!) + +
+ To use Machine ID with the OpenSSH integration, run the following command to connect to `node-name` within cluster `example.com`. diff --git a/docs/pages/machine-id/guides/ansible.mdx b/docs/pages/machine-id/guides/ansible.mdx index 98173c582972a..dfdcfbe2795c3 100644 --- a/docs/pages/machine-id/guides/ansible.mdx +++ b/docs/pages/machine-id/guides/ansible.mdx @@ -76,6 +76,12 @@ $ # Replace ".example.com" below with the name of your cluster. $ tsh ls --format=json | jq -r '.[].spec.hostname + ".example.com"' > hosts ``` +
+ +(!docs/pages/includes/node-logins.mdx!) + +
+ ## Step 2/2. Run a playbook Finally, let's create a simple Ansible playbook, `playbook.yaml`. diff --git a/docs/pages/server-access/guides/tsh.mdx b/docs/pages/server-access/guides/tsh.mdx index 94e35da254675..a1d4b7c4acc51 100644 --- a/docs/pages/server-access/guides/tsh.mdx +++ b/docs/pages/server-access/guides/tsh.mdx @@ -414,6 +414,12 @@ $ tsh ls os=osx [CLI Docs -tsh ls](../../setup/reference/cli.mdx#tsh-ls) +
+ +(!docs/pages/includes/node-logins.mdx!) + +
+ ## Interactive shell To launch an interactive shell on a remote Node or to execute a command, use diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx index 9a8cd4c3336a8..bc030f6258cfe 100644 --- a/docs/pages/setup/reference/cli.mdx +++ b/docs/pages/setup/reference/cli.mdx @@ -405,6 +405,12 @@ List cluster nodes: $ tsh ls [] [