some file

Okta

Okta is a cloud-based identity and access management service for enterprise use, providing single sign-on, multi-factor authentication, and lifecycle management.

Add Okta 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
  • Okta Workforce Identity Cloud account

Step 1: Create OIDC Application in Okta

  1. Navigate to Okta Admin Dashboard
  2. Click Applications → Applications
  3. Click Create App Integration
  4. Select:
    • Sign-in method: OIDC - OpenID Connect
    • Application type: Web Application
  5. Click Next
  6. Fill in:
    • App integration name: NetBird
    • Grant type: Authorization Code
    • Leave redirect URIs empty for now
  7. Click Save
  8. Note the Client ID and Client Secret

Step 2: 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:
FieldValue
TypeOkta
NameOkta (or your preferred display name)
Client IDFrom Okta application
Client SecretFrom Okta application
IssuerYour Okta URL (e.g., https://your-org.okta.com)
  1. Click Save

Step 3: Configure Redirect URI

After saving, NetBird displays the Redirect URL. Copy this URL and add it to your Okta application:

  1. Return to Okta Admin → Applications → NetBird
  2. Click Edit in the General Settings
  3. Add the redirect URL from NetBird to Sign-in redirect URIs
  4. Click Save

Step 4: Test the Connection

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

Standalone Setup (Advanced)

Use Okta 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 Okta administrators as it also requires additional setup and ongoing maintenance.

For most deployments, the embedded IdP 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) section above.

If you prefer to have full control over authentication, consider self-hosted alternatives like Keycloak.

Prerequisites

Step 1: Create Single-Page Application

  1. Navigate to Okta Admin Dashboard
  2. Click Applications → Applications
  3. Click Create App Integration
  4. Select:
    • Sign-in method: OIDC - OpenID Connect
    • Application type: Single-Page Application
  5. Click Next

New SPA application

  1. Fill in:
    • App integration name: Netbird
    • Grant type: Authorization Code and Refresh Token
    • Sign-in redirect URIs:
      • https://<yournetbirddomain.com>/auth
      • https://<yournetbirddomain.com>/silent-auth
      • http://localhost:53000
    • Sign-out redirect URIs: https://<yournetbirddomain.com>/
  2. Click Save

SPA application config

  1. Note the Client ID
  2. Click Sign On tab
  3. Under OpenID Connect ID Token, click Edit and set Issuer to use the Okta URL
  4. Click Save

Sign-on configuration

Step 2: Create Native Application (for Device Auth)

  1. Click Applications → Applications
  2. Click Create App Integration
  3. Select:
    • Sign-in method: OIDC - OpenID Connect
    • Application type: Native Application
  4. Click Next

New native application

  1. Fill in:
    • App integration name: Netbird Native App
    • Grant type: Device Authorization
  2. Click Save

Native application config

  1. Note the Client ID (for device auth)
  2. Click Sign On tab
  3. Under OpenID Connect ID Token, set Issuer to use the Okta URL
  4. Click Save

Native sign-on configuration

Step 3: Generate API Token

  1. Click Security → API
  2. Click Tokens tab
  3. Click Create token
  4. Enter:
    • Name: Netbird
  5. Click Create token
  6. Copy the token value and click OK, got it

Generate token

Step 4: Configure NetBird

Your authority OIDC configuration will be available at:

https://<YOUR_OKTA_ORGANIZATION_URL>/.well-known/openid-configuration

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

Set properties in the setup.env file:

NETBIRD_DOMAIN="<YOUR_DOMAIN>"
NETBIRD_AUTH_OIDC_CONFIGURATION_ENDPOINT="https://<YOUR_OKTA_ORGANIZATION_URL>/.well-known/openid-configuration"
NETBIRD_USE_AUTH0=false
NETBIRD_AUTH_AUDIENCE="<NETBIRD_CLIENT_ID>"
NETBIRD_AUTH_CLIENT_ID="<NETBIRD_CLIENT_ID>"
NETBIRD_AUTH_SUPPORTED_SCOPES="openid profile email"
NETBIRD_AUTH_REDIRECT_URI="/auth"
NETBIRD_AUTH_SILENT_REDIRECT_URI="/silent-auth"
NETBIRD_TOKEN_SOURCE="idToken"

NETBIRD_AUTH_DEVICE_AUTH_PROVIDER="hosted"
NETBIRD_AUTH_DEVICE_AUTH_CLIENT_ID="<NETBIRD_NATIVE_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_AUDIENCE="<NETBIRD_NATIVE_CLIENT_ID>"
NETBIRD_AUTH_DEVICE_AUTH_SCOPE="openid email"
NETBIRD_AUTH_DEVICE_AUTH_USE_ID_TOKEN=true

NETBIRD_MGMT_IDP="okta"
NETBIRD_IDP_MGMT_EXTRA_API_TOKEN="<API_TOKEN>"

Step 5: Continue with NetBird Setup

You've configured all required resources in Okta. Continue with the NetBird Self-hosting Guide.

Troubleshooting

"Invalid redirect URI" error

  • Ensure all redirect URIs are configured in Okta
  • Check for trailing slashes
  • Verify the application type matches the use case

"Invalid issuer" error

  • Ensure the issuer is set to use the Okta URL (not dynamic)
  • Verify the OIDC configuration endpoint returns valid JSON

Device authorization not working

  • Ensure the native application has "Device Authorization" grant type
  • Verify the native client ID is used for device auth settings

Users not syncing

  • Verify the API token is valid and not expired
  • Check that the token has appropriate permissions