mirror of
https://github.com/goauthentik/authentik
synced 2026-04-25 17:15:26 +02:00
6ed5cb5249
* website/integrations: rename "Create with Provider" to "New Application" The application list page now uses a split-button labeled "New Application" instead of the old "Create with Provider" dropdown. Update all 113 integration guides to match. * website/docs: update flow, stage, and policy button labels - "Create" → "New Flow", "New Stage", "New Policy" for trigger buttons - "Finish" → "Create Flow", "Create Stage", "Create Policy" for submit - "Create and bind stage" → "New Stage" / "Bind Existing Stage" - "Create" (binding submit) → "Create Stage Binding" * website/docs: update provider button labels - "Create" → "New Provider" for trigger buttons - "Create with Provider" → "New Application" in RAC docs - "Create" → "New Property Mapping", "New RAC Endpoint", "New Prompt" for related entity creation * website/docs: update directory button labels - "Create" → "New Source" for federation/social login pages - "Create" → "New Role", submit → "Create Role" - "Create" → "New Invitation" - Policy binding submit → "Create Policy Binding" * website/docs: update endpoint device and system management button labels - "Create" → "New Endpoint Connector", "New Enrollment Token", "New Device Access Group", "New Flow" - Submit → "Create Device Access Group" - "Create" → "New Notification Rule", "New Notification Transport" - Binding submit → "Create Policy Binding" * Reorganize policy documentation * website/docs: address policy docs review feedback * post-rebase * website/docs: Reorganize policy documentation -- Revisions (#21601) * apply suggestions * Fix escaped. * Fix whitespace. * Update button label. * Fix phrasing. * Fix phrasing. * Clean up stragglers. * Format. --------- Co-authored-by: Dominic R <dominic@sdko.org>
197 lines
7.4 KiB
Plaintext
197 lines
7.4 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 **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).
|