Skip to content

Commit

Permalink
Edit two guides for Cloud users
Browse files Browse the repository at this point in the history 
PAM guide

- Minor style/clarity/grammar edits
- Use a ScopedBlock to hide Cloud-irrelevant information in the MOTD
  section
- The organization of the original guide was a bit scrambled, so I
  attempted to reorganize it into a form that made more sense.

Tsh guide

- Use ScopedBlocks to provide scope-relevant information.

- Mention Machine ID in the "### SSH certificates for automation"
  section.

- Misc grammar/clarity/style edits
  • Loading branch information
@ptgott
ptgott committed Apr 5, 2022
1 parent 8a0e59a commit 1d5a391
Show file tree
Hide file tree
Showing 2 changed files with 422 additions and 224 deletions.
232 changes: 96 additions & 136 deletions docs/pages/server-access/guides/ssh-pam.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,19 +4,22 @@ description: How to configure Teleport SSH with PAM (Pluggable Authentication Mo
h1: Pluggable Authentication Modules (PAM)
---

Teleport's node service can be configured to integrate with [PAM](https://en.wikipedia.org/wiki/Linux_PAM).
Teleport's Node 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 additional authentication steps using PAM
- 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.
Expand All @@ -29,23 +32,22 @@ 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**
### Terminology

In PAM parlance, the application that uses PAM to authenticate a user is the server,
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)
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.
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.
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 six primitives grouped into four
facilities: authentication, account management, session management, and password
management.
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.

Expand All @@ -55,7 +57,7 @@ Teleport currently supports account management and session management.

(!docs/pages/includes/backup-warning.mdx!)

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

```yaml
ssh_service:
Expand All @@ -73,42 +75,16 @@ ssh_service:
```

Please note that most Linux distributions come with several PAM services in
`/etc/pam.d` and Teleport will try to use `sshd` by default, which 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.

## Set Message of the Day (motd) with Teleport

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

```yaml
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 into the cluster.

```code
$ 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.
`/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.

## Custom environment variables
## 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.
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:

Expand All @@ -124,84 +100,67 @@ ssh_service:
# "false" by default
use_pam_auth: true
# sets custom environment variables for PAM modules
# no environment variables except the standard `TELEPORT_USERNAME`, `TELEPORT_LOGIN`, and `TELEPORT_ROLES`
environment:
FOO: "bar"
EMAIL: "{{ external.email }}"
```
### Example node with PAM turned off
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:
```yaml
teleport:
nodename: graviton-node-1
auth_token: hello
auth_servers:
- 10.2.1.230:5070
data_dir: /var/lib/teleport
proxy_service:
enabled: false
auth_service:
enabled: false
ssh_service:
enabled: true
# configures PAM integration. see below for more details.
pam:
enabled: false
```
- `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`.

<Figure
align="center"
bordered
caption="Teleport SSH without MOTD"
>
![Teleport SSH without MOTD](../../../img/motd/teleport-no-MOTD.png)
</Figure>
## Display a Message of the Day (MOTD) with Teleport

### Example node with PAM enabled
<ScopedBlock scope={["oss", "enterprise"]}>

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

```yaml
teleport:
nodename: graviton-node-1
auth_token: hello
auth_servers:
- 10.2.1.230:5070
data_dir: /var/lib/teleport
proxy_service:
enabled: false
auth_service:
enabled: false
ssh_service:
enabled: true
# configures PAM integration. see below for more details.
pam:
enabled: true
message_of_the_day: "Welcome to the cluster. All activity will be logged."
```

<Figure
align="center"
bordered
caption="Teleport SSH with MOTD"
>
![Teleport SSH with MOTD](../../../img/motd/teleport-with-MOTD.png)
</Figure>
When PAM is enabled it will use the default `sshd` config file. This can differ per
distro.
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.

```code
$ cat /etc/pam.d/sshd
$ tsh login --proxy teleport.example.com
# Welcome to the cluster. All activity will be logged.
# Press [ENTER] to continue.
```

The default `sshd` 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.
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.

</ScopedBlock>
<ScopedBlock scope={["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.

</ScopedBlock>

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.

```txt
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.
By updating `/etc/motd` you can provide a message to users accessing Nodes via Teleport.

```code
$ cat /etc/motd
Expand All @@ -216,28 +175,13 @@ $ cat /etc/motd
![Teleport SSH with updated MOTD](../../../img/motd/teleport-with-updated-MOTD.png)
</Figure>

## Create local (UNIX) users on login

Teleport has the ability to create local (UNIX) users on login. This is
## 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.

Teleport added the ability to read in PAM environment variables from PAM handle and pass
environment variables to PAM modules: `TELEPORT_USERNAME`, `TELEPORT_LOGIN`, and `TELEPORT_ROLES`.

Here are some details on the contents of these environment variables which will be set by Teleport:

- `TELEPORT_USERNAME`: The Teleport username of the user who is logging into the 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 principal which the Teleport user is logging into the Teleport node as - for example, `root`, `developer`, `ubuntu`, `ec2-user` or similar.
- `TELEPORT_ROLES`: A space-separated list of Teleport roles which the Teleport user has - for example: `developer tester access`.

This PAM module creates the user and home directory before attempting to launch
a shell for said user.

### Examples

**Using pam_exec.so**

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.
Expand All @@ -246,7 +190,7 @@ You can either add `pam_exec.so` to the existing PAM stack for your application
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 `/etc/pam.d/teleport` with the following contents:
Start by creating a file called `/etc/pam.d/teleport` with the following contents:

```txt
account required pam_exec.so /etc/pam-exec.d/teleport_acct
Expand All @@ -255,21 +199,16 @@ session required pam_permit.so
```

<Admonition type="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.
</Admonition>

Next, create the script that will be run by `pam_exec.so` like below. This
script will check if the user passed in `TELEPORT_LOGIN` exists and if it does
not, it will create it. Any error from `useradd` will be written to
`/tmp/pam.error`. Note the additional environment variables
`TELEPORT_USERNAME`, `TELEPORT_ROLES`, and `TELEPORT_LOGIN`. These can be used
to write richer scripts that may change the system in other ways based on
identity information.
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.

<Admonition type="note">
The `useradd` location can have a different path than the example below depending on your linux flavor. Adjust to your particular system as needed from `which useradd` (Ex: `/usr/sbin/useradd` instead of the below example).
</Admonition>

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

```bash
mkdir -p /etc/pam-exec.d
cat > /etc/pam-exec.d/teleport_acct <<EOF
Expand All @@ -281,6 +220,27 @@ EOF
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.

<Admonition type="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:

```code
$ which useradd
```

</Admonition>


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

Expand All @@ -299,11 +259,11 @@ The `/etc/pam-exec.d/teleport_acct` script can set the user's groups as an optio
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 additional authentication steps
## Add authentication steps

By using the PAM `auth` modules, it is possible to add additional authentication
steps during user login. These can include passwords, 2nd factor, or even
biometrics.
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
Expand Down
Loading

0 comments on commit 1d5a391

Please sign in to comment.