![Fork me on GitHub](/docs/_next/image/?url=%2Fdocs%2F_next%2Fstatic%2Fmedia%2Fforkme.b9234619.webp&w=256&q=75)
Teleport
Access Controls for Servers
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
You can use Teleport's role-based access control (RBAC) system to set up granular permissions for authenticating to Linux servers connected to Teleport.
An example of a policy could be, Server administrators have access to everything, the QA team and engineers have full access to staging servers, and engineers can gain temporary access to production servers in case of emergency.
For a more general description of Teleport roles and examples see our Access Controls guides, as this section focuses on configuring RBAC for servers connected to Teleport.
Role configuration
Teleport's "role" resource provides the following instruments for restricting server access:
kind: role
version: v5
metadata:
name: developer
spec:
allow:
# The logins array defines the OS/UNIX logins a user is allowed to use.
# both strings and template variables are supported in this field
logins: [ubuntu, debian, '{{internal.logins}}']
# node_labels: a user with this role will be allowed to connect to
# SSH nodes whose labels match any of the expressions below.
node_labels:
# literal strings:
'env': 'test'
# the wildcard ('*') means "any node"
'*': '*'
# a list of allowed values:
'region': ['us-west-1', 'eu-central-1']
# regular expressions start with ^ and end with $
# Teleport uses Go's regexp syntax (https://github.com/google/re2/wiki/Syntax)
# the list example above can be expressed as:
'reg': '^us-west-1|eu-central-1$'
# List of host groups the created user will be added to. Any that don't
# already exist are created. Only applies when create_host_user_mode
# is not 'off'.
host_groups: [ubuntu, nginx, other]
# Assign the user to the sudoers group
host_sudoers:
- 'ALL=(ALL) NOPASSWD: ALL'
# Deny access to the root user
deny:
logins:
- root
Deny rules will match greedily. In the example above, a server session attempting to use the "root" server user account will be rejected.
Template variables
Similar to role fields for accessing other resources in Teleport, server-related fields support template variables.
Variables with the format {{external.xyz}}
are replaced with values from external SSO
providers. For OIDC logins, {{external.xyz}}
refers to the "xyz" claim; for
SAML logins, {{external.xyz}}
refers to the "xyz" assertion.
For example, here is what a role may look like if you want to assign allowed
server environment types and allowed logins from the user's Okta environments
and
allowedlogins
assertions:
spec:
allow:
node_labels:
- env: '{{external.environments}}'
logins:
- '{{external.allowedlogins}}'
The {{internal.logins}}
variable applies to local users
and works with Teleport trusted clusters. Trusted clusters allow
connecting from a root Teleport cluster to resources connected to other Teleport clusters.
Those Teleport clusters, identified as leaf clusters, allow the connection
by trusting the root Teleport cluster.
For example, suppose a user in the root cluster has the following role. As a
local user they could have the logins
trait of jeff
so they have two logins, jeff
and ubuntu
.
spec:
allow:
logins: ['{{internal.logins}}', ubuntu]
The role on the leaf cluster can be set up to use the user's allowed server
accounts and names. The leaf cluster will then include the same logins allowed from the root
cluster when the {{internal.logins}}
template variable is used.
spec:
allow:
logins: ["{{internal.logins}}"]
For full details on how variable expansion works in Teleport roles, see the Teleport Access Controls Reference.
Server role options
The allow
and deny
sections described above are used for controlling
the servers and logins allowed. Role options provide the Teleport features
available for users with the specified role. These options apply to Server access.
spec:
allow:
#....
options:
# Controls whether this role supports auto provisioning of users.
# Options: keep (keep users at session end), insecure-drop (remove user on session end),
# and off (disable host user creation)
create_host_user_mode: keep
# forward_agent controls whether SSH agent forwarding is allowed
forward_agent: true
# port_forwarding controls whether TCP port forwarding is allowed for SSH
port_forwarding: true
# ssh_file_copy controls whether file copying (SCP/SFTP) is allowed.
# Defaults to true.
ssh_file_copy: false
# client_idle_timeout determines if SSH sessions to cluster nodes are
# forcefully terminated after no activity from a client (idle client).
# It overrides the global cluster setting. examples: "30m", "1h" or "1h30m"
client_idle_timeout: never
# Determines if the clients will be forcefully disconnected when their
# certificates expire in the middle of an active session.
# It overrides the global cluster setting.
disconnect_expired_cert: no
# max_sessions is total number of session channels that can be established
# across a single connection. Setting it to 10 matches OpenSSH default behavior.
max_sessions: 10
# Defines which events are recorded by the BPF-based session recorder.
enhanced_recording:
- command
- disk
- network
# permit_x11_forwarding allows users to use X11 forwarding with openssh
# clients and servers through the proxy
permit_x11_forwarding: true
# The Enterprise-only max_connections field sets a limit of concurrent sessions within a
# cluster. This setting slows down Teleport performance because it has to track
# connections cluster-wide.
max_connections: 2
# Define how Teleport deals with session recording failures, such as a full
# disk error. The value can be set to either `best_effort` or `strict`. If
# set to `strict`, the session will terminate immediately. If set to
# `best_effort`, the session won’t be terminated, and the recording will be
# disabled. The configuration is done per service (currently, only `ssh` is
# supported).
record_session:
# Optional: the default session recording mode to use when a
# protocol-specific mode is not set.
default: best_effort|strict
# Optional: Session recording mode for SSH sessions.
# If not set, the value set on default will be used.
ssh: best_effort|strict
# Require an additional MFA tap to start new sessions.
# Optional: the default is false.
require_session_mfa: true
# Enterprise-only: when enabled, the source IP that was used to log in is embedded in the user
# certificates, preventing a compromised certificate from being used on another
# network. The default is false.
pin_source_ip: true
# Specify a list of names and associated values to be included in user SSH keys.
# The key type can only be "ssh" and the mode can only be "extension".
# The name and value fields can be arbitrary strings and the value field
# supports variable interpolation.
cert_extensions:
- type: ssh
mode: extension
name: [email protected]
value: "{{ external.github_login }}"