SVI/netbird
1
0
Fork 0
mirror of https://github.com/netbirdio/netbird.git synced 2026-05-11 18:51:53 -04:00
Code Issues 3.0k Packages Projects Releases 10 Wiki Activity

NetBird Issues with Keycloak 26.x (Self-Hosted) #2390

New Issue
Open
opened 2025-11-20 07:09:05 -05:00 by saavagebueno · 2 comments
saavagebueno commented 2025-11-20 07:09:05 -05:00
Owner
Copy Link

Originally created by @jessedye on GitHub (Oct 17, 2025).

Describe the problem

Android app authentication flow shows unexpected consent screen and fails to redirect back to the app after successful authentication with self-hosted Keycloak OIDC. The web dashboard authentication works correctly, but the Android app gets stuck after the browser authentication completes.

To Reproduce

Steps to reproduce the behavior:

  1. Open NetBird Android app
  2. Tap to authenticate/login
  3. App redirects to Chrome browser with Keycloak authentication page
  4. Enter credentials and authenticate successfully
  5. Browser shows consent screen: "Grant Access to NetBird Device/CLI" requesting permissions for:
    • Offline access
    • Email
    • User roles
    • User profile
  6. Click "Yes" to grant access
  7. Browser shows "Successful" message
  8. Browser does NOT redirect back to the NetBird Android app
  9. Manually switching back to NetBird app shows it's still not authenticated/connected

Expected behavior

After successful authentication in the browser:

  1. No consent screen should appear (consent is disabled on the client: consentRequired=false)
  2. Browser should automatically redirect back to the NetBird Android app using the netbird:// deep link
  3. NetBird app should complete authentication and connect to the network

Are you using NetBird Cloud?

No, self-hosting NetBird's control plane with:

  • NetBird Management: v0.59.6
  • NetBird Signal: v0.59.6
  • NetBird Dashboard: v2.12.0
  • Identity Provider: Keycloak (self-hosted)
  • Authentication: OIDC with Keycloak

NetBird version

Management/Signal: 0.59.6
Dashboard: v2.12.0
Android app: (current version from Play Store)

Is any other VPN software installed?

No other VPN software is installed on the Android device.

Debug output

Unable to capture debug output as the Android app never successfully authenticates to generate status or debug bundles.

Screenshots

The authentication flow shows:

  1. Chrome browser with Keycloak login page
  2. Consent screen showing "Grant Access to NetBird Device/CLI"
Image
  1. "Successful" message after granting consent
  2. Browser remains on success page instead of redirecting to app
Image

Additional context

Keycloak Client Configuration:

The netbird-client (Device/CLI) OIDC client in Keycloak is configured as follows:

  • Client ID: netbird-client
  • Access Type: PUBLIC
  • Consent Required: false (explicitly disabled)
  • Full Scope Allowed: true
  • Standard Flow: Enabled
  • Direct Access Grants: Enabled
  • OAuth 2.0 Device Authorization Grant: Enabled

Redirect URIs configured:

netbird://oauth
netbird://callback
netbird://*
http://localhost:*
http://localhost:53000

Web Origins:

+

Default Client Scopes:

web-origins, acr, offline_access, roles, profile, api, basic, email

Optional Client Scopes:

address, phone, microprofile-jwt

Issues Observed:

  1. Consent Screen Appears Despite Being Disabled: Even though consentRequired=false is set on the Keycloak client, the consent screen still appears asking for permissions. We've verified the setting is correctly applied in Keycloak.

  2. Deep Link Redirect Fails: After clicking "Yes" on the consent screen, the browser shows "Successful" but does not redirect back to the NetBird Android app using the netbird:// deep link scheme.

  3. Web Dashboard Works Correctly: The NetBird web dashboard at https://vpn.REDACTED.com authenticates successfully with the same Keycloak setup using a different client (netbird-dashboard), so the Keycloak configuration appears correct for web flows.

