diff --git a/website/docs/add-secure-apps/flows-stages/stages/endpoint/index.md b/website/docs/add-secure-apps/flows-stages/stages/endpoint/index.md new file mode 100644 index 000000000000..71a6673404bf --- /dev/null +++ b/website/docs/add-secure-apps/flows-stages/stages/endpoint/index.md @@ -0,0 +1,18 @@ +--- +title: Endpoint stage +--- + +This stage integrates with the [Endpoint Device](../../../../endpoint-devices/index.mdx) functionality and allows authentik to verify whether the device executing a flow is registered. + +The Endpoint stage fetches [device facts](../../../../endpoint-devices/device-compliance/device-reporting.md#device-facts) via a configured [connector](../../../../endpoint-devices/device-compliance/connectors.md) and injects them into the flow context. These device facts can be used by other stages and policies to make device compliance decisions. + +## Connector + +Select the [connector](../../../../endpoint-devices/device-compliance/connectors.md) that the Endpoint stage will use to obtain device facts. + +## Mode + +Select whether the presence of a registered endpoint device is required for the stage to succeed. + +- If the mode is set to required, and device verification fails, the the user is not able to proceed with the flow. +- If the mode is set to optional, authentik will attempt to verify the device, and if it doesn't receive a response within the specified `challenge_idle_timeout`, authentik will continue without attaching a device to the flow. diff --git a/website/docs/endpoint-devices/authentik-agent/agent-deployment/index.mdx b/website/docs/endpoint-devices/authentik-agent/agent-deployment/index.mdx new file mode 100644 index 000000000000..91cd961e54c8 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/agent-deployment/index.mdx @@ -0,0 +1,14 @@ +--- +title: Deployment +sidebar_label: Deployment +--- + +import DocCardList from "@theme/DocCardList"; + +You can deploy the authentik Agent on [Linux](./linux.md), [macOS](./macos.md), and [Windows](./windows.md) devices. + +Documentation for large-scale deployments using [Mobile Device Management (MDM)](./mdm.mdx) tools is also available. + +Select a topic below to continue: + + diff --git a/website/docs/endpoint-devices/authentik-agent/agent-deployment/linux.md b/website/docs/endpoint-devices/authentik-agent/agent-deployment/linux.md new file mode 100644 index 000000000000..3818365f61b4 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/agent-deployment/linux.md @@ -0,0 +1,88 @@ +--- +title: Deploy authentik Agent on Linux +sidebar_label: Linux +tags: [authentik Agent, linux, deploy, packages] +--- + +## What it can do + +- Retrieves information about the host and reports it to authentik, see [Device Compliance](../../device-compliance/index.mdx). +- Authorize Sudo elevation, see [Sudo authorization](../../device-authentication/sudo-authorization.md). +- SSH to Linux hosts using authentik credentials, see [SSH authentication](../../device-authentication/ssh-authentication.mdx). +- Authenticate CLI applications using authentik credentials, see [CLI application authentication](../../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-and-ssh-access). + +## Install the authentik Agent on Linux + +Follow these steps to install the authentik Agent on your Linux device: + +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` + +## Enable device authentication + +To enable [device authentication features](../../device-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. + +## Enable device compliance and SSH access + +To enable [device compliance features](../../device-compliance/index.mdx) and the device [accepting SSH connections](../../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 +ak-sysd domains join --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. + +## Logging + +authentik Agent logs are available via the system journal (`systemd`) or `syslog`, depending on the distribution. diff --git a/website/docs/endpoint-devices/authentik-agent/agent-deployment/macos.md b/website/docs/endpoint-devices/authentik-agent/agent-deployment/macos.md new file mode 100644 index 000000000000..702b5292da70 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/agent-deployment/macos.md @@ -0,0 +1,73 @@ +--- +title: Deploy authentik Agent on macOS +sidebar_label: macOS +tags: [authentik Agent, mac, macos, deploy] +--- + +## What it can do + +- Retrieves information about the host for use in authentik, see [Device Compliance](../../device-compliance/index.mdx). +- SSH to Linux hosts using authentik credentials, see [SSH authentication](../../device-authentication/ssh-authentication.mdx). +- Authenticate CLI applications using authentik credentials, see [CLI application authentication](../../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-macos). + +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). + +## Install the authentik Agent on macOS + +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 **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` + +## Enable device authentication + +To enable [device authentication features](../../device-authentication/index.mdx), you must connect the device 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. + +## Enable device compliance + +To enable [device compliance features](../../device-compliance/index.mdx), you must join the device to an authentik domain. + +1. Open a Terminal session and run the following command: + +```sh +ak-sysd domains join --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. + +## 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`. diff --git a/website/docs/endpoint-devices/authentik-agent/agent-deployment/mdm.mdx b/website/docs/endpoint-devices/authentik-agent/agent-deployment/mdm.mdx new file mode 100644 index 000000000000..554646ea9d36 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/agent-deployment/mdm.mdx @@ -0,0 +1,57 @@ +--- +title: Deploy authentik Agent via MDM +sidebar_label: MDM +tags: [authentik Agent, mdm, fleet, deploy] +--- + +authentik Agent can be deployed at scale to multiple devices via Mobile Device Management (MDM) tools. + +## 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. + +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**. + +## Windows + +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 **Setup**, select the enrollment token that you wish to use for enrolling devices. +5. Click **Windows** and then click either **Download** or **Copy** to obtain your SyncML MDM configuration snippet. + +This SyncML snippet can be used by Microsoft Intune, Microsoft Endpoint Manager and other MDM tools to deploy the changes required to support the authentik Agent. + +The following two registry keys (`REG_SZ`) are added by the configuration snippet: + +- `HKLM/SOFTWARE/authentik Security Inc./Platform/ManagedConfig/RegistrationToken` +- `HKLM/SOFTWARE/authentik Security Inc./Platform/ManagedConfig/URL` + +## macOS + +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 **Setup**, select the enrollment token that you wish to use for enrolling devices. +5. Click **macOS** and then click either **Download** or **Copy** to obtain your MDM policy. + +This policy can be used by Apple Business Manager, Fleet, and other MDM tools to deploy the changes required to support the authentik Agent. + +:::warning MDM only +Apple requires that this policy be applied to a device via an MDM tool. It will not function if manually applied to a device. +::: + +### User registration + +Upon deploying the authentik Agent to a device, the user will receive a notification asking them to register with authentik. When a user follows the registration they are asked to authenticate with authentik, once authenticated the device is enrolled in authentik and associated with the user. diff --git a/website/docs/endpoint-devices/authentik-agent/agent-deployment/windows.md b/website/docs/endpoint-devices/authentik-agent/agent-deployment/windows.md new file mode 100644 index 000000000000..ff1e9a98d6fa --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/agent-deployment/windows.md @@ -0,0 +1,92 @@ +--- +title: Deploy authentik Agent on Windows +sidebar_label: Windows +tags: [authentik Agent, windows] +--- + +## What it can do + +- Retrieves information about the host for use in authentik, see [Device Compliance](../../device-compliance/index.mdx). +- SSH to Linux hosts using authentik credentials, see [SSH authentication](../../device-authentication/ssh-authentication.mdx). +- Authenticate CLI applications using authentik credentials, see [CLI application authentication](../../device-authentication/cli-app-authentication/index.mdx). + +:::warn Supported Windows Versions +The authentik Agent is currently only tested on Windows 11 and Windows Server 2022. Other versions may work but are untested. +::: + +## Windows Credential Provider + +Windows Credential Provider (WCP) is a component of the authentik Agent that allows logging in to Windows workstations using authentik credentials. + +It currently only supports local login; RDP login is not supported. + +:::warning + +- When WCP is enabled, the password of the Windows user account that's used to login is set to a random string. +- WCP can cause issues with user encrypted directories. +- Support with Active directory has not been confirmed yet. +- Offline login is currently not supported. + ::: + +## 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-windows). + +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). + +## Install the authentik Agent on Windows + +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 **Setup**, click **Windows** to download the authentik Agent installer. +5. Once the download is complete, install the MSI file. +6. _(Optional)_ During installation, select [Windows Credential Provider](#windows-credential-provider) if you want to log in to the Windows device using authentik credentials. +7. Confirm that the authentik Agent is installed by opening a PowerShell or Terminal window and entering the following command: `ak` + You should see a response that starts with: `authentik CLI v` + +## Enable device authentication + +To enable [device authentication features](../../device-authentication/index.mdx), you must connect the device to an authentik deployment. To do so, follow these steps: + +1. Open a Terminal 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. + +## Enable device compliance + +To enable [device compliance features](../../device-compliance/index.mdx), you must join the device to an authentik domain. + +1. Open a Terminal session and run the following command: + +```sh +ak-sysd domains join --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. + +## Logging + +The authentik Agent primarily outputs logs to Windows Event Viewer. + +WCP logs to the `wcp.log` located in `C:\Program Files\Authentik Security Inc\wcp`. diff --git a/website/docs/endpoint-devices/authentik-agent/authentik-cli.mdx b/website/docs/endpoint-devices/authentik-agent/authentik-cli.mdx new file mode 100644 index 000000000000..acb3db09efa0 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/authentik-cli.mdx @@ -0,0 +1,140 @@ +--- +title: Agent CLI commands +sidebar_label: Agent CLI commands +tags: [authentik Agent, authentik cli, ak cli, ak, cli, ak-sysd, commands] +--- + +The following commands are available when interacting with the authentik Agent via the command line. + +:::info Flags +Most of the CLI commands have a `-v`/`--verbose` flag for verbose output. +Use the `-h`/`--help` flag to access help information. +::: + +## authentik-cli commands + +### auth + +Commands for authenticating with different CLI applications. + +```bash +ak auth +``` + +- `aws` - Authenticate to AWS with the authentik profile. +- `kubectl` - Authenticate to a Kubernetes Cluster with the authentik profile. +- `raw` - Authenticate to arbitrary API calls. +- `vault` - Generate a JWT for authenticating to HashiCorp Vault. + +### completion + +Generate the autocompletion script for the specified shell. + +```bash +ak completion +``` + +- `bash` - Generate the autocompletion script for bash. +- `fish` - Generate the autocompletion script for fish. +- `powershell` - Generate the autocompletion script for PowerShell. +- `zsh` - Generate the autocompletion script for zsh. + +### config + +Configure authentik CLI + +```bash +ak config +``` + +- `list-profiles` - List profiles that are enabled on the device. Each profile is associated with a separate authentik deployment. +- `setup` - Configure authentik CLI. + +### help + +Output help information about any command. + +```bash +ak help +``` + +Where `` is any authentik CLI command you want help with, for example: `ak help ssh` + +### ssh + +Establish an SSH connection with the target endpoint device. + +```bash +ak ssh +``` + +### system + +Commands for interacting with authentik sessions. + +```bash +ak system +``` + +- `status` - Status about the current session. + +### whoami + +Check user account details for a given profile. + +```bash +ak whoami +``` + +## authentik-sysd commands + +### agent + +Used to run the authentik system agent + +```bash +ak-sysd agent +``` + +`-d` for debug +`--disable-component` to disable a component, can be used multiple times. +TODO @BeryJu document the ids of components + +### completion + +Generate the autocompletion script for the specified shell. + +```bash +ak-sysd completion +``` + +- `bash` - Generate the autocompletion script for bash. +- `fish` - Generate the autocompletion script for fish. +- `powershell` - Generate the autocompletion script for powershell. +- `zsh` - Generate the autocompletion script for zsh. + +### domains + +```bash +ak-sysd domains +``` + +- `join` - Join an authentik domain, for example `ak-sysd domains join -a ` + +### help + +```bash +ak-sysd help +``` + +Where `` is any authentik CLI command you want help with, for example: `ak-sysd help domains` + +### troubleshoot + +```bash +ak-sysd troubleshoot +``` + +- `check` - Check status of authentik agent components. Useful on Linux as there are various components being used. +- `inspect` - Outputs the state database that the agent has. +- `facts` - Outputs device facts. These are the facts that are sent to authentik for device reporting. diff --git a/website/docs/endpoint-devices/authentik-agent/configuration.md b/website/docs/endpoint-devices/authentik-agent/configuration.md new file mode 100644 index 000000000000..49ad00a9fb18 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/configuration.md @@ -0,0 +1,60 @@ +--- +title: Configuration +sidebar_label: Configuration +tags: [authentik Agent, connector, configure, configuration] +--- + +Before deploying the authentik Agent, configure your authentik deployment. This involves: + +- Importing the [Device code flow](../../add-secure-apps/providers/oauth2/device_code.md) +- Creating an OAuth application and provider +- Creating a [Connector](../device-compliance/connectors.md) + +## Import OAuth device code flow + +The OAuth device code flow enables secure authentication for input-limited clients like CLI tools and is required for the authentik Agent to function. + +If you have already deployed the authentik OAuth device code flow, skip to the [next section](#create-an-application-and-provider-in-authentik-for-cli). + +1. Download the [device code flow blueprint file](https://raw.githubusercontent.com/goauthentik/platform/refs/heads/main/hack/authentik/blueprints/oauth2-device-code.yaml). +2. Log in to authentik as an administrator and open the authentik Admin interface. +3. Navigate to **Flows and Stages** > **Flows**. +4. Click **Import** +5. Select the downloaded blueprint and click **Import**. +6. Navigate to **System** > **Brands** and click the **Edit** icon on the default brand. +7. Set **Default code flow** to the newly created device code flow and click **Update**. + +Alternatively, manually create the flow by following the instructions in the [Device code flow documentation](../../add-secure-apps/providers/oauth2/device_code.md#create-and-apply-a-device-code-flow). + +## Create an application and provider in authentik for CLI + +The authentik agent requires an OAuth application/provider pair to handle authentication. + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) + - **Application**: provide a descriptive name (e.g. `authentik-cli`), an optional group for the type of application, the policy engine mode, and optional UI settings. + - **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. + - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. + - Set the **Client type** to `Public`. + - Set the **Client ID** to `authentik-cli`. + - Select any available signing key. + - Under **Advanced protocol settings**: + - In addition to the three default **Selected Scopes**, add the `authentik default OAuth Mapping: OpenID 'offline_access'` scope. + - **Configure Bindings** _(optional)_: you can create a [binding](../../../add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage access to the application. + +3. Click **Submit** to save the new application and provider. + +## Create the authentik Agent connector + +The authentik Agent [Connector](../device-compliance/connectors.md) allows device information to be reported to authentik. + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Endpoint Devices** > **Connectors** and click **Create**. +3. Select **Agent Connector** as the agent type and click **Next**. +4. Configure the following required settings: + - **Connector name**: provide a descriptive name (e.g. `authentik Agent`) + - **Refresh interval**: select how often the agent will attempt to update its configuration. + - **Enabled**: toggle to enable the connector. + - Under **Authentication settings**: + - **Federated OIDC Providers**: add the `authentik-cli` provider that you created in the previous section. +5. Click **Finish**. diff --git a/website/docs/endpoint-devices/authentik-agent/development.md b/website/docs/endpoint-devices/authentik-agent/development.md new file mode 100644 index 000000000000..af7aed18f0c9 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/development.md @@ -0,0 +1,7 @@ +--- +title: Development +sidebar_label: Development +tags: [authentik Agent, development, repository] +--- + +The authentik Agent and associated components are developed in the [authentik Platform GitHub repository](https://github.com/goauthentik/platform). For source code and information on contributing to the project, refer to the documentation included in the GitHub repository. diff --git a/website/docs/endpoint-devices/authentik-agent/index.mdx b/website/docs/endpoint-devices/authentik-agent/index.mdx new file mode 100644 index 000000000000..eab18684f288 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/index.mdx @@ -0,0 +1,46 @@ +--- +title: authentik Agent +sidebar_label: authentik Agent +--- + +import DocCardList from "@theme/DocCardList"; + +## What is the authentik Agent? + +The authentik Agent is a service that can be installed on Linux, macOS, and Windows devices. It provides the following capabilities: + +- [Device Compliance](../device-compliance/index.mdx) by reporting information about Endpoint Devices to authentik +- [Local device login](../device-authentication/local-device-login/index.mdx) with authentik credentials +- [Connecting via SSH to Endpoint Devices](../device-authentication/ssh-authentication.mdx) with authentik credentials +- [Sudo authorization](../device-authentication/sudo-authorization.md) with authentik credentials +- [Authenticating to CLI applications](../device-authentication/cli-app-authentication/index.mdx) such as kubectl and AWS with authentik credentials + +## authentik Agent components + +The authentik Agent consists of several components: + +| Platform | Component | Description | Dependencies | +| ------------------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | +| **Linux, macOS, Windows** | `authentik-cli` | Provides CLI commands for interacting with `authentik-agent`. | `authentik-agent` | +| **Linux, macOS, Windows** | `authentik-agent` | User service. | `authentik-sysd` | +| **Linux, macOS, Windows** | `authentik-sysd` | System service. | None | +| **Linux only** | `libpam-authentik` | PAM Module for token-based and interactive authentication via authentik. Used for [SSH authentication](../device-authentication/ssh-authentication.mdx) and [local device login](../device-authentication/local-device-login/index.mdx). | `authentik-sysd` | +| **Linux only** | `libnss-authentik` | NSS Module that makes Linux aware of authentik users. All authentik users will be visible to Linux - but won't be able to login unless configured via device access groups. Provides a consistent `uid` and `gid` for users on all Endpoint Devices. | `authentik-sysd`, `libpam-authentik` | +| **Windows only** | `Windows Credential Provider` (WCP) | Enables logging in to Windows devices using authentik credentials. | `authentik-sysd` | + +## Technical information + +All authentik Agent components communicate via gRPC and Unix domain sockets. + +- `sys.sock` for general communication +- `sys-ctrl.sock` for domain join + +## Important considerations + +Sentry reporting is currently enabled by default and cannot be disabled. This will be configurable in a future release. + +## More information + +For more information refer to each of the topics below: + + diff --git a/website/docs/endpoint-devices/authentik-agent/release-notes/index.mdx b/website/docs/endpoint-devices/authentik-agent/release-notes/index.mdx new file mode 100644 index 000000000000..610d1aead4ee --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/release-notes/index.mdx @@ -0,0 +1,10 @@ +--- +title: authentik Agent Releases +sidebar_label: Release Notes +--- + +import DocCardList from "@theme/DocCardList"; + +Release notes for recent authentik Agent versions + + diff --git a/website/docs/endpoint-devices/authentik-agent/release-notes/temp.md b/website/docs/endpoint-devices/authentik-agent/release-notes/temp.md new file mode 100644 index 000000000000..f30b9f184c00 --- /dev/null +++ b/website/docs/endpoint-devices/authentik-agent/release-notes/temp.md @@ -0,0 +1,4 @@ +--- +title: temp +sidebar_label: temp +--- diff --git a/website/docs/endpoint-devices/device-authentication/cli-app-authentication/aws.mdx b/website/docs/endpoint-devices/device-authentication/cli-app-authentication/aws.mdx new file mode 100644 index 000000000000..7ae4eab84443 --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/cli-app-authentication/aws.mdx @@ -0,0 +1,45 @@ +--- +title: AWS CLI authentication +sidebar_label: AWS +tags: [authentik Agent, authentik cli, aws, cli] +--- + +You can use the authentik Agent to authenticate to the AWS CLI with authentik credentials. + +## Prerequisites + +- The [authentik Agent deployed on it](../../authentik-agent/agent-deployment/index.mdx) must be deployed on your device. + +## authentik configuration + +To support the integration of authentik Agent with AWS CLI, you need to create an application/provider pair in authentik. + +### Create an application and provider in authentik for AWS CLI + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) + - **Application**: provide a descriptive name (e.g. `authentik-aws-cli`), an optional group for the type of application, the policy engine mode, and optional UI settings. + - **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. + - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. + - Set the **Client type** to `Public`. + - Set the **Client ID** to `authentik-aws-cli`. + - Select any available signing key. + - Under **Machine-to-Machine authentication settings** add the `authentik-cli` provider as a **Federated OIDC Provider**. + - **Configure Bindings** _(optional)_: you can create a [binding](../../../../add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage access to the application. + +3. Click **Submit** to save the new application and provider. + +## Authenticate to AWS CLI with the authentik Agent + +To authenticate to the AWS CLI with the authentik agent, use the following command: + +```bash +ak auth aws +``` + +**Available flags:** + +- `-c, --client-id ` - Client ID +- `-e, --region ` - AWS region (default: `eu-central-1`) +- `-r, --role-arn ` - IAM Role ARN +- `-h, --help` - Display help information diff --git a/website/docs/endpoint-devices/device-authentication/cli-app-authentication/index.mdx b/website/docs/endpoint-devices/device-authentication/cli-app-authentication/index.mdx new file mode 100644 index 000000000000..728d8fb02cb8 --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/cli-app-authentication/index.mdx @@ -0,0 +1,21 @@ +--- +title: CLI application authentication +sidebar_label: CLI application authentication +tags: [authentik Agent, authentik cli, kubernetes, k8s, aws, cli] +--- + +import DocCardList from "@theme/DocCardList"; + +The authentik Agent can authenticate to CLI applications such as [`aws`](./aws.mdx) and [`kubectl`](./k8s.mdx). + +## How CLI authentication works + +First, `authentik-agent` and `authentik-cli` request an authentik token from the [authentik-cli OAuth Provider](../../authentik-agent/configuration.md#create-an-application-and-provider-in-authentik-for-cli) and exchange it for a token from the specified Kubernetes or AWS provider. + +This token is cached until expiration. This improves performance by eliminating repeated token requests. + +## More information + +For more information refer to each of the topics below: + + diff --git a/website/docs/endpoint-devices/device-authentication/cli-app-authentication/k8s.mdx b/website/docs/endpoint-devices/device-authentication/cli-app-authentication/k8s.mdx new file mode 100644 index 000000000000..59803d448084 --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/cli-app-authentication/k8s.mdx @@ -0,0 +1,80 @@ +--- +title: Kubernetes CLI authentication +sidebar_label: Kubernetes +tags: [authentik Agent, authentik cli, kubernetes, k8s, kubectl, cli] +--- + +You can use the authentik Agent to authenticate to `kubectl` with authentik credentials. + +## Prerequisites + +- The device that you're using must have the [authentik Agent deployed on it](../../authentik-agent/agent-deployment/index.mdx). + +## authentik configuration + +To support the integration of authentik Agent with `kubectl`, you need to create an application/provider pair in authentik. + +### Create an application and provider in authentik for Kubernetes + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Applications** > **Applications** and click **Create with Provider** to create an application and provider pair. (Alternatively you can first create a provider separately, then create the application and connect it with the provider.) + - **Application**: provide a descriptive name (e.g. `authentik-kubernetes`), an optional group for the type of application, the policy engine mode, and optional UI settings. + - **Choose a Provider type**: select **OAuth2/OpenID Connect** as the provider type. + - **Configure the Provider**: provide a name (or accept the auto-provided name), the authorization flow to use for this provider, and the following required configurations. + - Set the **Client type** to `Public`. + - Set the **Client ID** to `authentik-kubernetes`. + - Select any available signing key. + - Under **Machine-to-Machine authentication settings** add the `authentik-cli` provider as a **Federated OIDC Provider**. + - **Configure Bindings** _(optional)_: you can create a [binding](../../../../add-secure-apps/flows-stages/bindings/) (policy, group, or user) to manage access to the application. + +3. Click **Submit** to save the new application and provider. + +## Kubernetes configuration + +To integrate the authentik Agent with your kubernetes deployment, you'll need to configure kubeadm. + +### Configure kubeadm settings + +Add the following `extraArgs` to your `kubeadm_config.yml` file: + +```yaml +- name: oidc-client-id + value: authentik-kubernetes +- name: oidc-groups-claim + value: groups +- name: oidc-groups-prefix + value: "oidc:" +- name: oidc-issuer-url + value: https://authentik.company/application/o// +- name: oidc-username-claim + value: email +``` + +Run the following command to apply the changes to an existing Kubernetes cluster: + +:::warning +This command will restart the API server. Plan accordingly for production environments. +::: + +```sh +kubeadm upgrade apply --config=kubeadm_config.yml +``` + +Where `` matches the target Kubernetes version specified in your config file. + +:::info Example config file +An example `kubeadm_config.yml` is available on the [authentik Platform GitHub repository](https://github.com/BeryJu/infrastructure/blob/main/roles/beryjuio_kube/templates/kubeadm_config.yml#L11-L20). +::: + +## Authenticate to kubectl with the authentik Agent + +To authenticate to kubectl with the authentik agent, use the following command: + +```bash +ak auth kubectl +``` + +**Available flags:** + +- `-c, --client-id ` - Client ID +- `-h, --help` - Display help information diff --git a/website/docs/endpoint-devices/device-authentication/device-access-groups.mdx b/website/docs/endpoint-devices/device-authentication/device-access-groups.mdx new file mode 100644 index 000000000000..7fb4709abaf4 --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/device-access-groups.mdx @@ -0,0 +1,18 @@ +--- +title: Device access groups +sidebar_label: Device access groups +tags: [authentik Agent, device authentication, device login, device groups] +--- + +Device access groups control access to endpoint devices. You can organize devices into groups and bind users, user groups, and policies to determine access. + +## Creating a device access group + +To create a device access group, follow these steps: + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Endpoint Devices** > **Device Access Groups** and click **Create**. +3. Provide a **Group name** and click **Create**. +4. Expand the newly created device access group. +5. Click either **Create and bind Policy** or **Bind existing Policy / Group / User**. +6. Once you've configured the desired access for the device access group, click **Finish**. diff --git a/website/docs/endpoint-devices/device-authentication/index.mdx b/website/docs/endpoint-devices/device-authentication/index.mdx new file mode 100644 index 000000000000..35f886049a06 --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/index.mdx @@ -0,0 +1,19 @@ +--- +title: Device authentication +sidebar_label: Device authentication +--- + +import DocCardList from "@theme/DocCardList"; + +The [authentik Agent](../authentik-agent/index.mdx) supports multiple types of authentication and authorization using authentik credentials: + +- [Local device login](./local-device-login/index.mdx) - Log in to Windows endpoint devices. +- [SSH authentication](./ssh-authentication.mdx) - Connect from one endpoint device to another via SSH. +- [Sudo authorization](./sudo-authorization.md) - Authorize sudo elevation on an endpoint device. +- [Authenticate CLI applications](./cli-app-authentication/index.mdx) - Authenticate CLI based applications like `aws` and `kubectl`. + +[Device access groups](./device-access-groups.mdx) allow you to control which users have access to a device. + +For more information, pick a topic below: + + diff --git a/website/docs/endpoint-devices/device-authentication/local-device-login/authentik-login.png b/website/docs/endpoint-devices/device-authentication/local-device-login/authentik-login.png new file mode 100644 index 000000000000..fa5ce2a8240a Binary files /dev/null and b/website/docs/endpoint-devices/device-authentication/local-device-login/authentik-login.png differ diff --git a/website/docs/endpoint-devices/device-authentication/local-device-login/index.mdx b/website/docs/endpoint-devices/device-authentication/local-device-login/index.mdx new file mode 100644 index 000000000000..1a519254fb2a --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/local-device-login/index.mdx @@ -0,0 +1,17 @@ +--- +title: Local device login +sidebar_label: Local device login +tags: [authentik Agent, device login, device authentication, windows credential provider, wcp] +--- + +import DocCardList from "@theme/DocCardList"; + +Local device login allows you to log in to devices using authentik credentials instead of separate local accounts. + +Users authenticate with authentik, just like they do for any application. The operating system login screen on a laptop, desktop, or server is connected to authentik. + +Local device login is currently only supported on Windows. Linux support is possible but not yet implemented. Configuration and testing with various Linux login managers (SDDM, GDM, etc.) and PAM implementations is pending. + +For more information, pick a topic below: + + diff --git a/website/docs/endpoint-devices/device-authentication/local-device-login/linux.md b/website/docs/endpoint-devices/device-authentication/local-device-login/linux.md new file mode 100644 index 000000000000..8b2875b947ac --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/local-device-login/linux.md @@ -0,0 +1,9 @@ +--- +title: Linux local device login +sidebar_label: Linux +tags: [authentik Agent, device login, device authentication, linux] +--- + +Local device login is currently only supported on Windows. + +Linux support is possible but not yet implemented. Configuration and testing with various Linux login managers (SDDM, GDM, etc.) and PAM implementations is pending. diff --git a/website/docs/endpoint-devices/device-authentication/local-device-login/windows.md b/website/docs/endpoint-devices/device-authentication/local-device-login/windows.md new file mode 100644 index 000000000000..b86afc3b5451 --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/local-device-login/windows.md @@ -0,0 +1,40 @@ +--- +title: Windows local device login +sidebar_label: Windows +tags: [authentik Agent, device login, device authentication, windows credential provider, wcp] +--- + +## Windows Credential Provider + +Windows Credential Provider (WCP) is a component of the authentik Agent that allows logging in to Windows devices using authentik credentials. + +It currently only supports local login; RDP login is not supported. + +:::warning + +- WCP is currently only tested on Windows 11 and Windows Server 2022. +- When WCP is enabled, the password of the Windows user account that's used to login is set to a random string. +- WCP can cause issues with user encrypted directories. +- Support with Active directory has not been confirmed yet. +- Offline login is currently not supported. + ::: + +## Prerequisites + +You need to have deployed the authentik Agent including the WCP component on the Windows device, see [Deploy the authentik Agent on Windows](../../authentik-agent/agent-deployment/windows.md) for more details. + +## How it works + +- The system agent requests an authentication and authorization URL from authentik, using its token. +- This URL is opened in a browser which also injects the device token information, allowing authenitk to know that the login request is executed on the same machine. +- The end user logs in normally using the standard authentik interface and flows +- Once finished, the browser is redirect to a well-defined location and uses the token it receives to finish authentication and authorization through the system agent + +## How to log in to a Windows device + +1. On the Windows login screen, click the authentik icon: + +![Windows login screen](authentik-login.png) + +2. A browser window will open and prompt you for your authentik credentials. +3. Once authenticated, you will be logged in to the Windows device. diff --git a/website/docs/endpoint-devices/device-authentication/ssh-authentication.mdx b/website/docs/endpoint-devices/device-authentication/ssh-authentication.mdx new file mode 100644 index 000000000000..f78cc0107fec --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/ssh-authentication.mdx @@ -0,0 +1,56 @@ +--- +title: SSH authentication +sidebar_label: SSH authentication +tags: [ssh, authentik Agent] +--- + +You can use the [authentik Agent](../authentik-agent/index.mdx) to authenticate SSH connections ubetween endpoint devices using authentik credentials. + +Currently, only [Linux](../authentik-agent/agent-deployment/linux.md) devices can serve as SSH endpoints. See [Configure SSH authentication on an endpoint device](#configure-ssh-authentication-on-an-endpoint-device) section for more details. + +## Prerequisites + +- The [authentik Agent must be deployed](../authentik-agent/agent-deployment/index.mdx) on both the source and SSH target devices. +- The target device needs to be configured, see the [Configure SSH authentication on an endpoint device](#configure-ssh-authentication-on-an-endpoint-device) section below. + +## How to SSH to an endpoint device + +To SSH to a configured [Linux host](../authentik-agent/agent-deployment/linux.md) using the authentik Agent: + +1. Open a Terminal session and run the following command: + +``` +ak ssh +``` + +2. If not already authenticated, you will be prompted for authentik credentials. +3. Once authenticated, the SSH session will connect. + +## Configure SSH authentication on an endpoint device + +If you want a Linux Endpoint Device to support accepting SSH connections using authentik credentials, you will need to install the `libpam-authentik` package in addition to the authentik Agent. This is a PAM Module, which provides token-based and interactive authentication via authentik. + +Authentication is only possible if the Linux device is aware of the authentik user which is attempting to authenticate. This can be achieved in one of two ways: + +1. **Provision user accounts** - Create users on the Linux device with usernames that match authentik users that need to authenticate to the device. This can be done manually or via automation tools like Ansible. +2. **`libnss-authentik`** - This is a package that can be installed on the Linux device. It is an NSS module that makes the Linux device aware of authentik users. Similar to adding a Linux device to an Active Directory or LDAP domain. + +### Install the `libpam-authentik` package _(required)_ + +:::info Prerequisites +You must have already deployed and configured the authentik Agent on the device. +::: + +Run the following command to install the `libpam-authentik` package: + +```sh +sudo apt install libpam-authentik +``` + +### Install the `libnss-authentik` package _(optional)_ + +Run the following command to install the `libnss-authentik` package: + +```sh +sudo apt install libnss-authentik +``` diff --git a/website/docs/endpoint-devices/device-authentication/sudo-authorization.md b/website/docs/endpoint-devices/device-authentication/sudo-authorization.md new file mode 100644 index 000000000000..760edbe56c49 --- /dev/null +++ b/website/docs/endpoint-devices/device-authentication/sudo-authorization.md @@ -0,0 +1,43 @@ +--- +title: Sudo authorization +sidebar_label: Sudo authorization +tags: [sudo, authentik Agent] +--- + +You can use the [authentik Agent](../authentik-agent/index.mdx) to authorize sudo elevation when connected to a [Linux endpoint device via SSH](./ssh-authentication.mdx). + +When you run a sudo command in this situation, the sudo authorization will be handled by the authentik Agent. + +## Prerequisites + +- [authentik Agent needs to be deployed](../authentik-agent/agent-deployment/index.mdx) on the device. +- Sudo authorization needs to be configured on the device, see the [Configure sudo authorization on an endpoint device](#configure-sudo-authorization-on-an-endpoint-device) section below. + +## Configure sudo authorization on an endpoint device + +If you want a Linux Endpoint Device to support authorizing using authentik credentials, you will need to install the `libpam-authentik` package in addition to the authentik Agent. This is a PAM Module, which provides token-based and interactive authentication via authentik. + +Authorization is only possible if the Linux device is aware of the authentik user which is attempting to authorize. This can be achieved in one of two ways: + +1. **Provision user accounts** - Create users on the Linux device with usernames that match authentik users that need to authorize sudo to the device. This can be done manually or via automation tools like Ansible. +2. **`libnss-authentik`** - This is a package that can be installed on the Linux device. It is an NSS module that makes the Linux device aware of authentik users. Similar to adding a Linux device to an Active Directory or LDAP domain. + +### Install the `libpam-authentik` package _(required)_ + +:::info Prerequisites +You must have already deployed and configured the authentik Agent on the device. +::: + +Run the following command to install the `libpam-authentik` package: + +```sh +sudo apt install libpam-authentik +``` + +### Install the `libnss-authentik` package _(optional)_ + +Run the following command to install the `libnss-authentik` package: + +```sh +sudo apt install libnss-authentik +``` diff --git a/website/docs/endpoint-devices/device-compliance/browser-extension.mdx b/website/docs/endpoint-devices/device-compliance/browser-extension.mdx new file mode 100644 index 000000000000..0433f788f6e7 --- /dev/null +++ b/website/docs/endpoint-devices/device-compliance/browser-extension.mdx @@ -0,0 +1,46 @@ +--- +title: authentik browser extension +sidebar_label: Browser extension +tags: [device compliance, compliance, browser extension, extension] +--- + +import TabItem from "@theme/TabItem"; +import Tabs from "@theme/Tabs"; + +The authentik browser extension is required for device compliance functionality, and is currently available for Chrome-based and Firefox-based browsers. + +The browser extension connects to the [authentik Agent](../authentik-agent/index.mdx). It supplies [device facts](./device-reporting.md#device-facts) that [stages](../../add-secure-apps/flows-stages/stages/index.md) and [policies](../../customize/policies/index.md) can use during execution of authentik [flows](../../add-secure-apps/flows-stages/flow/index.md). This enables device compliance functionality such as limiting access to applications based on operating system, see [device compliance policy](./device-compliance-policy.md) for more details. + +## Deploy the authentik browser extension + + + + +(TODO - Jens finalizing adding extension to store) + +1. Open Google Chrome. +2. Go to the the authentik browser extension page in the [Chrome Web Store](https://chromewebstore.google.com). +3. Click **Add to Chrome**. +4. Review the permissions and click **Add extension**. + + + + +(TODO - Jens finalizing adding extension to store) + +1. Open Firefox. +2. Go to the the authentik browser extension page in the [Firefox Add-ons site](https://addons.mozilla.org). +3. Click **Add to Firefox**. +4. Review the permissions and click **Add** (or **Install**). + + + + +## Configuration verification + +Verify that the extension shows as installed in your extensions list. diff --git a/website/docs/endpoint-devices/device-compliance/configuration.md b/website/docs/endpoint-devices/device-compliance/configuration.md new file mode 100644 index 000000000000..4d73d85cacd5 --- /dev/null +++ b/website/docs/endpoint-devices/device-compliance/configuration.md @@ -0,0 +1,21 @@ +--- +title: Configuration +sidebar_label: Configuration +tags: [device compliance, compliance, configuration] +--- + +## Prerequisites + +Device compliance functionality requires the following: + +- [Configure authentik to support the authentik Agent](../authentik-agent/configuration.md). +- [Deploy the authentik Agent on the device](../authentik-agent/agent-deployment/index.mdx). +- [Deploy the authentik browser extension on the endpoint device](./browser-extension.mdx). + +## Configuration verification + +Verify that the endpoint device is reporting its facts on the [Devices](../manage-devices.mdx) page. + +## Using device compliance + +Now that the endpoint device is configured, you can create [device compliance policies](./device-compliance-policy.md) to control access to applications and more. diff --git a/website/docs/endpoint-devices/device-compliance/connectors.md b/website/docs/endpoint-devices/device-compliance/connectors.md new file mode 100644 index 000000000000..1712cbf58874 --- /dev/null +++ b/website/docs/endpoint-devices/device-compliance/connectors.md @@ -0,0 +1,45 @@ +--- +title: Connectors +sidebar_label: Connectors +tags: [device compliance, compliance, connectors, authentik Agent, fleet] +--- + +Connectors allow device information to be reported to authentik. + +They can be used standalone or alongside the [authentik Agent](../authentik-agent/index.mdx). + +Currently, the only supported connectors is the [authentik Agent](#authentik-agent) + +## Connectors + +The following connectors are currently supported: + +### authentik Agent + +- Unlike other connectors, the agent connector is used by the agent directly compared to other connectors talking to separate systems and APIs to integrate with other agents. Hence the functionality of the agent connector behaves differently than other connectors. +- the agent connector mainly holds configuration for the agent itself, as well as implementing certain platform specific protocols like Apple's Platform SSO. + +## Adding a connector + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Endpoint Devices** > **Connectors** and click **Create**. +3. Select the connector type and click **Next**, and configure the following required settings: + - **Connector name**: provide a descriptive name for the connector. + - **Refresh interval**: select how often the agent will attempt to update it's configuration. + - **Enabled**: enable or disable the connector. +4. Click **Finish**. + +## Editing a connector + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Endpoint Devices** > **Connectors**. +3. Click on the connector that you wish to edit. +4. Update any settings that you want to change. +5. Click **Update**. + +## Deleting a connector + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Endpoint Devices** > **Connectors**. +3. Select the connector that you wish to delete. +4. Click **Delete**. diff --git a/website/docs/endpoint-devices/device-compliance/device-compliance-policy.md b/website/docs/endpoint-devices/device-compliance/device-compliance-policy.md new file mode 100644 index 000000000000..fe3d5d87e3d7 --- /dev/null +++ b/website/docs/endpoint-devices/device-compliance/device-compliance-policy.md @@ -0,0 +1,95 @@ +--- +title: Device compliance policy +sidebar_label: Device compliance policy +tags: [device compliance, compliance, device access, policy] +toc_max_heading_level: 4 +--- + +Device compliance policies are used to limit access to authentik and applications based on [Device Compliance](./index.mdx) information. + +Device compliance policies are currently in development and inaccessible. + +However, similar functionality can be achieved with existing stages and policies. + +## Prerequisites + +You must have [configured compliance](./configuration.md) in authentik and on the endpoint device. + +## Accessing device facts within a flow + +To access device facts within a flow, the flow must include an [Endpoint stage](../../add-secure-apps/flows-stages/stages/endpoint/index.md). The Endpoint stage fetches device facts via a configured [Connector](./connectors.md) and adds them to the [Flow context](../../add-secure-apps/flows-stages/flow/context/index.mdx). + +The following example shows how to use these facts within an expression policy. + +```python +flow_plan = request.context.get("flow_plan") #set a flow_plan object +device = flow_plan.context.get("device") #set a device object +name = device.name #the name of the device +``` + +## Examples + +The following are examples of how device compliance can currently be implemented: + +### Only allow authentication via endpoint devices + +If your goal is to only allow authentication via endpoint devices, this is achievable by adding an [Endpoint stage](../../add-secure-apps/flows-stages/stages/endpoint/index.md) to your authentication flow. + +#### Create an Endpoint stage + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Flows and Stages > Flows**. +3. Select the authentication flow that you want to modify. +4. Open the **Stage Bindings** tab and click **Create and bind stage**. +5. Select Endpoint stage as the stage type, click **Next**, and configure the following settings: + - **Name**: provide a name for the stage + - **Connector**: select a connector for the stage to fetch device facts from (e.g. `authentik agent`) + - **Mode**: set to `Device required` +6. Click **Next**. +7. Select the order for the stage. Ensure that this places the Endpoint stage in the flow wherever you want device access to be checked. +8. Click **Finish**. + +### Only allow authentication via a specific type of endpoint device + +If your goal is to only allow authentication via a specific type of endpoint device, this is achievable by adding an [Endpoint stage](../../add-secure-apps/flows-stages/stages/endpoint/index.md) and a [Deny stage](../../add-secure-apps/flows-stages/stages/deny.md) to your authentication flow. + +The following example will only allow authentication via Apple devices. + +#### Create an Endpoint stage + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Flows and Stages > Flows**. +3. Select the authentication flow that you want to modify. +4. Open the **Stage Bindings** tab and click **Create and bind stage**. +5. Select Endpoint stage as the stage type, click **Next**, and configure the following settings: + - **Name**: provide a name for the stage + - **Connector**: select a connector for the stage to fetch device facts from (e.g. `authentik agent`) + - **Mode**: set to `Device required` +6. Click **Next**. +7. Select the **Order** for the stage. Ensure that this places the Endpoint stage in the flow wherever you want device access to be checked. +8. Click **Finish**. + +#### Create a Deny stage + +9. On the **Stage Bindings** tab, click **Create and bind stage**. +10. Select **Deny Stage** as the stage type and configure the following settings: + - **Name**: provide a name for the stage + - **Deny message**: provide a message explaining why access was denied +11. Click **Next**. +12. Select the **Order** for the stage. Ensure that this number is higher than the Endpoint stage created in the previous section. +13. Click **Finish**. +14. Expand the Deny stage that you just created and click **Create and bind Policy**. +15. Select **Expression policy** as the policy type, click **Next**, and configure the following settings: + - **Name**: provide a descriptive name for the policy + - **Expression**: + ```python + flow_plan = request.context.get("flow_plan") + device = flow_plan.context.get("device") + if device.manufacturer.lower() != "apple": + return True + ``` + :::info Deny stage + Because this is a deny stage, the policy must evaluate true when a requirement is not met. + ::: + +16. Click **Next** and then click **Finish**. diff --git a/website/docs/endpoint-devices/device-compliance/device-event-example.png b/website/docs/endpoint-devices/device-compliance/device-event-example.png new file mode 100644 index 000000000000..717abc663080 Binary files /dev/null and b/website/docs/endpoint-devices/device-compliance/device-event-example.png differ diff --git a/website/docs/endpoint-devices/device-compliance/device-reporting.md b/website/docs/endpoint-devices/device-compliance/device-reporting.md new file mode 100644 index 000000000000..4a060e1f5b5d --- /dev/null +++ b/website/docs/endpoint-devices/device-compliance/device-reporting.md @@ -0,0 +1,46 @@ +--- +title: Device reporting +sidebar_label: Device reporting +tags: + [ + device compliance, + compliance, + device facts, + device reporting, + device check-in, + check-in, + facts, + ] +--- + +Endpoint Devices registered with authentik via a connector, such as the [authentik Agent](./connectors.md#authentik-agent) connector, regularly [check-in](#device-check-in) with authentik and report their [device facts](#device-facts). + +These facts are shown on the [Devices](../manage-devices.mdx) page and are also accessible to policies and can be used to make policy decisions. See [Device Compliance Policy](./device-compliance-policy.md) for more details. + +## Device check-in + +When a device registered with authentik reports its [device facts](#device-facts), this is called a device check-in. These check-ins occur on a regular configurable schedule and can also be set to occur whenever a device is associated with an [Endpoint stage](../../add-secure-apps/flows-stages/stages/endpoint/index.md). + +## Device facts + +Device facts are informational snippets about a device, such as its operating system, serial number, installed applications, running processes, and more. These facts can are supplied to authentik flows via the [authentik browser extension](browser-extension.mdx) to be used in making policy decisions. For example, you can create a policy that only allows endpoint devices that are running a recent OS version to access an application. + +### Advanced device facts :ak-enterprise + +This feature is still in development and will be announced soon. + +## Endpoint devices in event logs + +Authentication events involving endpoint devices are included in the [event logs](../../sys-mgmt/events/logging-events.md). For example: + +![Example of device authentication event](device-event-example.png) + +### Search for an endpoint device in the event logs :ak-enterprise + +To search for event logs matching a specific endpoint device: + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Events** > **Logs**. +3. In the search bar, enter: `context.device.name = ""` + +For more information on searching the events logs, see [Logging events](../../sys-mgmt/events/logging-events.md). diff --git a/website/docs/endpoint-devices/device-compliance/index.mdx b/website/docs/endpoint-devices/device-compliance/index.mdx new file mode 100644 index 000000000000..281b17f9b097 --- /dev/null +++ b/website/docs/endpoint-devices/device-compliance/index.mdx @@ -0,0 +1,14 @@ +--- +title: Device Compliance +sidebar_label: Device Compliance +--- + +import DocCardList from "@theme/DocCardList"; + +Device compliance lets authentik verify that a user's device meets security and configuration criteria, such as operating system version, disk encryption, antivirus status etc, before allowing access to resources. + +Device compliance is currently in very early preview. Device compliance policies are currently inaccessible and therefore have to be emulated with existing policies. + +For more information, pick a topic below: + + diff --git a/website/docs/endpoint-devices/index.mdx b/website/docs/endpoint-devices/index.mdx new file mode 100644 index 000000000000..72e7f2aaa4af --- /dev/null +++ b/website/docs/endpoint-devices/index.mdx @@ -0,0 +1,61 @@ +--- +title: Endpoint Devices +sidebar_label: Endpoint Devices +--- + +import DocCardList from "@theme/DocCardList"; + +:::danger Early preview +The endpoint devices feature set is currently in early preview and in development. **It is not recommended for production use.** + +The features, methods, and even the name are yet to be confirmed. + +Breaking changes and bugs should be expected. +::: + +:::info Enterprise License Required +An enterprise license is required to access some of these features, refer to the [current features overview table](#features-overview) below for more details. + +During this early preview stage, short trial licenses are available for testers. Please contact us via hello@goauthentik.io for more details. +::: + +## What are endpoint devices? + +Endpoint devices are end-user devices or servers that are registered with authentik. + +There are two purposes for registration: [Device authentication](./device-authentication/index.mdx) and [Device compliance](./device-compliance/index.mdx). + +Devices can be registered by installing the [authentik Agent](./authentik-agent/index.mdx) which supports: + +- [Device compliance](./device-compliance/index.mdx) by reporting information about endpoint devices to authentik. +- [Local device login](./device-authentication/local-device-login/index.mdx) with authentik credentials. +- [Connecting via SSH to endpoint devices](./device-authentication/ssh-authentication.mdx) with authentik credentials. +- [Sudo authorization](./device-authentication/sudo-authorization.md) with authentik credentials. +- [Authenticating to CLI applications](./device-authentication/cli-app-authentication/index.mdx) such as kubectl and AWS with authentik credentials. + +Alternatively, [Connectors](./device-compliance/connectors.md) allow authentik to be integrated with third party services such as Fleet. This allows for device information to be reported to authentik for [Device compliance](./device-compliance/index.mdx) purposes. + +## Features overview + +| Feature | Linux | Windows | macOS | Status | +| --------------------------------------------------------- | -------------- | -------------- | ----------------- | ------------------------------------------------------------------------------------------- | +| **Local device login** | Open source | :ak-enterprise | :ak-enterprise \* | Available for early preview on Windows. | +| **SSH authentication** | Open source | N/A | :ak-enterprise | Available for early preview. Only supports Linux SSH targets. macOS targets in development. | +| **Sudo authorization** | Open source | N/A | N/A | Available for early preview. | +| **Device compliance** | Open source | Open source | Open source | Available for early preview. | +| **Advanced device compliance** | :ak-enterprise | :ak-enterprise | :ak-enterprise | In development. | +| **authentik Agent ** | Open source | Open source | Open source | Available for early preview. | +| **Fleet Connectors** | :ak-enterprise | :ak-enterprise | :ak-enterprise | Available for early preview. | +| **Other Connectors** (Entra, Intune, Cloudflare WARP etc) | :ak-enterprise | :ak-enterprise | :ak-enterprise | In development. | + +\*TODO: explain how PSSO works + +## How to provide feedback and report bugs + +Report issues via our [GitHub](https://github.com/goauthentik/platform/issues). Please include as much information as possible to assist us in troubleshooting. + +## More information + +For more information refer to each of the topics below: + + diff --git a/website/docs/endpoint-devices/manage-devices.mdx b/website/docs/endpoint-devices/manage-devices.mdx new file mode 100644 index 000000000000..fd763dbfebbc --- /dev/null +++ b/website/docs/endpoint-devices/manage-devices.mdx @@ -0,0 +1,38 @@ +--- +title: Manage devices +sidebar_label: Manage devices +tags: [devices, device info, device facts, managing devices] +--- + +The Devices page provides a list of all endpoint devices registered with your authentik deployment. Refer to [Device reporting](./device-compliance/device-reporting.md) for more details on how [device facts](./device-compliance/device-reporting.md#device-facts) are reported to authentik. + +Each Endpoint Device can be expanded to view more detailed information. + +## Accessing the Devices page + +To access the Devices page, follow these steps: + +1. Log in to authentik as an administrator and open the authentik Admin interface. +2. Navigate to **Endpoint Devices** > **Devices**. +3. Specific endpoint device information can be accessed by clicking on a device. + +## Specific device + +Once you have selected a specific endpoint device you will have access to the following tabs: + +### Overview + +Provides an overview of the endpoint device: + +- **Device details**: basic facts about the device: name, hostname, serial number, operating system, firewall status and device access group. +- **Hardware**: basic hardware facts about the device: manufacturer, model, cpu, memory, disk encryption status, primary disk size, primary disk usage. +- **Connections**: shows the current [connectors](./device-compliance/connectors.md) that are enabled for the device and when the last [check-in](./device-compliance/device-reporting.md#device-check-in) occurred. +- **Users/Groups**: shows the users and groups that have access to the device. Controlled via [device access groups](./device-authentication/device-access-groups.mdx). + +### Processes + +Lists the processes that were running on the device when its last check-in occurred. + +### Users + +### Groups diff --git a/website/docs/sidebar.mjs b/website/docs/sidebar.mjs index 98955fd82a3b..78962a18d58b 100644 --- a/website/docs/sidebar.mjs +++ b/website/docs/sidebar.mjs @@ -318,6 +318,7 @@ const items = [ "add-secure-apps/flows-stages/stages/captcha/index", "add-secure-apps/flows-stages/stages/deny", "add-secure-apps/flows-stages/stages/email/index", + "add-secure-apps/flows-stages/stages/endpoint/index", "add-secure-apps/flows-stages/stages/identification/index", "add-secure-apps/flows-stages/stages/invitation/index", "add-secure-apps/flows-stages/stages/mtls/index", @@ -675,6 +676,138 @@ const items = [ { //#endregion + //#region Endpoint Devices + type: "category", + label: "Endpoint Devices (Early Preview)", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/index", + }, + items: [ + { + //#endregion + + //#region authentik Agent + type: "category", + label: "authentik Agent", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/authentik-agent/index", + }, + items: [ + "endpoint-devices/authentik-agent/configuration", + { + //#endregion + + //#region authentik Agent Deployment + type: "category", + label: "Deployment", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/authentik-agent/agent-deployment/index", + }, + items: [ + "endpoint-devices/authentik-agent/agent-deployment/mdm", + "endpoint-devices/authentik-agent/agent-deployment/linux", + "endpoint-devices/authentik-agent/agent-deployment/macos", + "endpoint-devices/authentik-agent/agent-deployment/windows", + ], + }, + "endpoint-devices/authentik-agent/authentik-cli", + "endpoint-devices/authentik-agent/development", + { + //#endregion + + //#region authentik Agent Release Notes + type: "category", + label: "Release notes", + description: "Release Notes for recent authentik agent versions", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/authentik-agent/release-notes/index", + }, + items: ["endpoint-devices/authentik-agent/release-notes/temp"], + }, + ], + }, + "endpoint-devices/manage-devices", + { + //#endregion + + //#region Device Authentication + type: "category", + label: "Device authentication", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/device-authentication/index", + }, + items: [ + "endpoint-devices/device-authentication/device-access-groups", + { + //#endregion + + //#region local device login + type: "category", + label: "Local device login", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/device-authentication/local-device-login/index", + }, + items: [ + "endpoint-devices/device-authentication/local-device-login/linux", + "endpoint-devices/device-authentication/local-device-login/windows", + ], + }, + "endpoint-devices/device-authentication/ssh-authentication", + "endpoint-devices/device-authentication/sudo-authorization", + { + //#endregion + + //#region cli app authentication + type: "category", + label: "CLI application authentication", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/device-authentication/cli-app-authentication/index", + }, + items: [ + "endpoint-devices/device-authentication/cli-app-authentication/aws", + "endpoint-devices/device-authentication/cli-app-authentication/k8s", + ], + }, + ], + }, + { + //#endregion + + //#region Device Compliance + type: "category", + label: "Device compliance", + collapsed: true, + link: { + type: "doc", + id: "endpoint-devices/device-compliance/index", + }, + items: [ + "endpoint-devices/device-compliance/configuration", + "endpoint-devices/device-compliance/connectors", + "endpoint-devices/device-compliance/device-reporting", + "endpoint-devices/device-compliance/device-compliance-policy", + "endpoint-devices/device-compliance/browser-extension", + ], + }, + ], + }, + { + //#endregion + //#region Developer Documentation type: "category", label: "Developer Documentation",