
Teleport
Getting Started With Access Controls
- Version 15.x
- Version 14.x
- Version 13.x
- Version 12.x
- Older Versions
- Available for:
- OpenSource
- Team
- Cloud
- Enterprise
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 Teleport Team account. If you don't have an account, sign up to begin your free trial.
-
The Enterprise
tctl
admin tool andtsh
client tool, version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
-
A running Teleport cluster. For details on how to set this up, see the Getting Started guide.
-
The
tctl
admin tool andtsh
client tool version >= 14.0.0.See Installation for details.
-
A running Teleport Enterprise cluster. For details on how to set this up, see the Enterprise Getting Started guide.
-
The Enterprise
tctl
admin tool andtsh
client tool version >= 14.0.0.You can download these tools by visiting your Teleport account workspace.
Please use the latest version of Teleport Enterprise documentation.
To check version information, run the tctl version
and tsh version
commands.
For example:
tctl versionTeleport Enterprise v13.3.9 git:api/14.0.0-gd1e081e go1.21
tsh versionTeleport v13.3.9 go1.21
Proxy version: 13.3.9Proxy: teleport.example.com
- To check that you can connect to your Teleport cluster, sign in with
tsh login
, then verify that you can runtctl
commands on your administrative workstation using your current credentials. For example:If you can connect to the cluster and run thetsh login --proxy=teleport.example.com --user=[email protected]tctl statusCluster teleport.example.com
Version 14.0.0
CA pin sha256:abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678abdc1245efgh5678
tctl status
command, you can use your current credentials to run subsequenttctl
commands from your workstation. If you host your own Teleport cluster, you can also runtctl
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: editor
, auditor
, and access
.
- The
editor
role authorizes users to modify cluster configuration. - The
auditor
role authorizes users to view audit logs. - The
access
role authorizes users to access cluster resources.
Teleport Enterprise contains two additional preset roles: reviewer
and requester
.
- The
reviewer
role authorizes users to review Access Requests. - The
requester
role authorizes users to request 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 lsUser Roles
-------------------- --------------
alice editor
tctl users lsUser 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.
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
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
version: v3
Create the oidc
resource:
tctl create okta.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.yamlGet a list of all roles in the system
tctl get roles --format text