Expand documentation of logins / principals on leaf clusters.

benarent commented 4 years ago

Summary

We have a good summary of how trusted clusters work, but when referring to leaf clusters the RBAC UX can be confusing. Teleport always requires the root to have possible principles for a leaf cluster, under https://gravitational.com/teleport/docs/trustedclusters/#rbac we say Both clusters "main" and "east" have their own locally defined roles. but for Trusted Cluster to work correctly it requires the root to have all principles.

E.g.

# root cluster
kind: role
version: v3
metadata:
  name: admin
spec:
  # SSH options used for user sessions with default values:
  options:
    ...
    # logins array defines the OS/UNIX logins a user is allowed to use.
    logins: [root,ec2_user]

# leaf cluster
kind: role
version: v3
metadata:
  name: admin
spec:
  # SSH options used for user sessions with default values:
  options:
    ...
    # The user can now login as `root` and `ec2_user` but NOT `dave` since 
    # this wasn't set in the root cluster RBAC. 
    logins: [dave,"{{internal.logins}}"]

The examples currently don't show unix principles which adds to this confusion.

https://gravitational.com/teleport/docs/admin-guide/#adding-and-deleting-users https://community.gravitational.com/t/what-is-the-difference-between-internal-and-external-variables-in-teleport-templates/159

Audience

Enterprise / RBAC users

Location

Update Trusted Clusters & RBAC Guide

webvictim commented 4 years ago

Teleport always requires the root to have possible principals for a leaf cluster

but for Trusted Cluster to work correctly it requires the root to have all principals.

If these two statements are true then I think this is actually a bug.

kgtw commented 4 years ago

We are currently experiencing this while trialing the enterprise license.

What we have observed is that only principals from the main cluster are exclusively used in the leaf cluster, and the only way to get additional principals on the leaf is to add the principal to the role in the main cluster.

One thing that currently does work with a main/leaf setup is if the leaf role specifies the deny configuration with a principal from the main role, then the leaf will block access for that principal.

The current documentation is somewhat misleading in its current state, if you take a look at the following snippet one would assume that this should work for main/leaf setups.

https://gravitational.com/teleport/docs/enterprise/ssh_rbac/

  # allow section declares a list of resource/verb combinations that are
  # allowed for the users of this role. by default nothing is allowed.
  allow:
    # logins array defines the OS/UNIX logins a user is allowed to use.
    # a few special variables are supported here (see below)
    logins: [root, '{{internal.logins}}']

In most cases {{internal.logins}} will probably be used in a leaf setup to get the base principals for a user. Ideally the leaf role should be able to add additional principals.

gravitational / teleport