Skip to main content
Version: 14.x

Access Controls for Servers

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

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: drop (remove user on session end), keep (keep users at session end)
    #          and off (disable host user creation)
    create_host_user_mode: drop
    # 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: login@github.com
       value: "{{ external.github_login }}"