Skip to main content

Configure SSH with Pluggable Authentication Modules

Teleport's SSH Service can be configured to integrate with Pluggable Authentication Modules (PAM).

Teleport currently supports the auth, account, and session PAM modules. The auth stack is optional and not used by default.

These are a few things leverage PAM for:

  • Create a custom Message of the Day (MOTD)
  • Create local Unix users on login
  • Add authentication steps

Introduction to Pluggable Authentication Modules​

Background​

Pluggable Authentication Modules (PAM) date back to 1995 when Sun Microsystems implemented a generic authentication framework for Solaris. Since then most GNU/Linux distributions have adopted PAM.

$ man pam

The Pluggable Authentication Modules (PAM) library abstracts several common authentication-related operations and provides a framework for dynamically loaded modules that implement these operations in various ways.

Terminology​

In PAM parlance, the application that uses PAM to authenticate a user is the server, and is identified for configuration purposes by a service name, which is often (but not necessarily) the program name.

The user requesting authentication is called the applicant, while the user (usually, root) charged with verifying their identity and granting them the requested credentials is called the arbitrator.

The sequence of operations the server goes through to authenticate a user and perform whatever task they requested is a PAM transaction. The context within which the server performs the requested task is called a session.

The functionality embodied by PAM is divided into four facilities: authentication, account management, session management, and password management.

Teleport currently supports account management and session management.

Set up PAM on a Linux Machine running Teleport​

Best practices for production security

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.

Warning

Backing up production instances, environments, and/or settings before making permanent modifications is encouraged as a best practice. Doing so allows you to roll back to an existing state if needed.

To enable PAM on a Linux machine, update /etc/teleport.yaml with:

ssh_service:
  # Enabled SSH Service
  enabled: true
  # Enable PAM integration
  pam:
    # "no" by default
    enabled: true
    # use /etc/pam.d/sshd configuration (the default)
    service_name: "sshd"
    # use the "auth" modules in the PAM config
    # "false" by default
    # use_pam_auth: false

Please note that most Linux distributions come with several PAM services in /etc/pam.d, and Teleport will try to use /etc/pam.d/sshd by default. This file will be removed if you uninstall the openssh-server package. We recommend creating your own PAM service file like /etc/pam.d/teleport and specifying it as service_name above.

Get and set environment variables for PAM modules​

Teleport supports setting arbitrary environment variables for PAM modules as of version 6.1. These variables can also be role-style SSO claims in the form {{ external.email }}, where email is a claim made by the configured SSO IdP.

To set custom environment variables, update /etc/teleport.yaml with:

ssh_service:
  enabled: true
  pam:
    # disabled by default
    enabled: true
    # use /etc/pam.d/sshd configuration (the default)
    service_name: "sshd"
    # use the "auth" modules in the PAM config
    # "false" by default
    use_pam_auth: true
    # sets custom environment variables for PAM modules
    environment:
      FOO: "bar"
      EMAIL: "{{ external.email }}"

Teleport can also read PAM environment variables from the PAM handle, an opaque data structure that is used by PAM to store state. These variables include:

  • TELEPORT_USERNAME: The Teleport username of the user who is logging into a Node. This is usually an email address (such as user@example.com) if using SAML/OIDC identities with Teleport Enterprise, or a more standard exampleuser if using local Teleport users.
  • TELEPORT_LOGIN: The name of the Linux/Unix username that the Teleport user assumes when logging into the Teleport Node, e.g., root, developer, ubuntu, ec2-user,or similar.
  • TELEPORT_ROLES: A space-separated list of Teleport roles which the Teleport user has, e.g., developer tester access.

Display a Message of the Day (MOTD) with Teleport​

A cluster-wide Message of the Day can be set in the auth_service configuration.

auth_service:
    message_of_the_day: "Welcome to the cluster. All activity will be logged."

This will be shown during the tsh login process, and must be positively acknowledged before the user is allowed to log in to the cluster.

$ tsh login --proxy teleport.example.com
# Welcome to the cluster. All activity will be logged.
# Press [ENTER] to continue.

