Skip to main content

Deploy authentik Agent on Linux

authentik: 2025.12.0+

What it can do​

Prerequisites​

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

Create an enrollment token​

If you already have an enrollment token, skip to 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 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 to add the device to after enrollment.
    • Expiring (optional): Set whether the enrollment token expires.
  5. Click Create.
  6. (Optional) Click the Copy icon in the Actions column. You need this value to join the device to an authentik domain.

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
  1. 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
  1. Update your repositories and install the authentik Agent packages:
sudo apt update
sudo apt install authentik-cli authentik-agent authentik-sysd
  1. (Optional) To enable SSH server authentication and local device login, install two additional packages:
sudo apt install libnss-authentik libpam-authentik

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

Headless server

On a headless server, the system agent (sysd) does not start the user agent (ak-agent). Start the user agent manually:

systemctl start --user ak-agent

Join the device to an authentik domain​

Joining the device to an authentik domain is what enrolls it with your authentik deployment and issues it a device token. This step is required for device compliance features, for the device accepting SSH connections, and for local device login.

  1. Open a Terminal session and run the following command:
sudo ak-sysd domains join <deployment_name> --authentik-url https://authentik.company
  • deployment_name identifies the authentik deployment on the device.
  • https://authentik.company is the fully qualified domain name of the authentik deployment.
  1. Enter your enrollment token when prompted.
  2. After you enter the token, authentik enrolls the device. The device appears on the Devices page after it checks in.

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:
/etc/nsswitch.conf
...
passwd:         files systemd authentik
group:          files systemd authentik
shadow:         files systemd authentik
gshadow:        files systemd
...
  1. 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.
/etc/pam.d/common-auth
...
auth    [success=2 default=ignore]      pam_authentik.so
...
/etc/pam.d/common-session
...
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
  1. Your default browser opens the authentik login page. After you authenticate, the authentik Agent is configured.

Check version of installed components​

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

ak version

View logs​

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

Report issues​

Please report issues and bugs via the authentik Platform GitHub repository.