REDACTED

NetBird Configuration (Helm values):

auth:
  audience: "netbird"
  authority: "https://keycloak.REDACTED.com/realms/master"
  device:
    provider: "hosted"
    authority: "https://keycloak.REDACTED.com/realms/master"
    clientID: "netbird-client"
    audience: "netbird"
    scope: "openid profile email offline_access api"
    useIDToken: false

idp:
  managerType: "keycloak"
  clientID: "netbird"
  adminEndpoint: "https://keycloak.REDACTED.com/admin/realms/master"
  tokenEndpoint: "https://keycloak.REDACTED.com/realms/master/protocol/openid-connect/token"
  grantType: "client_credentials"

Questions:

  1. Is there a known issue with the Android app's deep link handler for netbird:// URLs?
  2. Should the Android app be using Device Authorization Grant flow instead of the standard authorization code flow to avoid browser redirects?
  3. Is there additional configuration needed in the Keycloak OIDC client to prevent the consent screen for PUBLIC clients?
  4. Are there any Android app logs or debugging methods to see what's happening when it attempts to receive the redirect?

Related Issues:

This appears similar to #2972 but occurs with self-hosted Keycloak OIDC provider.

Have you tried these troubleshooting steps?

  • Reviewed client troubleshooting (if applicable)
  • Checked for newer NetBird versions (using latest 0.59.6)
  • Searched for similar issues on GitHub (including closed ones)
  • Restarted the NetBird client
  • Disabled other VPN software (none installed)
  • Checked firewall settings
  • Verified Keycloak client configuration (consent disabled, correct redirect URIs, proper scopes)
  • Tested web dashboard authentication (works correctly)
  • Cleared NetBird app data and reinstalled
  • Tested with different Keycloak scope configurations
