# 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. 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

**Self-Hosted**

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.

**Teleport Enterprise Cloud**

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/motd
WARNING: All activity on this node is being recorded by Teleport
```

![Teleport SSH with updated MOTD](/docs/assets/images/teleport-with-updated-MOTD-6744e7751fd3e0725e707f6cb27a2270.png)

## Create local Unix users on login

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. If you do not already use the PAM stack, you may alternatively use Teleport's built in support for [automatically provisioning users](https://goteleport.com/docs/ver/17.x/enroll-resources/server-access/guides/host-user-creation.md).

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](https://goteleport.com/docs/ver/17.x/reference/access-controls/authentication.md) (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

```