mirror of
https://github.com/goauthentik/authentik.git
synced 2026-06-18 11:29:26 +03:00
Dewi Roberts
185 lines
6.8 KiB
Plaintext
185 lines
6.8 KiB
Plaintext
---
|
|
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 **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](#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. 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. 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.
|
|
|
|
### Local 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 system journal (`systemd`) or `syslog`, depending on the distribution.
|
|
|
|
## Reporting issues
|
|
|
|
Please report issues and bugs via the [authentik Platform GitHub repository](https://github.com/goauthentik/platform).
|