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 running: ak --version

    You should see output that starts with: authentik Agent CLI: <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​

Both the system agent and the user agent use macOS's native logging abilities. To retrieve their logs, open the Console application and filter for the process you're interested in, or run one of the following commands.

For the system agent:

log show --predicate 'process == "ak-sysd"'

For the user agent:

log show --predicate 'process == "ak-agent-desktop"'

Troubleshooting​

The Agent shows "disconnected" or lists no profiles​

Joining the device to a domain enrolls the device, but the desktop Agent stays disconnected until a user profile exists. If the Agent app shows disconnected with no profiles, or ak whoami returns profile not found, you haven't yet completed SSH client authentication and CLI application authentication:

  1. Run ak config setup --authentik-url https://authentik.company and complete the browser sign-in.
  2. Confirm that a profile now exists with ak config list-profiles, then verify with ak whoami.

If ak config setup doesn't open a login page, or reports an unknown client or a missing device code flow, your deployment is missing the OAuth prerequisites. Return to configuring your authentik deployment and confirm that a Device code flow is set on the brand, that the authentik-cli OAuth application and provider exist, and that the Agent connector federates the authentik-cli provider under Federated OIDC Providers.

Report issues​

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