Originally created by @jessedye on GitHub (Oct 17, 2025). **Describe the problem** Android app authentication flow shows unexpected consent screen and fails to redirect back to the app after successful authentication with self-hosted Keycloak OIDC. The web dashboard authentication works correctly, but the Android app gets stuck after the browser authentication completes. **To Reproduce** Steps to reproduce the behavior: 1. Open NetBird Android app 2. Tap to authenticate/login 3. App redirects to Chrome browser with Keycloak authentication page 4. Enter credentials and authenticate successfully 5. Browser shows consent screen: "Grant Access to NetBird Device/CLI" requesting permissions for: - Offline access - Email - User roles - User profile 6. Click "Yes" to grant access 7. Browser shows "Successful" message 8. Browser does NOT redirect back to the NetBird Android app 9. Manually switching back to NetBird app shows it's still not authenticated/connected **Expected behavior** After successful authentication in the browser: 1. No consent screen should appear (consent is disabled on the client: `consentRequired=false`) 2. Browser should automatically redirect back to the NetBird Android app using the `netbird://` deep link 3. NetBird app should complete authentication and connect to the network **Are you using NetBird Cloud?** No, self-hosting NetBird's control plane with: - NetBird Management: v0.59.6 - NetBird Signal: v0.59.6 - NetBird Dashboard: v2.12.0 - Identity Provider: Keycloak (self-hosted) - Authentication: OIDC with Keycloak **NetBird version** Management/Signal: `0.59.6` Dashboard: `v2.12.0` Android app: (current version from Play Store) **Is any other VPN software installed?** No other VPN software is installed on the Android device. **Debug output** Unable to capture debug output as the Android app never successfully authenticates to generate status or debug bundles. **Screenshots** The authentication flow shows: 1. Chrome browser with Keycloak login page 2. Consent screen showing "Grant Access to NetBird Device/CLI" <img width="952" height="1799" alt="Image" src="https://github.com/user-attachments/assets/c3740b8b-ca32-44da-86ff-45ebd6f21dff" /> 3. "Successful" message after granting consent 4. Browser remains on success page instead of redirecting to app <img width="952" height="1799" alt="Image" src="https://github.com/user-attachments/assets/0ee61db7-2a2c-4753-bc8b-5ceac4044eea" /> **Additional context** **Keycloak Client Configuration:** The `netbird-client` (Device/CLI) OIDC client in Keycloak is configured as follows: - Client ID: `netbird-client` - Access Type: `PUBLIC` - Consent Required: `false` (explicitly disabled) - Full Scope Allowed: `true` - Standard Flow: Enabled - Direct Access Grants: Enabled - OAuth 2.0 Device Authorization Grant: Enabled **Redirect URIs configured:** ``` netbird://oauth netbird://callback netbird://* http://localhost:* http://localhost:53000 ``` **Web Origins:** ``` + ``` **Default Client Scopes:** ``` web-origins, acr, offline_access, roles, profile, api, basic, email ``` **Optional Client Scopes:** ``` address, phone, microprofile-jwt ``` **Issues Observed:** 1. **Consent Screen Appears Despite Being Disabled**: Even though `consentRequired=false` is set on the Keycloak client, the consent screen still appears asking for permissions. We've verified the setting is correctly applied in Keycloak. 2. **Deep Link Redirect Fails**: After clicking "Yes" on the consent screen, the browser shows "Successful" but does not redirect back to the NetBird Android app using the `netbird://` deep link scheme. 3. **Web Dashboard Works Correctly**: The NetBird web dashboard at `https://vpn.REDACTED.com` authenticates successfully with the same Keycloak setup using a different client (`netbird-dashboard`), so the Keycloak configuration appears correct for web flows. REDACTED **NetBird Configuration (Helm values):** ```yaml auth: audience: "netbird" authority: "https://keycloak.REDACTED.com/realms/master" device: provider: "hosted" authority: "https://keycloak.REDACTED.com/realms/master" clientID: "netbird-client" audience: "netbird" scope: "openid profile email offline_access api" useIDToken: false idp: managerType: "keycloak" clientID: "netbird" adminEndpoint: "https://keycloak.REDACTED.com/admin/realms/master" tokenEndpoint: "https://keycloak.REDACTED.com/realms/master/protocol/openid-connect/token" grantType: "client_credentials" ``` **Questions:** 1. Is there a known issue with the Android app's deep link handler for `netbird://` URLs? 2. Should the Android app be using Device Authorization Grant flow instead of the standard authorization code flow to avoid browser redirects? 3. Is there additional configuration needed in the Keycloak OIDC client to prevent the consent screen for PUBLIC clients? 4. Are there any Android app logs or debugging methods to see what's happening when it attempts to receive the redirect? **Related Issues:** This appears similar to #2972 but occurs with self-hosted Keycloak OIDC provider. **Have you tried these troubleshooting steps?** - [x] Reviewed [client troubleshooting](https://docs.netbird.io/how-to/troubleshooting-client) (if applicable) - [x] Checked for newer NetBird versions (using latest 0.59.6) - [x] Searched for similar issues on GitHub (including closed ones) - [x] Restarted the NetBird client - [x] Disabled other VPN software (none installed) - [x] Checked firewall settings - [x] Verified Keycloak client configuration (consent disabled, correct redirect URIs, proper scopes) - [x] Tested web dashboard authentication (works correctly) - [x] Cleared NetBird app data and reinstalled - [x] Tested with different Keycloak scope configurations
saavagebueno added the triage-needed label 2025-11-20 07:09:05 -05:00
saavagebueno commented 2025-11-20 07:09:06 -05:00
Author
Owner
Copy Link

@jessedye commented on GitHub (Oct 17, 2025):

The issue seems to be related to the offline token capability for KeyCloak.

✗ netbird up --management-url https://api.vpn.REDACTED.com --admin-url https://vpn.REDACTED.com
Please do the SSO login in your browser.
If your browser didn't open automatically, use this URL to log in:

