Fork me on GitHub

Getting Started With Access Controls

Getting Started

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.


  1. We discourage using sudo in production environments unless it's needed.
  2. We encourage creating new, non-root, users or new test instances for experimenting with Teleport.
  3. We encourage adherence to the Principle of Least Privilege (PoLP) and Zero Admin best practices. Don't give users the admin role when giving them the more restrictive access,editor roles will do instead.
  4. 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
# Version  7.1.3
# CA pin   sha256:sha-hash-here
Connecting to the cloud

To try this flow in the cloud, login into your cluster using tsh, then use tctl remotely:

$ tsh login
$ tctl status

Step 1/3. Add local users with preset roles

Teleport provides a several preset roles: admin, editor, auditor and access. Members of the editor role can modify cluster configuration, members of auditor role can view audit logs, and access members can access cluster resources. Members of admin, are full cluster administrators.

Invite a local user Alice as cluster editor:

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

User Roles

-------------------- --------------

alice editor

[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 logs

tctl 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.

Step 2/3. Map SSO users to roles

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 access.

kind: github
version: v3
  # connector name that will be used with `tsh --auth=github login`
  name: github
  # 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 to your domain name
  # Map github teams to teleport roles
    - organization: octocats # Github organization name
      team: admin            # Github team name within that organization
      # map github admin team to Teleport's "access" role
      logins: ["access"]

Step 3/3. Create a custom role

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 interns.yaml:

kind: role
version: v4
  name: interns
    # 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
      'env': ['staging', 'test']
      'env': 'dev'
      'type': ['monitoring']
  # The deny rules always override allow rules.
    # deny access to any node, database, app or kubernetes cluster labeled
    # as prod as any user.
      'env': 'prod'
      'env': 'prod'
      'env': 'prod'
      'env': 'prod'

Create a role using tctl create -f command:

tctl create -f /tmp/interns.yaml

Get a list of all roles in the system

tctl get roles --format text

Next steps

Have a suggestion or can’t find something?