Skip to content

Authentication

Authentication for production

Authorization Code flow with PKCE (RFC 7636): 

[QGIS Plugin]  ──OIDC auth──▶  [Keycloak]
     │                              │
     │  JWT (Bearer token)          │ (validates)
     ▼                              ▼
[FastAPI/NiceGUI backend]  ◀── JWT validation
     │
     ▼
[NiceGUI frontend, embedded in QGIS WebEngine]

Important detail: the QGIS plugin is the public client in this setup and shouldn't know of the client_secret. The plugin runs on user-controlled machines; any embedded secret can be extracted. PKCE replaces the client secret as proof of possession.

QGIS plugin configuration

  1. Open QGIS authentication settings.
  2. Create a new authentication configuration.
  3. Select OAuth2.
  4. Select PKCE under Permission Flow.
  5. Set Auth-URL to http://localhost:8080/realms/xmas/protocol/openid-connect/auth. # For local use, set real value provided by app provider.
  6. Set Token-URL to http://localhost:8080/realms/xmas/protocol/openid-connect/token. # For local use, set real value provided by app provider.
  7. Set Client-ID to xmas-plugin.
  8. Set Redirect-URI to 127.0.0.1:17070.
  9. Select this authentication configuration in the XMAS plugin settings.

Dev credentials are username xmas-test-user with password test.

XMAS-App configuration

The XMAS-App must be configured to work with Keycloak authentication:

AUTH_MODE=keycloak

Authentication setup for local development

Local development uses a static Bearer token.

QGIS plugin configuration

  1. Open QGIS authentication settings.
  2. Create a new authentication configuration.
  3. Select API Header.
  4. Set the header name to Authorization.
  5. Set the header value to Bearer <local-dev-token>.
  6. Select this authentication configuration in the XMAS plugin settings.

XMAS-App configuration

The XMAS-App must be configured to accept the same token, for example:

AUTH_TOKENS={"local-dev-token": "<user-name>", ...}
AUTH_MODE=static

Requests must include: Authorization: Bearer local-dev-token

The token is mapped to a user ID internally and used as the authenticated user.

This setup is only meant for local development and testing. In production, the static token must be replaced by an active Bearer access token issued through Keycloak.

Rasterdaten (plan documents)

Plan document rasters are opened as QgsRasterLayer over GDAL's /vsicurl/ driver. GDAL fetches these with its own libcurl, so they bypass QgsNetworkAccessManager and with it the Requester, the broker handshake and the WebEngine request interceptor — none of which GDAL ever sees.

The plugin therefore hands GDAL the same Authorization: Bearer <token> header out of band, as a path-specific GDAL_HTTP_HEADERS option scoped to the configured webapp URL (xmas_plugin/core/network/gdal_auth.py). Because the header is not part of the layer URI, the token is never written into a saved .qgs project, and the path scoping prevents it from being sent to any other host.

The header is bound when GDAL opens the dataset. If an access token expires while a raster layer is open, reload the plan to pick up the refreshed token.