Getting Started With Access Controls
In Teleport, any local, SSO, or robot user can be a member of one or several roles. Roles govern access to databases, SSH servers, kubernetes clusters, and web apps.
We will start with local users and preset roles, map SSO users to roles and wrap up with creating your own role.
The examples below may include the use of the
sudo keyword, token UUIDs, and users with
admin privileges to make following each step easier when creating resources from scratch.
- We discourage using
sudoin production environments unless it's needed.
- We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
- We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the
adminrole when giving them the more restrictive
access,editorroles will do instead.
- Saving tokens into a file rather than sharing tokens directly as strings.
Learn more about Teleport Role-Based Access Control best practices.
Verify that your Teleport client is connected:
$ tctl status # Cluster tele.example.com # Version 7.1.3 # CA pin sha256:sha-hash-here
To try this flow in the cloud, login into your cluster using tsh, then use tctl remotely:
$ tsh login --proxy=myinstance.teleport.sh $ tctl status
Teleport provides a several preset roles:
Members of the
editor role can modify cluster configuration, members of
role can view audit logs, and
access members can access cluster resources.
admin, are full cluster administrators.
Invite a local user Alice as cluster
tctl users add alice --roles=editor
Once Alice signs up, she will be able to edit cluster configuration. You can list
users and their roles using
tctl users ls.
tctl users ls
[email protected] admin
You can update user's roles using
tctl users update command:
Once Alice logs back in, she will be able to view audit logstctl users update alice --set-roles=editor,auditor
Because Alice has two roles, permissions from those roles create a union - she will be able to act as a system administrator and auditor at the same time.
We're now going to set up a GitHub connector for Teleport Open Source Edition and Okta for Teleport Enterprise Edition.
Save the file below as
github.yaml and update the fields. You will need to set up
Github OAuth 2.0 Connector app.
Any member belonging to the Github organization
octocats and on team
admin will be able to assume a built-in role
kind: github version: v3 metadata: # connector name that will be used with `tsh --auth=github login` name: github spec: # client ID of Github OAuth app client_id: client-id # client secret of Github OAuth app client_secret: client-secret # This name will be shown on UI login screen display: Github # Change tele.example.com to your domain name redirect_url: https://tele.example.com:443/v1/webapi/github/callback # Map github teams to teleport roles teams_to_logins: - organization: octocats # Github organization name team: admin # Github team name within that organization # map github admin team to Teleport's "access" role logins: ["access"]
Let's create a custom role for interns. Interns will have access
to test or staging SSH servers as
readonly users. We will let them
view some monitoring web applications and dev kubernetes cluster.
Save this role as
kind: role version: v4 metadata: name: interns spec: allow: # Logins configures SSH login principals logins: ['readonly'] # Assigns members of this role to built-in kubernetes group view kubernetes_groups: ["view"] # Allow access to SSH nodes, kubernetes clusters, apps or databases labeled with staging or test node_labels: 'env': ['staging', 'test'] kubernetes_labels: 'env': 'dev' app_labels: 'type': ['monitoring'] # The deny rules always override allow rules. deny: # deny access to any node, database, app or kubernetes cluster labeled # as prod as any user. node_labels: 'env': 'prod' kubernetes_labels: 'env': 'prod' db_labels: 'env': 'prod' app_labels: 'env': 'prod'
Create a role using
tctl create -f command:
tctl create -f /tmp/interns.yaml
Get a list of all roles in the systemtctl get roles --format text