# Linux logon

> Add Ironchip as a second factor on Linux with the PAM module: create the application, install pam_ironchip_auth.so and protect sudo, SSH or login.

URL: https://docs.ironchip.com/en/identidad/integraciones/puestos/linux-logon/

Ironchip integrates with Linux through PAM (Pluggable Authentication Modules) and adds the second factor to services such as `sudo`, SSH or local login. Use this page to create the application, install the module and configure PAM.

## Requirements

- Access to the Ironchip admin console.
- A user with administrator permissions (`root` or `sudo`) on the Linux machine.
- Connectivity from the machine to the Ironchip API (`https://api.ironchip.com`).
- A Linux system with PAM. For macOS, see [macOS logon](https://docs.ironchip.com/en/identidad/integraciones/puestos/macos-logon/).

:::caution[It can lock you out]
An incorrect PAM configuration can leave you without access to the machine. Keep a `root` session open while you test, and start with `sudo` before protecting SSH or login.
:::

## Configure Ironchip

### Create the application

1. Go to **Applications > New application**.

   [Image: Applications section of the console with the button to create a new application]

2. Select the **Linux Logon** integration type.

   [Image: Selecting the Linux Logon integration type]

3. Enter a descriptive name for the application and click **Add**.

   [Image: Application name and Add button]

4. Save the **API key** shown when you create the application. You will need it later.

   [Image: Window with the application API key]

### Give users access

1. Open the application you just created and click the button to add a new access.

   [Image: Application page with the button to add an access]

2. Select the users who will use the service.

   [Image: Selecting the users of the access]

3. Set the username to match the Linux system username.

   [Image: Username equal to the Linux system username]

4. Set the access conditions the user must meet to sign in to the machine.

   [Image: User access conditions]

5. Save the access.

   [Image: Access summary before saving it]

## Configure Linux

### Install the PAM module

1. Optional: install these dependencies, which are only needed in some cases.

   ```bash
   # Debian and Ubuntu
   sudo apt-get install libcurl4-openssl-dev libpam-dev uuid-dev

   # RHEL, AlmaLinux and CentOS
   sudo yum install curl-devel pam-devel libuuid libuuid-devel
   ```

2. Create a folder in a secure location.

   ```bash
   mkdir /usr/local/lib/security
   ```

3. Save the `pam_ironchip_auth.so` file in it. You can find it in the **Plugins** section of the Ironchip console.

   ```bash
   mv pam_ironchip_auth.so /usr/local/lib/security/
   ```

   [Image: The pam_ironchip_auth.so file copied to the secure folder]

### Configure PAM

Go to `/etc/pam.d` and open one of these files in a text editor, depending on your company's needs. File names can vary with the system architecture.

| File           | Protects                              |
| -------------- | ------------------------------------- |
| `sudo`         | Authentication in the `sudo` command. |
| `sshd`         | Authentication in the SSH service.    |
| `gdm-password` | Login to the computer.                |
| `common-auth`  | All the previous services.            |

`gdm-password` handles the graphical login (GNOME Display Manager). `common-auth` centralizes the authentication that services such as `sudo`, `login` or `sshd` import with the `@include common-auth` line.

Add the following line with your data:

```text
auth required <absolute path of pam_ironchip_auth.so> host=https://api.ironchip.com api_key=<API_KEY>
```

Use the API key you saved when you created the application.

### Module parameters

| Parameter           | Required | Description                                                                                                                |
| ------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `host`              | Yes      | URL of the Ironchip identity server, for example `https://api.ironchip.com`.                                               |
| `api_key`           | Yes      | API key of the application, used during authentication.                                                                    |
| `offline_skip`      | No       | With `offline_skip=true`, if there is no connectivity with Ironchip the module is skipped and PAM treats it as successful. |
| `whitelisted_users` | No       | Users separated by `;` who skip the module, for example `whitelisted_users=root;ubuntu`.                                   |

:::caution
`offline_skip` and `whitelisted_users` mean those cases are not asked for the second factor. Use them only when strictly necessary.
:::

### Require the second factor or accept it as sufficient

The verb you use in the `auth` line decides how Ironchip combines with the other PAM modules:

- `required`: the user must pass this module **at least**. Use it to make the second factor mandatory.
- `sufficient`: if the module is passed, PAM ends the authentication successfully right away and ignores the remaining modules.

```text
auth required pam_ironchip_auth.so <options>
auth sufficient pam_ironchip_auth.so <options>
```

## SSH with public key and Ironchip

This configuration requires both the public key and Ironchip as interactive authentication (`keyboard-interactive`).

### Configure sshd_config

1. Open the main SSH configuration file with administrator privileges.

   ```bash
   sudo nano /etc/ssh/sshd_config
   ```

2. Find and adjust these parameters, or add them at the end of the file.

   ```text title="/etc/ssh/sshd_config"
   # Enable keys and disable plain passwords
   PubkeyAuthentication yes
   PasswordAuthentication no

   # Force BOTH: public key + Ironchip (keyboard-interactive)
   AuthenticationMethods publickey,keyboard-interactive

   # Settings required for PAM (Ironchip) to work
   UsePAM yes
   KbdInteractiveAuthentication yes   # Modern Ubuntu/Debian
   ```

3. If your Linux system is not Ubuntu or Debian, also add this line.

   ```text
   ChallengeResponseAuthentication yes
   ```

### Authenticate in SSH without a password

For the SSH server to recognize Ironchip as an interactive authentication method, change the PAM configuration. This way the system validates the identity with Ironchip without also asking for the traditional Linux password.

1. Open the file that manages authentication for the SSH service.

   ```bash
   sudo nano /etc/pam.d/sshd
   ```

2. Add this line at the **top** of the file, so it is the first method evaluated in the interactive phase.

   ```text title="/etc/pam.d/sshd"
   auth sufficient pam_ironchip_auth.so host=https://api.ironchip.com api_key=<API_KEY>
   ```

### Allow the connection with SELinux

The server must make outbound requests to `api.ironchip.com` to validate the identity. On systems with SELinux enabled, such as RHEL, AlmaLinux or CentOS, the SSH service is restricted from using the network by default, and that would block communication with Ironchip.

Import the policy module that allows the SSH process to open network connections.

```bash
semodule -i mi-sshdsession.pp
```

### Apply the changes

Save the files and restart the SSH service.

```bash
# Systems with systemd (Ubuntu, Debian, RHEL 7+)
sudo systemctl restart sshd

# Check the service status
sudo systemctl status sshd
```

With `sufficient`, the SSH client still shows the password prompt. The user can enter any value: it is not validated if Ironchip has already accepted the authentication. To stop the prompt from appearing, add `PermitEmptyPasswords yes` in `/etc/ssh/sshd_config` and restart `sshd`. Do this only if you use the module as a `sufficient` method. If you expect a second factor (MFA), do not change this parameter.

## Verify the integration

1. Keep a `root` session open and open another terminal.
2. Run a command that goes through PAM, for example `sudo -k && sudo ls`.
3. Authorize the access in Ironchip when prompted.
4. If you protected SSH, open a new connection with the user configured in Ironchip and authorize the access.

If something fails, restore the PAM line from the `root` session, which is still open.

Video: [Protecting Linux login with Ironchip](https://play.hubspotvideo.com/v/7745202/id/145633784588)

## Logs

The module writes its logs to `syslog`. View them like this:

```bash
tail -f /var/log/auth.log
```

To filter the graphical login:

```bash
tail -f /var/log/syslog | grep gdm-password
```

## Troubleshooting

**SSH still asks for the Linux password.** Check that `UsePAM yes` is in `/etc/ssh/sshd_config` and restart the service. To avoid the prompt with the `sufficient` method, see [Apply the changes](#apply-the-changes).

**On RHEL, AlmaLinux or CentOS, SSH does not validate with Ironchip.** Import the SELinux policy module from the [Allow the connection with SELinux](#allow-the-connection-with-selinux) section.