Teleport
Pluggable Authentication Modules (PAM)
- Version 17.x
- Version 16.x
- Version 15.x
- Version 14.x
- Older Versions
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
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.
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. 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[email protected]
) if using SAML/OIDC identities with Teleport Enterprise, or a more standardexampleuser
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.comWelcome 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.
You can set a per-Node Message of the Day 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/motdWARNING: All activity on this node is being recorded by Teleport
Create local Unix users on login
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
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.
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