OIDC Authentication

Nebula Commander can use OpenID Connect (OIDC) for login. Keycloak is supported with a pre-configured setup; other OIDC providers (Authentik, Auth0, etc.) work with the same environment variables.

Required variables

Set these in env.d/backend (Docker) or in the backend environment:

  • NEBULA_COMMANDER_PUBLIC_URL – URL where users reach the app (FQDN or host:port). The redirect URI is derived as PUBLIC_URL + /api/auth/callback if you do not set OIDC_REDIRECT_URI.
  • NEBULA_COMMANDER_OIDC_ISSUER_URL – Issuer URL used by the backend to talk to the provider. Inside Docker use the container name and container port (e.g. http://keycloak:8080/realms/nebula-commander). Do not use the host-mapped port here.
  • NEBULA_COMMANDER_OIDC_PUBLIC_ISSUER_URL – Issuer URL as seen by the browser (FQDN or host:port). Use the same URL users would use to open the provider’s login page.
  • NEBULA_COMMANDER_OIDC_CLIENT_ID – OIDC client ID (e.g. nebula-commander).
  • NEBULA_COMMANDER_OIDC_CLIENT_SECRET – Client secret from the provider. Prefer NEBULA_COMMANDER_OIDC_CLIENT_SECRET_FILE in production.

Optional: NEBULA_COMMANDER_OIDC_REDIRECT_URI – Override only if you need a callback URL different from PUBLIC_URL + /api/auth/callback.

Keycloak with Docker

  1. Copy example env files and edit env.d/backend (set PUBLIC_URL, OIDC issuer URLs, client id/secret).
  2. Start with Keycloak:
    docker compose -f docker-compose.yml -f docker-compose-keycloak.yml up -d
  3. Create a user in Keycloak Admin and assign client roles under the nebula-commander client: system-admin, network-owner, or user.

Zero-touch Keycloak

The project provides a custom Keycloak image that imports the realm and theme at startup. Build the image (see Installation: Docker and docker/keycloak), set the same OIDC variables in env.d/backend, and start the stack. No manual realm creation is required; create users and assign roles in the Admin console.

Manual Keycloak setup

If you do not use the zero-touch image, create the realm and client in Keycloak:

  • Client type: OpenID Connect, confidential, standard flow.
  • Valid redirect URI: your PUBLIC_URL + /api/auth/callback.
  • Valid post-logout redirect URIs: PUBLIC_URL + /*.
  • Web origins: your PUBLIC_URL.
  • Create client roles: system-admin, network-owner, user. Assign them to users via Role mapping.

Then set the client secret in env.d/backend.

Backend cannot reach Keycloak

The backend talks to Keycloak on the Docker network. Use the container port in NEBULA_COMMANDER_OIDC_ISSUER_URL (e.g. http://keycloak:8080/realms/nebula-commander), not the host-mapped port. Use the host port or FQDN only in NEBULA_COMMANDER_OIDC_PUBLIC_ISSUER_URL and in NEBULA_COMMANDER_PUBLIC_URL.

External OIDC provider

Keycloak is the default, but Nebula Commander’s OIDC integration is fully provider-agnostic: login, logout, and step-up reauth all use standard OIDC discovery (.well-known/openid-configuration) to find the provider’s actual endpoints, rather than assuming Keycloak’s URL conventions. Any standards-compliant provider — Authentik, Auth0, Okta, and others — works with the same environment variables.

Use the same variables as above. In the provider, set redirect URI to PUBLIC_URL + /api/auth/callback, client type Confidential, grant type Authorization Code. Set OIDC_ISSUER_URL and OIDC_PUBLIC_ISSUER_URL to the provider’s issuer URL (often the same).

docker-compose.yml includes the Keycloak stack by default. To use an external provider instead, comment out (or delete) the include: block at the top of docker-compose.yml:

# include:
#   - path: ./docker-compose-keycloak.yml

then docker compose up -d starts only the backend and frontend.

Admin role mapping

Keycloak assigns roles via a client-roles claim shaped like resource_access.<client_id>.roles, which most other providers don’t emit by default. If you’re not using Keycloak, set:

  • NEBULA_COMMANDER_OIDC_ADMIN_ROLE_CLAIM – the top-level claim your provider emits (e.g. roles, groups, or an Auth0-style namespaced claim like https://nebula.example.com/roles).
  • NEBULA_COMMANDER_OIDC_ADMIN_ROLE_VALUE – the value within that claim that grants system-admin (default system-admin).

Leave OIDC_ADMIN_ROLE_CLAIM unset to keep using Keycloak’s default shape — this is the default, so existing Keycloak deployments need no changes.

Roles and permissions

  • system-admin – Manage users; view all networks/nodes with limited data; delete networks/nodes (with reauth); request access grants from owners.
  • network-owner – Create and manage networks, nodes, invitations, node requests, and access; set default node parameters and auto-approval.
  • user – Access only what network owners grant; request nodes and higher access.

See the repository docker/README for detailed RBAC and permission features.

Last modified September 16, 2026: Document generic-OIDC support and admin role mapping (2c7d7cd)