netbird-docs/src/pages/selfhosted/identity-providers/managed/okta.mdx

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

# Okta SSO with NetBird Self-Hosted

[Okta](https://www.okta.com/) is a cloud-based identity and access management service for enterprise use, providing single sign-on, multi-factor authentication, and lifecycle management.

## Management Setup (Recommended)

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

### Step 1: Start Creating OIDC Application in Okta

1. Navigate to Okta Admin Dashboard
2. Click **Applications** → **Applications**
3. Click **Create App Integration**

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/1_create-app-integration-okta.png" alt="Create app integration" className="imagewrapper-big"/>
</p>

4. Select:
   - **Sign-in method**: `OIDC - OpenID Connect`
   - **Application type**: `Web Application`

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/2_oidc-web-app-okta.png" alt="OIDC Web Application" className="imagewrapper-big"/>
</p>

5. Click **Next**
6. Fill in:
   - **App integration name**: `NetBird`
   - **Grant type**: `Authorization Code`
   - Leave redirect URIs empty for now (you'll add this in Step 3)
7. Under **Assignments**, select an option for controlled access:
   - **Allow everyone in your organization to access** (recommended for testing)
   - **Limit access to selected groups** (for production)
   - **Skip group assignment for now** (assign later)

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/3_assignments-okta.png" alt="Assignments" className="imagewrapper-big"/>
</p>

8. **Don't click Save yet** — keep this tab open and proceed to Step 2

### Step 2: 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 | Okta |
| Name | Okta (or your preferred display name) |
| Client ID | From Okta application (will fill after Step 3) |
| Client Secret | From Okta application (will fill after Step 3) |
| Issuer | Your Okta URL (e.g., `https://your-org.okta.com`) |

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

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/4_redirect-url-okta.png" alt="Copy redirect URL" className="imagewrapper-big"/>
</p>

### Step 3: Complete Okta Application Setup

1. Return to the Okta tab
2. In the **Sign-in redirect URIs** field, paste the redirect URL you copied from NetBird

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/5_sign-in-uri-okta.png" alt="Sign-in redirect URIs" className="imagewrapper-big"/>
</p>

3. Click **Save**
4. Note the **Client ID** and **Client Secret** — you'll need these for Step 4

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/6_client-id-okta.png" alt="Client ID" className="imagewrapper-big"/>
</p>

### Step 4: Complete NetBird Setup

1. Return to the NetBird tab
2. Fill in the **Client ID** and **Client Secret** from Step 3

<p>
    <img src="/docs-static/img/selfhosted/identity-providers/managed/okta/7_complte-config-okta.png" alt="Complete configuration" className="imagewrapper-big"/>
</p>

3. Click **Add Provider**

### Step 5: 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. Unless your user approval setting were changed you will need to log back into your local admin account to approve the user.

---

## 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](/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 [Okta SSO with NetBird Self-Hosted (Legacy)](/selfhosted/identity-providers/managed/advanced/okta) documentation.

<Note>
If you prefer to have full control over authentication, consider self-hosted alternatives like [PocketID](/selfhosted/identity-providers/pocketid).
</Note>

---

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

---

## Related Resources

- [Okta Developer Documentation](https://developer.okta.com/docs/)
- [Okta Admin Console](https://help.okta.com/en/prod/Content/Topics/Apps/Apps_App_Integration_Wizard_OIDC.htm)
- [Embedded IdP Overview](/selfhosted/identity-providers/local)