Alternatively, a per-Node Message of the Day can be set using the traditional Unix /etc/motd file. The /etc/motd file is normally displayed by login(1) after a user has logged in but before the shell is run. It is generally used for important system-wide announcements.

This feature can help you inform users that activity on the Node is being audited and recorded.

The default sshd PAM configuration will call two pam_motd files, one dynamic MOTD that prints the machine info, and a static MOTD that can be set by an admin.

session    optional     pam_motd.so  motd=/run/motd.dynamic
session    optional     pam_motd.so noupdate

By updating /etc/motd you can provide a message to users accessing Nodes via Teleport.

$ cat /etc/motd
# WARNING: All activity on this node is being recorded by Teleport

Teleport SSH with updated MOTD

Create local Unix users on login​

warning

Using PAM to create local users on login is obsolete and will be removed in a future version. Refer to the Host user creation guide to learn how to configure Teleport to automatically create local Linux users without PAM.

Teleport has the ability to create local Unix users on login. This is very helpful if you're a large organization and want to provision local users and home directories on the fly.

Using pam_exec.so is the easiest way to use the PAM stack to create a user if the user does not already exist. pam_exec.so usually ships with the operating system.

You can either add pam_exec.so to the existing PAM stack for your application or write a new one for Teleport. In this example, we'll write a new one to simplify how to use pam_exec.so with Teleport.

Start by creating a file called /etc/pam.d/teleport with the following contents:

account   required   pam_exec.so /etc/pam-exec.d/teleport_acct
session   required   pam_motd.so
session   required   pam_permit.so
note

Pay attention to the inclusion of pam_motd.so under the session facility. While pam_motd.so is not required for user creation, Teleport requires at least one module to be set under both the account and session facilities for it to work.

Next, create a script that will be run by pam_exec.so.

Create a directory where you will store the script:

$ mkdir -p /etc/pam-exec.d

In /etc/pam-exec.d, add a file called teleport_acct with the following content:

#!/bin/sh
COMMENT="User ${TELEPORT_LOGIN} for ${TELEPORT_USERNAME} with roles ${TELEPORT_ROLES} created by Teleport."
/bin/id -u "${TELEPORT_LOGIN}" > /dev/null 2>&1 || /sbin/useradd -m -s /bin/bash -c "${COMMENT}" "${TELEPORT_LOGIN}" 2>> /tmp/pam.error
exit 0

Ensure that your script is executable:

$ chmod +x /etc/pam-exec.d/teleport_acct

This script will check if the login assigned to TELEPORT_LOGIN exists and, if it does not, it will create it. Any error from useradd will be written to /tmp/pam.error.

The environment variables TELEPORT_USERNAME and TELEPORT_ROLES can be used to write richer scripts that may change the system in other ways based on identity information.

note

The useradd command can have a different path than the example above depending on your Linux distribution. Adjust to your particular system as needed depending on the result of the following command:

$ which useradd

Next, update /etc/teleport.yaml to call the above PAM stack by both enabling PAM and setting the service_name.

ssh_service:
  enabled: true
  pam:
    enabled: true
    service_name: "teleport"

Now attempting to log in as an existing user should result in the creation of the user and a successful login.

The /etc/pam-exec.d/teleport_acct script can set the user's groups as an option to auto-populate the user's permissions. The user's roles are populated as space-delimited TELEPORT_ROLES variables. These could be used to map to a particular sudo group with additional scripting.

Add authentication steps​

By using the PAM auth modules, it is possible to add authentication steps during user login. These can include passwords, second authentication factor, or even biometrics.

Note that Teleport enables strong SSH authentication out of the box using certificates. For most users, hardening the initial Teleport authentication (e.g. tsh login) is preferred.

By default, auth modules are not used to avoid the default system behavior (usually using local Unix passwords). You can enable them by setting use_pam_auth in the pam section of your teleport.yaml.

ssh_service:
  enabled: true
  pam:
    enabled: true
    # use /etc/pam.d/sshd configuration (the default)
    service_name: "sshd"
    # use the "auth" modules in the PAM config
    use_pam_auth: true