Okta SSO with NetBird Self-Hosted

Okta 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

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

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:

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

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

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

Step 4: Complete NetBird Setup

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

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.

Configuring JWT 'groups' Claim

To sync Okta groups with NetBird, you need to configure Okta to include a groups claim in the ID token. There are two methods depending on your Okta setup.

Method 1: Application-Level Configuration (Recommended)

This method works with Okta's org authorization server and is the simplest approach:

1. In Okta Admin Console, go to Applications → Applications
2. Select your NetBird application
3. Go to the Sign On tab
4. Click Edit in the OpenID Connect ID Token section
5. Under Group claim type, select Filter
6. In Group claims filter:
   • Claim name: groups
   • Filter: Select Matches regex and enter .* (to include all groups)
7. Click Save

Method 2: Custom Authorization Server

If you're using a custom authorization server (required for access token claims):

1. In Okta Admin Console, go to Security → API
2. Select your custom authorization server
3. Go to the Claims tab
4. Click Add Claim
5. Configure the claim:
   • Name: groups
   • Include in token type: ID Token (select Always)
   • Value type: Groups
   • Filter: Select Matches regex and enter .*
6. Click Create

Enable JWT Group Sync in NetBird

After configuring Okta:

1. In NetBird Dashboard, go to Settings → Groups
2. Enable JWT group sync
3. Set JWT claim to groups
4. Optionally configure JWT allow groups to restrict access

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 Management Setup (Recommended) section above.

For detailed instructions on the standalone setup, see the Okta SSO with NetBird Self-Hosted (Legacy) documentation.

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
• Okta Admin Console
• Embedded IdP Overview