[GH-ISSUE #5143] Generic OIDC authentication fails if "name"-claim is missing (no configurable fallback) #10648

Open
opened 2026-08-05 01:26:45 -04:00 by saavagebueno · 12 comments
Owner

Originally created by @ecdlguy on GitHub (Jan 20, 2026).
Original GitHub issue: https://github.com/netbirdio/netbird/issues/5143

Describe the problem

Authentication via Generic OIDC fails in NetBird self-hosted v0.63.0 with the error
Failed to authenticate: missing "name" claim, even though the external OIDC provider is compliant and authentication succeeds.

NetBird currently hard-requires the name claim, but provides no way to configure an alternative claim (e.g. sub, username, or email) for user identification when using the new Dashboard-based IdP integration. As a result, Generic OIDC is unusable with providers that do not emit a name claim and cannot be customized (e.g. Synology SSO).


To Reproduce

Steps to reproduce the behavior:

  1. Deploy NetBird self-hosted control plane version 0.63.0
  2. Open the NetBird Dashboard
  3. Go to Identity Providers
  4. Add a new provider of type Generic OIDC
  5. Configure client ID, client secret, and issuer URL of an external OIDC provider
  6. Login via the external IdP
  7. After successful authentication and redirect back to the NetBird dashboard, observe the error
    Failed to authenticate: missing "name" claim

Expected behavior

NetBird should either:

  • allow configuring which OIDC claim is used as the user identifier / display name (e.g. sub, username, email), or
  • fall back to a reasonable default claim if name is not present.

Authentication should succeed for OIDC-compliant providers that do not emit a name claim.


Are you using NetBird Cloud?

No, NetBird is self-hosted (control plane).


NetBird version

netbird version
0.63.0

Is any other VPN software installed?

No.


Debug output

Not attached yet.

The issue occurs before the client establishes a session and is reproducible solely through the dashboard login flow using Generic OIDC.

If required, debug output and a debug bundle can be provided.


Screenshots

Not applicable. The error message is displayed as plain text in the NetBird dashboard:

Failed to authenticate: missing "name" claim

Additional context

  • This issue appeared after migrating to the new Dashboard-based IdP integration introduced in recent versions.
  • Older self-hosted setups allowed configuring user identification via options such as AuthUserIDClaim and AUTH_SUPPORTED_SCOPES.
  • These options no longer apply to Dashboard-based Identity Providers.
  • The Management API also does not expose any fields to configure claim mapping.
  • The external IdP (Synology SSO) is OIDC-compliant but does not emit a name claim and cannot be customized.
  • This is not specific to Synology; any OIDC provider without a name claim is affected.
  • Switching to a more flexible IdP would technically resolve the issue. However, this is not a realistic workaround: the existing SSO is already integrated with more than 10 production services, and replacing it would require extensive reconfiguration and validation across all of them, introducing unnecessary risk and operational overhead for what is effectively a client-side claim-mapping limitation.

Have you tried these troubleshooting steps?

  • Reviewed client troubleshooting documentation
  • Checked for newer NetBird versions
  • Searched for similar issues on GitHub (including closed ones)
  • Restarted the NetBird client
  • Disabled other VPN software (not applicable)
  • Checked firewall settings
Originally created by @ecdlguy on GitHub (Jan 20, 2026). Original GitHub issue: https://github.com/netbirdio/netbird/issues/5143 **Describe the problem** Authentication via Generic OIDC fails in NetBird self-hosted v0.63.0 with the error `Failed to authenticate: missing "name" claim`, even though the external OIDC provider is compliant and authentication succeeds. NetBird currently hard-requires the `name` claim, but provides **no way to configure an alternative claim** (e.g. `sub`, `username`, or `email`) for user identification when using the new Dashboard-based IdP integration. As a result, Generic OIDC is unusable with providers that do not emit a `name` claim and cannot be customized (e.g. Synology SSO). --- **To Reproduce** Steps to reproduce the behavior: 1. Deploy NetBird self-hosted control plane version 0.63.0 2. Open the NetBird Dashboard 3. Go to **Identity Providers** 4. Add a new provider of type **Generic OIDC** 5. Configure client ID, client secret, and issuer URL of an external OIDC provider 6. Login via the external IdP 7. After successful authentication and redirect back to the NetBird dashboard, observe the error `Failed to authenticate: missing "name" claim` --- **Expected behavior** NetBird should either: * allow configuring which OIDC claim is used as the user identifier / display name (e.g. `sub`, `username`, `email`), or * fall back to a reasonable default claim if `name` is not present. Authentication should succeed for OIDC-compliant providers that do not emit a `name` claim. --- **Are you using NetBird Cloud?** No, NetBird is self-hosted (control plane). --- **NetBird version** ``` netbird version 0.63.0 ``` --- **Is any other VPN software installed?** No. --- **Debug output** Not attached yet. The issue occurs before the client establishes a session and is reproducible solely through the dashboard login flow using Generic OIDC. If required, debug output and a debug bundle can be provided. --- **Screenshots** Not applicable. The error message is displayed as plain text in the NetBird dashboard: ``` Failed to authenticate: missing "name" claim ``` --- **Additional context** * This issue appeared after migrating to the new Dashboard-based IdP integration introduced in recent versions. * Older self-hosted setups allowed configuring user identification via options such as `AuthUserIDClaim` and `AUTH_SUPPORTED_SCOPES`. * These options no longer apply to Dashboard-based Identity Providers. * The Management API also does not expose any fields to configure claim mapping. * The external IdP (Synology SSO) is OIDC-compliant but does not emit a `name` claim and cannot be customized. * This is not specific to Synology; any OIDC provider without a `name` claim is affected. * Switching to a more flexible IdP would technically resolve the issue. However, this is not a realistic workaround: the existing SSO is already integrated with more than 10 production services, and replacing it would require extensive reconfiguration and validation across all of them, introducing unnecessary risk and operational overhead for what is effectively a client-side claim-mapping limitation. --- **Have you tried these troubleshooting steps?** * [x] Reviewed client troubleshooting documentation * [x] Checked for newer NetBird versions * [x] Searched for similar issues on GitHub (including closed ones) * [x] Restarted the NetBird client * [ ] Disabled other VPN software (not applicable) * [x] Checked firewall settings
saavagebueno added the triage-needed label 2026-08-05 01:26:45 -04:00
Author
Owner

@ecdlguy commented on GitHub (Jan 22, 2026):

I set up a standalone Dex instance and was able to successfully authenticate against the same IdP using the following configuration:

connectors:
- type: oidc
  id: synology
  name: Synology-SSO
  config:
    issuer: https://myidp.com
    clientID: ***
    clientSecret: ***
    redirectURI: https://mydex.com/callback
    scopes:
      - openid
      - email
      - groups
    userIDKey: sub
    userNameKey: username
    insecureSkipEmailVerified: true
    insecureEnableGroups: true
    claimMapping:
      preferred_username: username

This demonstrates that Dex itself is fully capable of interoperating with this IdP by adjusting connector-specific parameters such as claim mappings and user identity keys.

Since NetBird now relies on Dex internally for OIDC authentication, it would be highly beneficial if the NetBird UI or configuration allowed passing through or customizing these connector parameters (e.g. userIDKey, userNameKey, claimMapping, scopes, etc.).
At the moment, the fixed expectations around certain claims (notably name) make it impossible to integrate otherwise standards-compliant OIDC providers that cannot be adjusted on the IdP side.

<!-- gh-comment-id:3784051451 --> @ecdlguy commented on GitHub (Jan 22, 2026): I set up a standalone Dex instance and was able to successfully authenticate against the same IdP using the following configuration: ```yaml connectors: - type: oidc id: synology name: Synology-SSO config: issuer: https://myidp.com clientID: *** clientSecret: *** redirectURI: https://mydex.com/callback scopes: - openid - email - groups userIDKey: sub userNameKey: username insecureSkipEmailVerified: true insecureEnableGroups: true claimMapping: preferred_username: username ``` This demonstrates that Dex itself is fully capable of interoperating with this IdP by adjusting connector-specific parameters such as claim mappings and user identity keys. Since NetBird now relies on Dex internally for OIDC authentication, it would be highly beneficial if the NetBird UI or configuration allowed passing through or customizing these connector parameters (e.g. `userIDKey`, `userNameKey`, `claimMapping`, scopes, etc.). At the moment, the fixed expectations around certain claims (notably `name`) make it impossible to integrate otherwise standards-compliant OIDC providers that cannot be adjusted on the IdP side.
Author
Owner

@wolfjudge commented on GitHub (Jan 28, 2026):

We are running into the same issue, using RC Devs WebADM.

<!-- gh-comment-id:3810161418 --> @wolfjudge commented on GitHub (Jan 28, 2026): We are running into the same issue, using RC Devs WebADM.
Author
Owner

@man15h commented on GitHub (Jan 31, 2026):

Same issue while paired up with authelia

Workaround for Authelia users:

If you're using Authelia as your OIDC provider, you can fix the "missing 'name' claim" error by adding a claims_policy that forces the name claim into the ID token.

Add this to your Authelia configuration.yml:

identity_providers:
  oidc:
    # Add claims policy to include name claim in ID token
    claims_policies:
      netbird:
        id_token:
          - name
          - email
          - preferred_username
          - groups
    
    clients:
      - client_id: netbird
        client_name: Netbird
        claims_policy: netbird  # <-- Assign the policy here
        # ... rest of your client config

<!-- gh-comment-id:3829473073 --> @man15h commented on GitHub (Jan 31, 2026): Same issue while paired up with authelia Workaround for Authelia users: If you're using Authelia as your OIDC provider, you can fix the "missing 'name' claim" error by adding a claims_policy that forces the name claim into the ID token. Add this to your Authelia configuration.yml: ```yml identity_providers: oidc: # Add claims policy to include name claim in ID token claims_policies: netbird: id_token: - name - email - preferred_username - groups clients: - client_id: netbird client_name: Netbird claims_policy: netbird # <-- Assign the policy here # ... rest of your client config ```
Author
Owner

@FlashGordon86 commented on GitHub (Feb 1, 2026):

Same issue while paired up with authelia

Same. With authilia, too.

<!-- gh-comment-id:3832054671 --> @FlashGordon86 commented on GitHub (Feb 1, 2026): > Same issue while paired up with authelia > Same. With authilia, too.
Author
Owner

@ecdlguy commented on GitHub (Feb 4, 2026):

Following up on my previous comments, I’ve identified two additional critical limitations in the "OIDC Generic" implementation (tested with NetBird v0.64) that prevent a seamless integration with my IdP:

1. Missing Group Scope Request & Custom Claim Mapping

Currently, the "OIDC Generic" provider does not seem to request the groups scope by default. Even if a group claim is configured in the IdP settings, the sync fails because the scope is missing from the initial OIDC request.

  • Observation: Switching the provider type to Pocket ID solves this, as it explicitly requests the groups scope and correctly extracts the claim.
  • Requirement: Please add an option to the "OIDC Generic" configuration to explicitly enable/disable the groups scope request and allow mapping it to a custom claim (similar to the requested username/name mapping).

2. Custom End-Session-Endpoint URL (SLO)

Many OIDC providers (like Dex) do not expose an end_session_endpoint in their .well-known/openid-configuration. Consequently, clicking "Logout" in NetBird only clears the local session, leaving the user logged in at the upstream IdP.

  • Observation: Since the discovery JSON cannot always be modified, NetBird lacks the information on where to redirect for a remote logout.
  • Requirement: Add a field to the UI to provide a Custom End-Session-Endpoint URL. If provided, NetBird should prioritize this URL for the logout redirect, even if it's missing from the discovery document.

Summary of requested UI additions for "OIDC Generic":

  1. Username Claim Field: (Already discussed) To choose between name, preferred_username, etc.
  2. Groups Scope Toggle & Claim Field: To force the groups scope and define the claim name.
  3. Manual Logout URL Field: To allow Single Log-Out when the discovery endpoint is incomplete.

These additions would make the "OIDC Generic" provider truly generic and compatible with the most common self-hosted OIDC setups.

<!-- gh-comment-id:3846954526 --> @ecdlguy commented on GitHub (Feb 4, 2026): Following up on my previous comments, I’ve identified two additional critical limitations in the "OIDC Generic" implementation (tested with NetBird v0.64) that prevent a seamless integration with my IdP: **1. Missing Group Scope Request & Custom Claim Mapping** Currently, the "OIDC Generic" provider does not seem to request the groups scope by default. Even if a group claim is configured in the IdP settings, the sync fails because the scope is missing from the initial OIDC request. - Observation: Switching the provider type to Pocket ID solves this, as it explicitly requests the groups scope and correctly extracts the claim. - Requirement: Please add an option to the "OIDC Generic" configuration to explicitly enable/disable the groups scope request and allow mapping it to a custom claim (similar to the requested username/name mapping). **2. Custom End-Session-Endpoint URL (SLO)** Many OIDC providers (like Dex) do not expose an end_session_endpoint in their .well-known/openid-configuration. Consequently, clicking "Logout" in NetBird only clears the local session, leaving the user logged in at the upstream IdP. - Observation: Since the discovery JSON cannot always be modified, NetBird lacks the information on where to redirect for a remote logout. - Requirement: Add a field to the UI to provide a Custom End-Session-Endpoint URL. If provided, NetBird should prioritize this URL for the logout redirect, even if it's missing from the discovery document. **Summary of requested UI additions for "OIDC Generic":** 1. Username Claim Field: (Already discussed) To choose between name, preferred_username, etc. 2. Groups Scope Toggle & Claim Field: To force the groups scope and define the claim name. 3. Manual Logout URL Field: To allow Single Log-Out when the discovery endpoint is incomplete. These additions would make the "OIDC Generic" provider truly generic and compatible with the most common self-hosted OIDC setups.
Author
Owner

@xd003 commented on GitHub (Mar 20, 2026):

Any chance this could be fixed in near future ?

<!-- gh-comment-id:4097665346 --> @xd003 commented on GitHub (Mar 20, 2026): Any chance this could be fixed in near future ?
Author
Owner

@james-d-elliott commented on GitHub (Mar 28, 2026):

This issue is an issue with the compliance of netbird. It's expecting values in the ID Token that must not be expected by default. It either must request them via the claims parameter or must retrieve them from the User Info Endpoint using the Access Token. This is true in all instances of an OpenID Connect 1.0 flow that returns an Access Token, and it is why the Access Token is returned (when a flow does not return an Access Token, the Provider MUST include the claims expected at User Info in the ID Token, this is the only exception to the requirement to use the claims parameter or User Info endpoint).

This is a minimum requirement of the OpenID Connect 1.0 specification (ergo Netbird does not support OIDC), if you would like formal specification references that prove this I can provide them.

Note that the "fix" described in https://github.com/netbirdio/netbird/issues/5143#issuecomment-3829473073 is actually a workaround.

<!-- gh-comment-id:4147197276 --> @james-d-elliott commented on GitHub (Mar 28, 2026): This issue is an issue with the compliance of netbird. It's expecting values in the ID Token that must not be expected by default. It either must request them via the `claims` parameter or must retrieve them from the User Info Endpoint using the Access Token. This is true in all instances of an OpenID Connect 1.0 flow that returns an Access Token, and it is why the Access Token is returned (when a flow does not return an Access Token, the Provider MUST include the claims expected at User Info in the ID Token, this is the only exception to the requirement to use the claims parameter or User Info endpoint). This is a minimum requirement of the OpenID Connect 1.0 specification (ergo Netbird **_does not_** support OIDC), if you would like formal specification references that prove this I can provide them. Note that the "fix" described in https://github.com/netbirdio/netbird/issues/5143#issuecomment-3829473073 is actually a workaround.
Author
Owner

@mandrepont commented on GitHub (Apr 10, 2026):

To add to the OIDC generic configuration options that @ecdlguy mentioned

Groups Scope Toggle & Claim Field: To force the groups scope and define the claim name.

Allow us specify the specific scope and not just the generic groups scope. I use a custom claim and scope that only holds netbird related groups so that jwt sync is not polluted with other groups.

<!-- gh-comment-id:4227315239 --> @mandrepont commented on GitHub (Apr 10, 2026): To add to the OIDC generic configuration options that @ecdlguy mentioned > Groups Scope Toggle & Claim Field: To force the groups scope and define the claim name. Allow us specify the specific scope and not just the generic `groups` scope. I use a custom claim and scope that only holds netbird related groups so that jwt sync is not polluted with other groups.
Author
Owner

@rjcds commented on GitHub (Apr 14, 2026):

I was struggling to add Rauthy as a generic OIDC service; Netbird didn't recognise the additional attribute for 'name' I tried adding into a custom claim

However, after some trial and error, I found that by using the Zitadel option from the UI (but adding all my Rauthy details), it worked out of the box (even with the custom claims removed).

So I don't know what Netbird's Zitadel config is doing differently from the generic OIDC setup, but it correctly reads the 'name' from the profile

Hope that helps others

<!-- gh-comment-id:4243806775 --> @rjcds commented on GitHub (Apr 14, 2026): I was struggling to add Rauthy as a generic OIDC service; Netbird didn't recognise the additional attribute for 'name' I tried adding into a custom claim However, after some trial and error, I found that by using the Zitadel option from the UI (but adding all my Rauthy details), it worked out of the box (even with the custom claims removed). So I don't know what Netbird's Zitadel config is doing differently from the generic OIDC setup, but it correctly reads the 'name' from the profile Hope that helps others
Author
Owner

@kaysond commented on GitHub (May 21, 2026):

This (and the IdP JWT groups lockout issue) make me really hesitant to use netbird... It makes it seem like all the homelab stuff is just lip service.

<!-- gh-comment-id:4514430361 --> @kaysond commented on GitHub (May 21, 2026): This (and the IdP JWT groups lockout issue) make me really hesitant to use netbird... It makes it seem like all the homelab stuff is just lip service.
Author
Owner

@james-d-elliott commented on GitHub (May 21, 2026):

So I don't know what Netbird's Zitadel config is doing differently from the generic OIDC setup, but it correctly reads the 'name' from the profile

@rjcds effectively Zitadel is solving the same issue where both netbird and Rauthy do not actually support OIDC. Their generic implementation seems to be or similar to the "spec" version.

<!-- gh-comment-id:4514667359 --> @james-d-elliott commented on GitHub (May 21, 2026): > So I don't know what Netbird's Zitadel config is doing differently from the generic OIDC setup, but it correctly reads the 'name' from the profile @rjcds effectively Zitadel is solving the same issue where both netbird and Rauthy do not actually support OIDC. Their generic implementation seems to be or similar to the "spec" version.
Author
Owner

@NoArmyKnife commented on GitHub (Jul 31, 2026):

In case people landing here haven't seen this already, I made a somewhat extensive report of me trying to setup SSO on netbird here https://github.com/netbirdio/netbird/discussions/6244.
Hope this helps for people trying to make this work, and hopefully the more upvotes it gets the more the chances are the netbird team addresses this.

<!-- gh-comment-id:5142924843 --> @NoArmyKnife commented on GitHub (Jul 31, 2026): In case people landing here haven't seen this already, I made a somewhat extensive report of me trying to setup SSO on netbird here https://github.com/netbirdio/netbird/discussions/6244. Hope this helps for people trying to make this work, and hopefully the more upvotes it gets the more the chances are the netbird team addresses this.
Sign in to join this conversation.
No Label triage-needed
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: DYNR/netbird#10648