Deploy authentik Agent on macOS

What it can do

• Retrieves information about the host for use in authentik, see Device Compliance.
• SSH to Linux hosts using authentik credentials, see SSH authentication.
• Authenticate CLI applications using authentik credentials, see CLI application authentication.

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

Install the authentik Agent on macOS

:::info Automated deployment is recommended It's recommended to deploy the Agent via MDM or automation tools instead of manually configuring it. :::

:::info 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. Once the download is complete, attempt to install the package. Default Apple security settings should block the install.

   • 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>

Enable device compliance

To enable device compliance features, you must join the device to an authentik domain.

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 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.
3. Once provided, the device will be enrolled with your authentik deployment and should appear on the Devices page after a check-in is completed.

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

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:

ak version

Logging

The authentik Agent uses macOS's native logging abilities. To retrieve the logs, open the Console application and then filter for authentik-related processes such as authentik-agent or authentik-sysd.

Reporting issues

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