Teleport

Getting Started With Access Controls

In Teleport, any local, SSO, or robot user can be assigned one or several roles. Roles govern access to databases, SSH servers, Kubernetes clusters, Windows desktops, and web apps.

We will start with local users and preset roles, assign roles to SSO users, and wrap up with creating your own role.

Prerequisites

A running Teleport cluster version 17.0.0-dev or above. If you want to get started with Teleport, sign up for a free trial or set up a demo environment.
The tctl admin tool and tsh client tool.

Visit Installation for instructions on downloading tctl and tsh.

To check that you can connect to your Teleport cluster, sign in with tsh login, then verify that you can run tctl commands using your current credentials. For example:
```
tsh login --proxy=teleport.example.com --user=email@example.com
tctl status
Cluster  teleport.example.com
Version  17.0.0-dev
CA pin   sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
```
If you can connect to the cluster and run the tctl status command, you can use your current credentials to run subsequent tctl commands from your workstation. If you host your own Teleport cluster, you can also run tctl commands on the computer that hosts the Teleport Auth Service for full permissions.

When running Teleport in production, you should adhere to the following best practices to avoid security incidents:

Avoid using sudo in production environments unless it's necessary.
Create new, non-root, users and use test instances for experimenting with Teleport.
Run Teleport's services as a non-root user unless required. Only the SSH Service requires root access. Note that you will need root permissions (or the CAP_NET_BIND_SERVICE capability) to make Teleport listen on a port numbered < 1024 (e.g. 443).
Follow the principle of least privilege. Don't give users permissive roles when more a restrictive role will do. For example, don't assign users the built-in access,editor roles, which give them permissions to access and edit all cluster resources. Instead, define roles with the minimum required permissions for each user and configure access requests to provide temporary elevated permissions.
When you enroll Teleport resources—for example, new databases or applications—you should save the invitation token to a file. If you enter the token directly on the command line, a malicious user could view it by running the history command on a compromised system.

You should note that these practices aren't necessarily reflected in the examples used in documentation. Examples in the documentation are primarily intended for demonstration and for development environments.

Step 1/3. Add local users with preset roles

Teleport provides several preset roles:

Role	Description	Enterprise-only
`access`	Allows access to cluster resources.
`editor`	Allows editing of cluster configuration settings.
`auditor`	Allows reading cluster events, audit logs, and playing back session records.
`requester`	Allows a user to create Access Requests.	✔
`reviewer`	Allows review of Access Requests.	✔
`group-access`	Allows access to all user groups.	✔
`device-admin`	Used to manage trusted devices.	✔
`device-enroll`	Used to grant device enrollment powers to users.	✔
`require-trusted-device`	Requires trusted device access to resources.	✔
`terraform-provider`	Allows the Teleport Terraform provider to configure all of its supported Teleport resources.	✔

Invite the local user Alice as cluster editor:

tctl users add alice --roles=editor

Invite the local user Alice as cluster editor and reviewer:

tctl users add alice --roles=editor,reviewer

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

tctl users ls

User                 Roles
-------------------- --------------
alice                editor, reviewer

You can update the user's roles using the 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

Once Alice logs back in, she will be able to view audit logs
tctl users update alice --set-roles=editor,reviewer,auditor

Because Alice has two or more 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

Next, follow the instructions to set up an authentication connector that maps users within your SSO solution to Teleport roles.

Teleport Enterprise

Create a SAML or OIDC application that Teleport can integrate with, then create an authentication connector that maps users within your application to Teleport roles.

Follow our SAML Okta Guide to create a SAML application.

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
metadata:
  name: okta
spec:
  acs: https://tele.example.com/v1/webapi/saml/acs
  attributes_to_roles:
  - {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

Create the saml resource:

tctl create okta.yaml

Follow our OIDC guides to create an OIDC application.

Copy the YAML below to a file called oidc.yaml and edit the information to include the details of your OIDC application.

kind: oidc
metadata:
  name: oidc_connector
spec:
  claims_to_roles:
  - claim: groups
    roles:
    - access
    value: users
  - claim: groups
    roles:
    - editor
    value: admins
  client_id: <CLIENT-NAME>
  client_secret: <CLIENT-SECRET>
  issuer_url: https://idp.example.com/
  redirect_url: https://mytenant.teleport.sh:443/v1/webapi/oidc/callback
  max_age: 24h
  client_redirect_settings:
    # a list of hostnames allowed for HTTPS client redirect URLs
    # can be a regex pattern
    allowed_https_hostnames:
      - remote.machine
      - '*.app.github.dev'
      - '^\d+-[a-zA-Z0-9]+\.foo.internal$'
    # a list of CIDRs allowed for HTTP or HTTPS client redirect URLs
    insecure_allowed_cidr_ranges:
      - '192.168.1.0/24'
      - '2001:db8::/96'
version: v3

Create the oidc resource:

tctl create okta.yaml

Teleport Community Edition

Save the file below as github.yaml and update the fields. You will need to set up a GitHub OAuth 2.0 Connector app. Any member belonging to the GitHub organization octocats and on team admin will be able to assume the built-in role access.

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_roles:
    - organization: octocats # GitHub organization name
      team: admin            # GitHub team name within that organization
      # map github admin team to Teleport's "access" role
      roles: ["access"]

Create the github resource:

tctl create github.yaml

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: v7
metadata:
  name: interns
spec:
  allow:
    # Logins configures SSH login principals
    logins: ['readonly']
    # Assigns users with this role to the 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'
    kubernetes_resources:
      - kind: *
        namespace: "*"
        name: "*"
        verbs: ["*"]
    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'
    kubernetes_resources:
      - kind: "namespace"
        name: "prod"
    db_labels:
      'env': 'prod'
    app_labels:
      'env': 'prod'

Create a role using the tctl create -f command:

tctl create -f /tmp/interns.yaml
Get a list of all roles in the system
tctl get roles --format text

The Teleport Access Platform

Featured Resource

Integrations

Featured Resource

Use Cases

Featured Resource

Industries

Featured Resource

Compliance

Featured Resource

Strategic Partners

Featured AWS Webinar

Read

Experience

Discover

Featured Blog Post

Company

Explore

Featured Event

Getting Started With Access Controls

Prerequisites

Step 1/3. Add local users with preset roles

Step 2/3. Map SSO users to roles

Teleport Enterprise

Teleport Community Edition

Step 3/3. Create a custom role

Next steps