---
title: Deploy authentik Agent on Linux
sidebar_label: Linux
tags: [authentik Agent, linux, deploy, packages]
authentik_version: "2025.12.0"
---

import TabItem from "@theme/TabItem";
import Tabs from "@theme/Tabs";

## What it can do

- Retrieves information about the host and reports it to authentik, see [Device Compliance](../../device-compliance/index.mdx).
- SSH to Linux hosts using authentik credentials, see [SSH authentication](../../authentik-agent/device-authentication/ssh-authentication.mdx).
- Authenticate CLI applications using authentik credentials, see [CLI application authentication](../../authentik-agent/device-authentication/cli-app-authentication/index.mdx).

## Prerequisites

You must [configure your authentik deployment](../configuration.md) to support the authentik Agent.

## Create an enrollment token

If you have already created have an enrollment token, skip to the [next section](#install-the-authentik-agent-on-linux).

1. Log in to authentik as an administrator and open the authentik Admin interface.
2. Navigate to **Endpoint Devices** > **Connectors**.
3. Click on the authentik Agent connector that you created when [configuring your authentik deployment](../configuration.md) to support the authentik agent.
4. Under **Enrollment Tokens**, click **New Enrollment Token**, and configure the following settings:
    - **Token name**: provide a descriptive name for the token
    - **Device group _(optional)_**: select a device access group for the device to be added to after completing enrollment
    - **Expiring _(optional)_**: set whether or not the enrollment token will expire
5. Click **Create**.
6. _(Optional)_ Click the **Copy** icon in the **Actions** column to copy the enrollment token. This value will be required if [enabling a device for device compliance](#enable-device-compliance-ssh-server-authentication-and-local-device-login).

## Install the authentik Agent on Linux

Follow these steps to install the authentik Agent on your Linux device:

<Tabs defaultValue="Debian-based">
<TabItem value="Debian-based">

1. Open a Terminal session and install the required GPG key:

```sh
curl -fsSL https://pkg.goauthentik.io/keys/gpg-key.asc | sudo gpg --dearmor -o /usr/share/keyrings/authentik-keyring.gpg
```

2. Add the repository:

```sh
echo "deb [signed-by=/usr/share/keyrings/authentik-keyring.gpg] https://pkg.goauthentik.io stable main" | sudo tee /etc/apt/sources.list.d/authentik.list
```

3. Update your repositories and install the authentik Agent packages:

```sh
sudo apt update
sudo apt install authentik-cli authentik-agent authentik-sysd
```

4. _(optional)_ If you plan to enable [SSH server authentication and local device login](#enable-device-compliance-ssh-server-authentication-and-local-device-login), you will need to install two additional packages:

```sh
sudo apt install libnss-authentik libpam-authentik
```

5. Confirm that the authentik Agent is installed by opening a terminal window and entering the following command: `ak`

    You should see a response that starts with: `authentik CLI v<version_number>`

:::note Headless server
On a headless server, the system agent (sysd) does not start the user agent (ak-agent). You will need to manually start the user agent with this command:

```bash
systemctl start --user ak-agent
```

:::

</TabItem>
<TabItem value="RedHat-based">

1. Open a Terminal session and run the following command to add the authentik repo and associated GPG key:

```bash
# This overwrites any existing configuration in /etc/yum.repos.d/authentik.repo
cat <<EOF | sudo tee /etc/yum.repos.d/authentik.repo
[authentik]
name=authentik
baseurl=https://pkg.goauthentik.io
enabled=1
gpgcheck=1
gpgkey=https://pkg.goauthentik.io/keys/gpg-key.asc
EOF
```

2. Run the following commands to refresh metadata and install the authentik Agent packages:

```bash
sudo yum install -y authentik-cli authentik-agent authentik-sysd
```

3. _(optional)_ If you plan to enable [SSH server authentication and local device login](#enable-device-compliance-ssh-server-authentication-and-local-device-login), you will need to install two additional packages:

```sh
sudo yum install -y libnss-authentik libpam-authentik
```

4. Confirm that the authentik Agent is installed by opening a terminal window and entering the following command: `ak`

    You should see a response that starts with: `authentik CLI v<version_number>`

:::note Headless server
On a headless server, the system agent (sysd) does not start the user agent (ak-agent). You will need to manually start the user agent with this command:

```bash
systemctl start --user ak-agent
```

:::

</TabItem>
</Tabs>

## Enable device compliance, SSH server authentication, and local device login

To enable [device compliance features](../../device-compliance/index.mdx) and the device [accepting SSH connections](../../authentik-agent/device-authentication/ssh-authentication.mdx), you must join the device to an authentik domain.

1. Open a Terminal session and run the following command:

```sh
sudo ak-sysd domains join <deployment_name> --authentik-url https://authentik.company
```

- `deployment_name` is the name that will be used to identify the authentik deployment on the device.
- `https://authentik.company` is the fully qualified domain name of the authentik deployment.

2. You will be prompted to enter your [enrollment token](#create-an-enrollment-token).
3. Once provided, the device will be enrolled with your authentik deployment and should appear on the [Devices page](../../manage-devices.mdx) after a [check-in](../../device-compliance/device-reporting.md) is completed.

### Configure device login on non-Debian systems

On non-Debian Linux distributions, you currently need to manually configure NSS and PAM:

1. Edit `/etc/nsswitch.conf` to include `authentik` for `passwd`, `group`, and `shadow`:

```bash title="/etc/nsswitch.conf"
...
passwd:         files systemd authentik
group:          files systemd authentik
shadow:         files systemd authentik
gshadow:        files systemd
...
```

2. Edit the following two files in the `/etc/pam.d/` directory. The order matters, both of these lines should be located above `pam_unix` in the respective files.

```bash title="/etc/pam.d/common-auth"
...
auth    [success=2 default=ignore]      pam_authentik.so
...
```

```bash title="/etc/pam.d/common-session"
...
session required                        pam_authentik.so
...
```

## Enable SSH client authentication and CLI application authentication

To enable [initiating SSH connections](../../authentik-agent/device-authentication/ssh-authentication.mdx) and [CLI application authentication](../../authentik-agent/device-authentication/cli-app-authentication/index.mdx), the device must be connected to an authentik deployment. To do so, follow these steps:

1. Open a Terminal session and run the following command:

```sh
ak config setup --authentik-url https://authentik.company
```

2. Your default browser will open and direct you to the authentik login page. Once authenticated, the authentik Agent will be configured.

## Check version of installed components

You can check the version of all installed authentik components by running the following command:

```bash
ak version
```

## Logging

authentik Agent logs are available via the systemd journal (`journalctl`) or `syslog`, depending on the distribution.

## Reporting issues

Please report issues and bugs via the [authentik Platform GitHub repository](https://github.com/goauthentik/platform).