Skip to main content

Deploy authentik Agent on macOS

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 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 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 macOS​

Automated deployment is recommended

It's recommended to deploy the Agent via MDM or automation tools instead of manually configuring it.

Serial number required

The Agent requires a serial number be presented by macOS. Some hypervisors don't set serial numbers. When deploying on a virtual machine, ensure that it has a serial number set.

  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 Setup, click macOS to download the authentik Agent installer.

  5. After the download completes, attempt to install the package. Default Apple security settings should block the installation.

    • This can be avoided by Option + Right Clicking the package and clicking Open.
    • Alternatively use the following command to remove the package from quarantine: xattr -r -d com.apple.quarantine "$HOME/Downloads/authentik agent installer.pkg"

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

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 and for every other feature that authenticates as the device, including Platform SSO.

  1. Open a Terminal session and run the following command:
sudo "/Applications/authentik Agent.app/Contents/MacOS/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.

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​

The system agent writes its output to a log file:

sudo tail -f /Library/Logs/io.goauthentik/sysd.log

The user agent uses macOS's native logging abilities. To retrieve its logs, open the Console application and filter for the ak-agent-desktop process, or run:

log show --last 30m --predicate 'process == "ak-agent-desktop"' --info --debug

Report issues​

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