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 elevated privileges to make following each step easier.

We recommend you follow the best practices to avoid security incidents:

  1. Avoid using sudo in production environments unless it's necessary.
  2. Create new, non-root, users and use test instances for experimenting with Teleport.
  3. You can run many Teleport's services as a non root. For example, auth, proxy, application access, kubernetes access, and database access services can run as a non-root user. Only the SSH/node service requires root access. You will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443)
  4. Follow the "Principle of Least Privilege" (PoLP) and "Zero Admin" best practices. Don't give users permissive roles when giving them more restrictive access,editor roles will do instead.
  5. Save tokens into a file rather than sharing tokens directly as strings.

Verify that your Teleport client is connected:

$ tctl status

# Cluster
# Version  8.0.7
# 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
$ tctl status

Step 1/3. Add local users with preset roles

Teleport provides several preset roles: 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.

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

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"]

Follow SAML Okta Guide to create a SAML app. Check out OIDC guides for OpenID Connect apps. Save the file below as okta.yaml and update the acs field. Any member in Okta group okta-admin will assume a built-in role admin.

kind: saml
version: v2
  name: okta
  - {name: "groups", value: "okta-admin", roles: ["access"]}
  entity_descriptor: |
    <?xml !!! Make sure to shift all lines in XML descriptor
    with 4 spaces, otherwise things will not work

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?