https://keycloak.REDACTED.com/realms/master/device?user_code=READACTED

Error: daemon up failed: sso login failed: waiting sso login failed with: rpc error: code = Unknown desc = Offline tokens not allowed for the user or client

After some digging it looks like this may be a regression in keycloak 26.x downgrading to 25.x to test further.

@jessedye commented on GitHub (Oct 17, 2025): The issue seems to be related to the offline token capability for KeyCloak. ✗ netbird up --management-url https://api.vpn.REDACTED.com --admin-url https://vpn.REDACTED.com Please do the SSO login in your browser. If your browser didn't open automatically, use this URL to log in: https://keycloak.REDACTED.com/realms/master/device?user_code=READACTED Error: daemon up failed: sso login failed: waiting sso login failed with: rpc error: code = Unknown desc = Offline tokens not allowed for the user or client After some digging it looks like this may be a regression in keycloak 26.x downgrading to 25.x to test further.
saavagebueno commented 2025-11-20 07:09:06 -05:00
Author
Owner
Copy Link

@ghazyami commented on GitHub (Oct 18, 2025):

I am working on deploying netbird at the moment with keycloak 26.

I encountered something might be the case issue for you as well.

Keycloak 26 enabled light weight tokens by default for clients, this causes generated access token to not include some claims like sub which from where netbird gets the username, luckily there is a config in netbird to specify which claim to use NETBIRD_AUTH_USER_ID_CLAIM in setup.env and AuthUserIDClaim in management.json.
I updated this to preferred_username which works. Other solution would be to add mapper for needed claims.

@ghazyami commented on GitHub (Oct 18, 2025): I am working on deploying netbird at the moment with keycloak 26. I encountered something might be the case issue for you as well. Keycloak 26 enabled light weight tokens by default for clients, this causes generated access token to not include some claims like `sub` which from where netbird gets the username, luckily there is a config in netbird to specify which claim to use `NETBIRD_AUTH_USER_ID_CLAIM` in setup.env and `AuthUserIDClaim` in management.json. I updated this to `preferred_username` which works. Other solution would be to add mapper for needed claims.
Sign in to join this conversation.
No Branch/Tag Specified
Branches Tags
Labels
Clear labels
2021 Q4
2022 Q1
2022 Q1
accessibility
acl
agent
agent
Android
Android
api
authentik
automation
azure
battery-usage
bug
cache
client
client-ui
cloud
cloud-only
cloudflare
community
compatibility
config-idp
config-issue
connection
contribution
coturn
cross-vpn
dashboard
data-usage
distribution
dns
docker
documentation
duplicate
enhancement
enhancement
event-stream
feature-request
freebsd
getting-started
go
good first issue
gui
help wanted
home-assistant
idp
inconsistency
integration
integrations
ios
ipv6
jwt
k8s
keycloak
linux
login
macos
management-service
missing-docs
mobile
moved-internal
needs-review
netbird-ui
networking
new-platform
nginx
notification
okta
openwrt
packaging
peer-management
peer-management
peer-management
performance
postgres
posture-checks
psk
pull-request
Mirrored from GitHub Pull Request
 question
refactor
relay
release
rfc
routes
security
security-related
self-hosting
server
signal
sleep-issue
ssh
ssl
status
store
synology
system-compatibility-issue
test-suite
third-party-integration
triage
triage-needed
troubleshooting
UX
waiting-feedback
windows
wontfix
zitadel
No Label triage-needed
Milestone
No items
No Milestone
Projects
Clear projects
No project
Assignees
Clear assignees
saavagebueno
No Assignees
1 Participants
Notifications
Due Date
No due date set.
Dependencies

No dependencies set.

Reference: SVI/netbird#2390
Delete Branch "%!s()"

Deleting a branch is permanent. Although the deleted branch may continue to exist for a short time before it actually gets removed, it CANNOT be undone in most cases. Continue?