mirror of
https://github.com/netbirdio/docs.git
synced 2026-04-18 08:26:35 +00:00
Added JWT group sync instructions for each IdP (#545)
* Added JWT group sync instructions for each IdP
This commit is contained in:
shuuri-labs
@@ -114,6 +114,35 @@ Add Authentik as an external IdP directly in the NetBird Management Dashboard. T
|
||||
3. Click it and authenticate with your Authentik credentials
|
||||
4. You should be redirected back to NetBird and logged in
|
||||
|
||||
### Configuring JWT 'groups' Claim
|
||||
|
||||
**Authentik includes a `groups` claim in the ID token by default through the `profile` scope.** However, you may need to verify the configuration and ensure groups are included in the token.
|
||||
|
||||
#### Step 1: Verify Scope Mappings
|
||||
|
||||
1. In Authentik admin, go to **Customization** → **Property Mappings**
|
||||
2. Find and click on **authentik default OAuth Mapping: OpenID 'profile'**
|
||||
3. Verify it includes group information, or create a custom mapping
|
||||
|
||||
#### Step 2: Configure Provider to Include Claims in ID Token
|
||||
|
||||
1. Go to **Applications** → **Providers**
|
||||
2. Edit your NetBird provider
|
||||
3. Under **Advanced protocol settings**, enable **Include claims in id_token**
|
||||
4. Ensure the **profile** and **groups** scopes are selected
|
||||
5. Click **Update**
|
||||
|
||||
#### Step 3: Enable JWT Group Sync in NetBird
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
Authentik returns group names (not IDs) in the `groups` claim. Groups are synced based on the user's group membership in Authentik.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Standalone Setup (Advanced)
|
||||
|
||||
@@ -146,6 +146,32 @@ This allows you to support different authentication methods for different user g
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/idp-login.png" alt="Multiple Identity Providers" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
### User Provisioning
|
||||
|
||||
#### JWT Group Sync
|
||||
|
||||
If you've connected an external IdP, NetBird can optionally fetch a user's groups via JWT claim. These groups automatically obtain representations within NetBird and will be applied to the corresponding NetBird user. To enable JWT group sync,
|
||||
navigate to Settings > Groups and toggle 'Enable JWT group sync'.
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/jwt-group-sync.png" alt="JWT Group Sync Settings" className="imagewrapper"/>
|
||||
</p>
|
||||
|
||||
Specify the JWT claim to be used as the user's groups list (normally 'groups'). You can optionally specify a 'JWT allow groups' - this group will need to exist in your chosen claim for the user in order for that user to be granted access to NetBird.
|
||||
Your IdP may require specific configuration in order to pass a groups claim to NetBird. For detailed per-IdP implementation steps, see below. If your IdP isn't on the list, refer to the project's documentation.
|
||||
|
||||
- [Google](/selfhosted/identity-providers/managed/google-workspace#configuring-jwt-groups-claim)
|
||||
- [Microsoft Entra ID](/selfhosted/identity-providers/managed/microsoft-entra-id#configuring-jwt-groups-claim)
|
||||
- [Okta](/selfhosted/identity-providers/managed/okta#configuring-jwt-groups-claim)
|
||||
- [JumpCloud](/selfhosted/identity-providers/managed/jumpcloud#configuring-jwt-groups-claim)
|
||||
- [Zitadel](/selfhosted/identity-providers/zitadel#configuring-jwt-groups-claim)
|
||||
- [PocketID](/selfhosted/identity-providers/pocketid#configuring-jwt-groups-claim)
|
||||
- [Authentik](/selfhosted/identity-providers/authentik#configuring-jwt-groups-claim)
|
||||
- [Keycloak](/selfhosted/identity-providers/keycloak#configuring-jwt-groups-claim)
|
||||
|
||||
#### SCIM
|
||||
NetBird supports provisioning users and groups through SCIM. However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
|
||||
|
||||
### Best Practices
|
||||
|
||||
1. **Start simple** - Begin with local users, add external providers as needed
|
||||
@@ -181,11 +207,6 @@ This allows you to support different authentication methods for different user g
|
||||
|
||||
For provider-specific troubleshooting, see the individual provider pages.
|
||||
|
||||
## User Provisioning (SCIM)
|
||||
|
||||
In addition to OIDC-based authentication, NetBird supports provisioning users and groups through SCIM.
|
||||
However, this functionality is not available in the open source Community Edition. It is offered only in the cloud-managed version of NetBird or through a [Commercial License](https://netbird.io/pricing#on-prem) for enterprise self-hosted deployments.
|
||||
|
||||
## Migration Guide and Backwards Compatibility
|
||||
|
||||
If you have an existing NetBird deployment using a standalone IdP (like Zitadel from the previous quickstart), you have several options:
|
||||
|
||||
@@ -142,6 +142,72 @@ Add Keycloak as an external IdP directly in the NetBird Management Dashboard. Th
|
||||
Users who authenticate via Keycloak will appear in your NetBird Users list with a Keycloak badge next to their name.
|
||||
</Note>
|
||||
|
||||
### Configuring JWT 'groups' Claim
|
||||
|
||||
To sync Keycloak groups with NetBird, you need to create a client scope with a group membership mapper.
|
||||
|
||||
#### Step 1: Create Groups Client Scope
|
||||
|
||||
1. In Keycloak Admin Console, ensure the `netbird` realm is selected
|
||||
2. Go to **Client scopes** → **Create client scope**
|
||||
3. Fill in:
|
||||
- **Name**: `groups`
|
||||
- **Type**: `Default`
|
||||
- **Include in token scope**: `On`
|
||||
4. Click **Save**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/jwt_create-client-scope.png" alt="Create client scope" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### Step 2: Add Group Membership Mapper
|
||||
|
||||
1. In the newly created `groups` client scope, go to the **Mappers** tab
|
||||
2. Click **Configure a new mapper**
|
||||
3. Select **Group Membership**
|
||||
4. Configure the mapper:
|
||||
- **Name**: `groups`
|
||||
- **Token Claim Name**: `groups`
|
||||
- **Full group path**: `Off` (recommended for cleaner group names)
|
||||
- **Add to ID token**: `On`
|
||||
- **Add to access token**: `On`
|
||||
- **Add to userinfo**: `On`
|
||||
- **Add to token introspection**: `Off`
|
||||
5. Click **Save**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/jwt_add-group-mapper.png" alt="Add group mapper" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### Step 3: Add Client Scope to NetBird Client
|
||||
|
||||
1. Go to **Clients** → **netbird** (your client)
|
||||
2. Go to the **Client scopes** tab
|
||||
3. Click **Add client scope**
|
||||
4. Select **groups** and add it as **Default**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/keycloak/jwt_add-client-scope.png" alt="Add client scope" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### Step 4: Create Groups and Assign Users
|
||||
|
||||
1. Go to **Groups** → **Create group**
|
||||
2. Create groups as needed (e.g., `admins`, `developers`)
|
||||
3. Go to **Users** → select a user → **Groups** tab
|
||||
4. Click **Join Group** and assign users to groups
|
||||
|
||||
#### Step 5: Enable JWT Group Sync in NetBird
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
If **Full group path** is enabled, group names will include the path (e.g., `/admins` or `/parent/child`). Disable it for cleaner names like `admins`.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Standalone Setup (Advanced)
|
||||
|
||||
@@ -99,6 +99,34 @@ To limit authentication to specific Google Workspace domains:
|
||||
2. Under **User type**, select **Internal** (Workspace only)
|
||||
3. For external apps, verify your domain to restrict access
|
||||
|
||||
### Configuring JWT 'groups' Claim
|
||||
|
||||
<Note>
|
||||
**Limitation:** Google's standard OIDC implementation does not include a `groups` claim in the JWT token. Unlike other identity providers, Google only provides minimal OIDC claims (email, name, profile) and does not expose group membership through the standard OIDC flow.
|
||||
</Note>
|
||||
|
||||
To sync Google Workspace groups with NetBird, you have two options:
|
||||
|
||||
#### Option 1: Use a Different Identity Provider (Recommended)
|
||||
|
||||
If group-based access control is important for your deployment, consider using an identity provider that natively supports the `groups` claim:
|
||||
|
||||
- [Keycloak](/selfhosted/identity-providers/keycloak) - Can federate with Google and add groups claims
|
||||
- [Authentik](/selfhosted/identity-providers/authentik) - Supports Google as a source with group mapping
|
||||
- [Zitadel](/selfhosted/identity-providers/zitadel) - Full OIDC support with groups
|
||||
|
||||
These providers can authenticate users via Google while adding proper group claims to the JWT.
|
||||
|
||||
#### Option 2: Manual Group Management in NetBird
|
||||
|
||||
If you don't need automatic group synchronization:
|
||||
|
||||
1. Authenticate users via Google as configured above
|
||||
2. Manually assign users to groups in NetBird Dashboard under **Team** → **Users**
|
||||
3. Use NetBird's built-in groups for access control policies
|
||||
|
||||
This approach works well for smaller teams where group membership doesn't change frequently.
|
||||
|
||||
<Note>
|
||||
Domain restrictions are configured in Google Cloud Console, not in NetBird.
|
||||
</Note>
|
||||
|
||||
@@ -114,6 +114,43 @@ Sometimes, the JumpCloud application configuration will add duplicate attributes
|
||||
3. Click it and authenticate with your JumpCloud 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 JumpCloud groups with NetBird, you need to enable the group attribute in your JumpCloud OIDC application.
|
||||
|
||||
#### Step 1: Enable Group Attributes in JumpCloud
|
||||
|
||||
1. In [JumpCloud Admin Portal](https://console.jumpcloud.com/), go to **Access** → **SSO Applications**
|
||||
2. Select your NetBird application
|
||||
3. Go to the **SSO** tab
|
||||
4. Under **Attribute Mapping**, find the **Group Attributes** section
|
||||
5. Check **Include group attribute**
|
||||
6. In **Groups Attribute Name**, enter: `groups`
|
||||
7. Click **Save**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/jumpcloud/jwt_add-groups-claim.png" alt="Add groups claim" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### Step 2: Assign User Groups to the Application
|
||||
|
||||
1. In your NetBird application, go to the **User Groups** tab
|
||||
2. Select the groups whose members should have access to NetBird
|
||||
3. Click **Save**
|
||||
|
||||
Users will receive group claims based on which assigned groups they belong to.
|
||||
|
||||
#### Step 3: Enable JWT Group Sync in NetBird
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
**Known issue:** If a user belongs to only one group, JumpCloud may return it as a string instead of an array, which can cause issues. Ensure users are members of at least two groups for consistent behavior, or test with your specific setup.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Standalone Setup (Advanced)
|
||||
|
||||
@@ -132,6 +132,57 @@ Add Microsoft as an external IdP directly in the NetBird Management Dashboard. C
|
||||
3. Click it and sign in with your Microsoft account
|
||||
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 Entra ID groups with NetBird, you need to configure your app registration to include group claims in the ID token.
|
||||
|
||||
#### Step 1: Configure Groups Claim in Azure
|
||||
|
||||
1. In [Entra Admin Center](https://entra.microsoft.com/), go to your app registration
|
||||
2. Navigate to **Token configuration**
|
||||
3. Click **Add groups claim**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/jwt_add-groups-claim.png" alt="Add groups claim" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
4. Select the group types to include:
|
||||
- **Security groups** - Recommended for most use cases
|
||||
- **Groups assigned to the application** - Recommended for large organizations (avoids token size limits)
|
||||
5. Under **Customize token properties by type**, expand **ID** and select:
|
||||
- **Group ID** - Returns Azure object IDs (default)
|
||||
6. Click **Add**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/microsoft-entra-id/jwt_configure-groups-claim.png" alt="Add groups claim" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
**Token size limit:** Entra ID limits groups to 200 in JWT tokens. If a user belongs to more groups, the claim is omitted entirely. Use **Groups assigned to the application** to avoid this by only including relevant groups.
|
||||
</Note>
|
||||
|
||||
#### Step 2: Assign Groups to the Application (Recommended)
|
||||
|
||||
If you selected "Groups assigned to the application":
|
||||
|
||||
1. Go to **Enterprise applications** in Entra Admin Center
|
||||
2. Find and select your NetBird application
|
||||
3. Go to **Users and groups**
|
||||
4. Click **Add user/group**
|
||||
5. Select the groups you want to sync with NetBird
|
||||
6. Click **Assign**
|
||||
|
||||
#### Step 3: Enable JWT Group Sync in NetBird
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
Entra ID returns group **object IDs** (GUIDs) by default, not group names. Your NetBird groups will appear as IDs like `a1b2c3d4-5678-90ab-cdef-1234567890ab`. To use display names instead, you need Azure AD Premium and cloud-only groups. [NetBird Cloud](https://netbird.io/) does not have this limitation—it syncs group names directly via the Microsoft integration.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Standalone Setup (Advanced)
|
||||
|
||||
@@ -102,6 +102,60 @@ Add Okta as an external IdP directly in the NetBird Management Dashboard. This i
|
||||
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**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/8_add-groups-claim.png" alt="Groups claim configuration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### 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**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/managed/okta/9_add-groups-claim-api.png" alt="Custom authorization server groups claim configuration" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<Note>
|
||||
The groups claim has a limit of 100 groups. If a user belongs to more than 100 groups that match the filter, the request will fail. Use a more specific filter (e.g., `^NetBird-.*`) to limit the groups included.
|
||||
</Note>
|
||||
|
||||
#### 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)
|
||||
|
||||
@@ -126,6 +126,27 @@ After saving, NetBird displays the **Redirect URL**. Copy this URL and add it to
|
||||
3. Click it and authenticate with your PocketID credentials
|
||||
4. You should be redirected back to NetBird and logged in
|
||||
|
||||
### Configuring JWT 'groups' Claim
|
||||
|
||||
PocketID includes user groups in the ID token by default when you've assigned groups to users and linked those groups to the OIDC client. If you followed Step 4 above, groups should already be included in the token.
|
||||
|
||||
#### Verify Groups Are Included
|
||||
|
||||
1. Ensure you've created a User Group in PocketID (Step 4)
|
||||
2. Ensure users are assigned to the group
|
||||
3. Ensure the group is linked to your NetBird OIDC client
|
||||
|
||||
#### Enable JWT Group Sync in NetBird
|
||||
|
||||
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 to users in specific PocketID groups
|
||||
|
||||
<Note>
|
||||
PocketID restricts OIDC client access based on group membership. Only users in groups assigned to the OIDC client can authenticate. This is configured in Step 4 above.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Standalone Setup (Advanced)
|
||||
|
||||
@@ -135,6 +135,72 @@ Add Zitadel as an external IdP directly in the NetBird Management Dashboard. Thi
|
||||
3. Click it and authenticate with your Zitadel credentials
|
||||
4. You should be redirected back to NetBird and logged in
|
||||
|
||||
### Configuring JWT 'groups' Claim
|
||||
|
||||
Zitadel uses **roles** instead of groups. By default, Zitadel's role claims use a nested JSON object format, but NetBird expects a flat array of strings. You'll need to create a Zitadel Action to transform roles into a `groups` claim.
|
||||
|
||||
#### Step 1: Create the Groups Action
|
||||
|
||||
1. In Zitadel Console, go to **Actions**
|
||||
2. Click **New**
|
||||
3. Fill in:
|
||||
- **Name**: `groupsClaim`
|
||||
4. Add the following script:
|
||||
|
||||
```javascript
|
||||
function groupsClaim(ctx, api) {
|
||||
if (ctx.v1.user.grants == undefined || ctx.v1.user.grants.count == 0) {
|
||||
return;
|
||||
}
|
||||
let groups = [];
|
||||
ctx.v1.user.grants.grants.forEach(claim => {
|
||||
claim.roles.forEach(role => {
|
||||
groups.push(role);
|
||||
});
|
||||
});
|
||||
api.v1.claims.setClaim('groups', groups);
|
||||
}
|
||||
```
|
||||
|
||||
5. Click **Add**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/jwt_create-action.png" alt="Create action" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### Step 2: Configure Action Triggers
|
||||
|
||||
1. Go to **Actions** → **Flows**
|
||||
2. Select **Complement Token**
|
||||
3. Add triggers for the `groupsClaim` action:
|
||||
- **Pre Userinfo creation**
|
||||
- **Pre access token creation**
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/jwt_add-trigger.png" alt="Add trigger" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
<p>
|
||||
<img src="/docs-static/img/selfhosted/identity-providers/self-hosted/zitadel/jwt_triggers.png" alt="Add trigger" className="imagewrapper-big"/>
|
||||
</p>
|
||||
|
||||
#### Step 3: Assign Roles to Users
|
||||
|
||||
1. Go to your **Project** in Zitadel
|
||||
2. Navigate to **Roles** and create roles (e.g., `admin`, `developer`)
|
||||
3. Go to **Authorizations** and assign roles to users
|
||||
|
||||
#### Step 4: Enable JWT Group Sync in NetBird
|
||||
|
||||
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
|
||||
|
||||
<Note>
|
||||
The action transforms Zitadel's role structure into a flat array. If you need to include project context, modify the script to use `groups.push(role + ':' + claim.projectId)`.
|
||||
</Note>
|
||||
|
||||
---
|
||||
|
||||
## Standalone Setup (Advanced)
|
||||
|
||||
Reference in New Issue
Block a user