netbird-docs/src/pages/selfhosted/identity-providers/authentik.mdx

import {Note} from "@/components/mdx";

# Authentik

[Authentik](https://goauthentik.io) is an open-source identity provider focused on flexibility and security. It serves as a self-hosted alternative to commercial solutions like Okta and Auth0, providing single sign-on (SSO), multi-factor authentication (MFA), access policies, user management, and support for SAML and OIDC protocols.

## Connector Setup (Recommended)

Add Authentik as a connector to the embedded IdP. This is the simplest approach and recommended for most deployments.

### Prerequisites

- NetBird self-hosted with embedded IdP enabled
- Authentik instance with admin access

### Step 1: Create OAuth2/OpenID Provider in Authentik

1. Navigate to Authentik admin interface
2. Click **Applications** on the left menu, then click **Providers**
3. Click **Create** to create a new provider
4. Select **OAuth2/OpenID Provider** and click **Next**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-type.png" alt="Select provider type" className="imagewrapper-big"/>
</p>

5. Fill in the form with the following values:
   - **Name**: `NetBird`
   - **Authentication Flow**: `default-authentication-flow (Welcome to authentik!)`
   - **Authorization Flow**: `default-provider-authorization-explicit-consent (Authorize Application)`
   - **Client type**: `Confidential`
   - **Redirect URIs/Origins**: Leave empty for now (you'll add this after creating the connector in NetBird)
   - **Signing Key**: Select any cert present, e.g., `authentik Self-signed Certificate`

6. Click **Finish**
7. Note the **Client ID** and **Client Secret**

### Step 2: Create Application in Authentik

1. Click **Applications** on the left menu, then click **Applications**
2. Click **Create** to create a new application
3. Fill in the form:
   - **Name**: `NetBird`
   - **Slug**: `netbird`
   - **Provider**: Select the `NetBird` provider you created
4. Click **Create**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-application.png" alt="Create application" className="imagewrapper-big"/>
</p>

### Step 3: Add Connector in NetBird

1. Log in to your NetBird Dashboard
2. Navigate to **Settings** → **Identity Providers**
3. Click **Add Identity Provider**
4. Fill in the fields:

| Field | Value |
|-------|-------|
| Type | Generic OIDC |
| Name | Authentik (or your preferred display name) |
| Client ID | From Authentik provider |
| Client Secret | From Authentik provider |
| Issuer | `https://authentik.example.com/application/o/netbird/` |

5. Click **Save**

### Step 4: Configure Redirect URI

After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to your Authentik provider:

1. Return to Authentik admin → **Providers** → **NetBird**
2. Click **Edit**
3. Under **Redirect URIs/Origins**, add the redirect URL from NetBird
4. Click **Update**

### Step 5: Test the Connection

1. Log out of NetBird Dashboard
2. On the login page, you should see an "Authentik" button
3. Click it and authenticate with your Authentik credentials
4. You should be redirected back to NetBird and logged in

---

## Standalone Setup (Advanced)

Use Authentik as your primary identity provider instead of NetBird's embedded IdP. This option gives you full control over authentication and user management, is recommended for experienced Authentik administrators as it also requires additional setup and ongoing maintenance.

For most deployments, the [embedded IdP](/selfhosted/identity-providers/local) is the simpler choice — it's built into NetBird, fully integrated, and requires minimal configuration to get started. For this implementation, go back up to the [Connector Setup (Recommended)](#connector-setup-recommended) section above.

<Note>
If you prefer not to self-host an Identity and Access Management solution, you could use a managed alternative like [Auth0](/selfhosted/identity-providers/managed/auth0).
</Note>

### Prerequisites

- Authentik instance running with SSL
- Docker and Docker Compose installed for NetBird

### Step 1: Create OAuth2/OpenID Provider

Follow steps 1-2 from the connector setup above, but configure the provider as follows:

- **Client type**: `Public`
- **Redirect URIs/Origins (RegEx)**:
  - Regex: `https://<domain>/.*`
  - Strict: `http://localhost:53000`
- **Advanced protocol settings**:
  - Access code validity: `minutes=10`
  - Subject mode: `Based on the User's ID`

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-provider-config.png" alt="Provider configuration" className="imagewrapper-big"/>
</p>

Take note of **Client ID** for later use.

### Step 2: Create Application

Follow step 2 from the connector setup to create the NetBird application.

### Step 3: Create Service Account

1. Navigate to Authentik admin interface
2. Click **Directory** on the left menu, then click **Users**
3. Click **Create Service Account**
4. Fill in the form:
   - **Username**: `Netbird`
   - **Create Group**: Disable
5. Click **Create**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-service-account.png" alt="Create service account" className="imagewrapper-big"/>
</p>

6. Note the service account username
7. Create an app password: Go to **Directory** → **Tokens and App passwords**
8. Create a new app password, selecting the NetBird service account as the **User**
9. Save the app password for later use

### Step 4: Add Service Account to Admin Group

1. Click **Directory** on the left menu, then click **Groups**
2. Click **authentik Admins** from the list and select **Users** tab
3. Click **Add existing user** and click **+** button
4. Select **Netbird** and click **Add**
5. Disable **Hide service-accounts** and verify the user is added

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-add-user-group.png" alt="Add user to group" className="imagewrapper-big"/>
</p>

### Step 5: Create Device Code Flow

1. Click **Flows and Stages** on the left menu, then click **Flows** → **Create**
2. Fill in the form:
   - **Name**: `default-device-code-flow`
   - **Title**: `Device Code Flow`
   - **Designation**: `Stage Configuration`
   - **Authentication**: `Require authentication`
3. Click **Create**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-new-device-flow.png" alt="Create device flow" className="imagewrapper-big"/>
</p>

4. Click **System** on the left menu, then click **Brands**
5. Click edit on **authentik-default**
6. Under **Default flows**, set **Device code flow** to `default-device-code-flow`
7. Click **Update**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/authentik-brand-device-flow.png" alt="Configure brand device flow" className="imagewrapper-big"/>
</p>

### Step 6: Configure NetBird

Your authority OIDC configuration will be available at:

```bash
https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration
```

<Note>
Double-check if the endpoint returns a JSON response by calling it from your browser.
</Note>

Set properties in the `setup.env` file:

```shell
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_AUTHENTIK_HOST_AND_PORT>/application/o/netbird/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email offline_access api"
NETBIRD_AUTH_AUDIENCE="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<PROVIDER_CLIENT_ID>"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"

NETBIRD_MGMT_IDP="authentik"
NETBIRD_IDP_MGMT_CLIENT_ID="<PROVIDER_CLIENT_ID>"
NETBIRD_IDP_MGMT_EXTRA_USERNAME="Netbird"
NETBIRD_IDP_MGMT_EXTRA_PASSWORD="<SERVICE_ACCOUNT_PASSWORD>"

# Needs disabling due to issue with IdP. Learn more: https://github.com/netbirdio/netbird/issues/3654
NETBIRD_AUTH_PKCE_DISABLE_PROMPT_LOGIN=true
```

### Step 7: Continue with NetBird Setup

You've configured all required resources in Authentik. Continue with the [NetBird Self-hosting Guide](/selfhosted/selfhosted-guide#step-4-disable-single-account-mode-optional).

---

## Troubleshooting

### "Invalid redirect URI" error

- Ensure the redirect URI exactly matches what NetBird provides
- For connector setup: Copy the exact URL from the success modal
- For standalone: Use regex pattern `https://<domain>/.*`

### Authentication fails silently

- Verify a signing key is selected in the provider configuration
- Check that the application is linked to the correct provider

### Service account authentication fails

- Ensure you're using the app password, not the account password
- Verify the service account is in the authentik Admins group

---

## Related Resources

- [Authentik Documentation](https://goauthentik.io/docs/)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)