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.

## Management Setup (Recommended)

Add Authentik as an external IdP directly in the NetBird Management Dashboard. 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

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

4. Select **OAuth2/OpenID Provider** and click **Next**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/2_type-oauth2-athentik.png" alt="Select OAuth2/OpenID Provider type" className="imagewrapper-big"/>
</p>

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

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/3_new-provider-auth-flow-athentik.png" alt="Provider configuration with authorization flow" className="imagewrapper-big"/>
</p>

6. Click **Finish**
7. Note the **Client ID** and **Client Secret** — you'll need these for Step 3

### Step 2: Create Application in Authentik

1. Click **Applications** on the left menu, then click **Applications**
2. Click **Create** to create a new application

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

3. Fill in the form:
   - **Name**: `NetBird`
   - **Slug**: `netbird`
   - **Provider**: Select the `NetBird` provider you created in Step 1

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/5_app-name-slug-athentik.png" alt="Application name and slug" className="imagewrapper-big"/>
</p>

4. Click **Create**

### Step 3: Get Redirect URL from NetBird

1. Open a new tab or window and 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 (from Step 1) |
| Client Secret | From Authentik provider (from Step 1) |
| Issuer | `https://authentik.example.com/application/o/netbird/` |

5. **Copy the Redirect URL** that NetBird displays (but don't click **Add Provider** yet)

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/6_netbird-config-copy-url-athentik.png" alt="NetBird configuration and copy redirect URL" className="imagewrapper-big"/>
</p>

### Step 4: Configure Redirect URI in Authentik

1. Return to Authentik admin → **Providers** → **NetBird**
2. Click **Edit**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/7_providers-edit-uri.png" alt="Edit provider redirect URIs" className="imagewrapper-big"/>
</p>

3. Under **Redirect URIs/Origins**, add the redirect URL you copied from NetBird
4. Select **Strict** (not Regex) to match the exact URL from NetBird

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/self-hosted/authentik/8_add-uri-strict-athentik.png" alt="Add redirect URI in Strict mode" className="imagewrapper-big"/>
</p>

5. Click **Update**

### Step 5: Complete NetBird Setup

1. Return to the NetBird tab
2. Click **Add Provider**

### Step 6: 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 [Management Setup (Recommended)](#management-setup-recommended) section above.

For detailed instructions on the standalone setup, see the [Authentik SSO with NetBird Self-Hosted (Advanced)](/selfhosted/identity-providers/advanced/authentik) documentation.

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

---

## Troubleshooting

### "Invalid redirect URI" error

- Ensure the redirect URI exactly matches what NetBird provides
- Copy the exact URL from the success modal

### Authentication fails silently

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

---

## Related Resources

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