Deploy authentik Agent on Linux

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.
• SSH to Linux hosts using authentik credentials, see SSH authentication.
• Authenticate CLI applications using authentik credentials, see CLI application authentication.

Prerequisites

You must configure your authentik deployment to support the authentik Agent.

Create an enrollment token

If you have already created have an enrollment token, skip to the next section.

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 to support the authentik agent.
4. Under Enrollment Tokens, click Create, 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.

Install the authentik Agent on Linux

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

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

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

2. Add the repository:

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:

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, you will need to install two additional packages:

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:

systemctl start --user ak-agent

:::

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

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

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

3. (optional) If you plan to enable SSH server authentication and local device login, you will need to install two additional packages:

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:

systemctl start --user ak-agent

:::

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

To enable device compliance features and the device accepting SSH connections, you must join the device to an authentik domain.

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

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.
3. Once provided, the device will be enrolled with your authentik deployment and should appear on the Devices page after a check-in 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:

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

...
auth    [success=2 default=ignore]      pam_authentik.so
...

...
session required                        pam_authentik.so
...

Enable SSH client authentication and CLI application authentication

To enable initiating SSH connections and CLI application authentication, 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:

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:

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.