From 3a2cd8cf358c25d23b40578eac23e0f8c1307873 Mon Sep 17 00:00:00 2001 From: gabriel-farache Date: Mon, 21 Sep 2026 09:40:05 +0200 Subject: [PATCH 1/3] docs: document environment agent authentication (inbound + outbound) Adds a dedicated Environment Agent Authentication guide covering the two independent auth surfaces introduced by environment-agent#35 and environment-agent#38: - Inbound: AGENT_AUTH_DISABLED / AGENT_AUTH_ISSUER_URL / AGENT_AUTH_JWT_AUDIENCE protecting the agent's own REST API (external SP registration, provider listing), health-path bypass, RFC 7807 error format, and the intentional audience fail-open behavior. - Outbound: DCM_AUTH_TOKEN / DCM_AUTH_TOKEN_ENDPOINT / DCM_AUTH_CLIENT_ID / DCM_AUTH_CLIENT_SECRET for the agent's own registration/heartbeat calls to the control plane, mode precedence, token refresh and failure behavior, Keycloak service-account setup, and the known reference-realm audience-mapper gap. Addresses the open documentation request from environment-agent#35 (review thread on internal/config/config.go, https://github.com/dcm-project/environment-agent/pull/35#discussion_r4042755293): 'put agent auth enablement on the website... same idea as the CP guide.' Content validated against the latest reviewed commits on both PR branches (config.go, jwt.go, middleware.go, token.go, client.go, main.go, openapi.yaml, README.md, decisions.md) rather than assumed from the PR descriptions alone. Updates the control-plane Authentication guide's Service-providers callout and troubleshooting row to link to the new page instead of a vague 'still landing' note, and cross-links from Local Setup and the Getting Started index. Signed-off-by: Gabriel Farache Co-authored-by: Cursor Signed-off-by: gabriel-farache --- content/docs/getting-started/_index.md | 2 + .../docs/getting-started/authentication.md | 32 +-- .../environment-agent-authentication.md | 219 ++++++++++++++++++ content/docs/getting-started/local-setup.md | 5 + 4 files changed, 245 insertions(+), 13 deletions(-) create mode 100644 content/docs/getting-started/environment-agent-authentication.md diff --git a/content/docs/getting-started/_index.md b/content/docs/getting-started/_index.md index 07c0edf..b5c430e 100644 --- a/content/docs/getting-started/_index.md +++ b/content/docs/getting-started/_index.md @@ -22,5 +22,7 @@ Get up and running with DCM. second service provider and create a random selection policy. - **[Authentication](authentication/)** — Enable auth, log in with the CLI or UI, and call the API with bearer tokens. +- **[Environment Agent Authentication](environment-agent-authentication/)** — + Protect the agent's API and authenticate its requests to the control plane. - **[Troubleshooting](troubleshooting/)** — Diagnose issues using container logs and status checks. diff --git a/content/docs/getting-started/authentication.md b/content/docs/getting-started/authentication.md index 7d814a1..c0101d0 100644 --- a/content/docs/getting-started/authentication.md +++ b/content/docs/getting-started/authentication.md @@ -26,10 +26,16 @@ The `/api/v1alpha1/health` endpoint stays **unauthenticated** whether or not auth is enabled. > **Service providers:** Service providers reach the control plane through the -> environment agent, not direct HTTP calls. Authentication for service-provider -> workflows depends on the deployed environment-agent version and its -> authentication configuration. Verify that the deployed agent supports -> control-plane authentication before enabling auth for full SP workflows. +> environment agent, not direct HTTP calls. The agent has its own inbound +> (protecting its API) and outbound (registering with the control plane) +> authentication, documented separately in +> [Environment Agent Authentication](../environment-agent-authentication/). +> Support depends on the deployed environment-agent version, so verify that the +> agent actually supports control-plane authentication before enabling auth for +> full SP workflows. Enabling auth on the control plane can still affect SP +> registration and instance workflows if the agent's outbound authentication is +> not configured to match. Use auth for CLI, UI, and direct API access first, or +> keep auth disabled while exercising full SP flows locally. ## How authentication works @@ -220,15 +226,15 @@ returns `403 Forbidden`. ## Troubleshooting -| Symptom | Things to check | -| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | -| `401 Unauthorized` on API or CLI | Auth enabled; token present and not expired; issuer matches `AUTH_ISSUER_URL`; if `AUTH_JWT_AUDIENCE` is set, token `aud` must match. | -| `dcm login` cannot reach issuer | Host maps `keycloak` (see [host access](#local-compose-host-access-to-keycloak)); issuer matches discovery; TLS if using HTTPS. | -| Issuer / JWKS errors in control-plane logs | `AUTH_ISSUER_URL` reachable from the control-plane container; Keycloak healthy (`auth` profile running). | -| CLI works but UI fails (or reverse) | Backstage SSO and control plane must trust the same IdP and audience; plugin backend URL points at the control plane. | -| `403 Forbidden` with valid token | Actor suspended or deactivated; wait up to `AUTH_CACHE_TTL` after status changes. | -| Service provider errors after enabling auth | SP traffic uses the environment agent; auth for agent and SP paths is still landing. See SP callout in [Overview](#overview). | -| Device flow times out | Complete browser approval within the time shown; retry `dcm login`. | +| Symptom | Things to check | +| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `401 Unauthorized` on API or CLI | Auth enabled; token present and not expired; issuer matches `AUTH_ISSUER_URL`; if `AUTH_JWT_AUDIENCE` is set, token `aud` must match. | +| `dcm login` cannot reach issuer | Host maps `keycloak` (see [host access](#local-compose-host-access-to-keycloak)); issuer matches discovery; TLS if using HTTPS. | +| Issuer / JWKS errors in control-plane logs | `AUTH_ISSUER_URL` reachable from the control-plane container; Keycloak healthy (`auth` profile running). | +| CLI works but UI fails (or reverse) | Backstage SSO and control plane must trust the same IdP and audience; plugin backend URL points at the control plane. | +| `403 Forbidden` with valid token | Actor suspended or deactivated; wait up to `AUTH_CACHE_TTL` after status changes. | +| Service provider workflow returns an auth error | Identify which request failed: SP-to-agent provider API calls use inbound `AGENT_AUTH_*` settings and the SP's token; agent registration and heartbeat calls use outbound `DCM_AUTH_*` settings and the control plane's `AUTH_*` settings. See [Environment Agent Authentication](../environment-agent-authentication/). | +| Device flow times out | Complete browser approval within the time shown; retry `dcm login`. | Verify Keycloak readiness when using compose: diff --git a/content/docs/getting-started/environment-agent-authentication.md b/content/docs/getting-started/environment-agent-authentication.md new file mode 100644 index 0000000..847664b --- /dev/null +++ b/content/docs/getting-started/environment-agent-authentication.md @@ -0,0 +1,219 @@ +--- +title: Environment Agent Authentication +type: docs +weight: 8 +--- + +The [environment agent](https://github.com/dcm-project/environment-agent) runs +in a target environment and acts as the intermediary between the DCM control +plane and the Service Providers (SPs) deployed there. It has **two independent** +authentication surfaces, separate from the control-plane authentication covered +in [Authentication](../authentication/): + +1. **Inbound** — protecting the agent's own REST API (external SP registration, + provider listing) from unauthenticated callers. +2. **Outbound** — authenticating the agent's own requests to the control plane + (agent registration and heartbeat) when the control plane has authentication + enabled. + +Both use the same mechanism as the control plane: OIDC-issued JWT bearer tokens, +validated with [Keycloak](https://www.keycloak.org/) in the reference stack. You +can enable either one independently of the other. + +```mermaid +graph LR + SP["External Service Provider"] -->|"Bearer JWT (inbound)"| Agent["Environment Agent"] + Agent -->|"Bearer JWT (outbound)"| CP["Control Plane"] +``` + +## Inbound: protecting the agent's API + +The agent's REST API — external SP registration (`POST /api/v1alpha1/providers`) +and provider listing (`GET /api/v1alpha1/providers`, +`GET /api/v1alpha1/providers/{provider_id}`) — can require a valid JWT bearer +token on every request. This closes the gap called out in the +[environment agent enhancement](https://github.com/dcm-project/enhancements/blob/main/enhancements/environment-agent/environment-agent.md#authentication-and-authorization-for-sp-registration-consolidation): +external SP registration was previously unauthenticated, with network isolation +as the only interim mitigation. + +`GET /api/v1alpha1/health` is the only endpoint that stays public — the bypass +checks both the method and the path, so `GET /health` is unauthenticated but any +other method at that path still requires a token. + +### How it works + +1. At startup, the agent discovers OIDC metadata from the issuer. When it + validates a token, it fetches signing keys from the issuer's JWKS endpoint as + needed and caches them. +2. On each protected request, the agent extracts the + `Authorization: Bearer ` header (case-insensitive scheme) and + validates signature, expiry, issuer, and — if configured — audience. +3. On success, the token's `sub` and `preferred_username` claims are attached to + the request's audit log line. There is no actor store or suspension concept + on the agent side (unlike the control plane): a valid token is sufficient to + call the API. +4. On failure, the agent returns `401 Unauthorized` as an RFC 7807 problem + response with a `WWW-Authenticate: Bearer` header. The response body never + contains the underlying validator error (for example "token expired" or + "signature invalid") — only a fixed `invalid Bearer token` detail. The + specific reason is logged server-side only. + +### Configuration + +| Variable | Purpose | +| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENT_AUTH_DISABLED` | When `true` (the default), auth middleware is bypassed. The agent still logs a startup `WARN` ("authentication is disabled") so the insecure default is visible in logs. | +| `AGENT_AUTH_ISSUER_URL` | OIDC issuer URL for JWT validation (for example `http://keycloak:8080/realms/dcm`). Required when `AGENT_AUTH_DISABLED=false`; startup fails otherwise. | +| `AGENT_AUTH_JWT_AUDIENCE` | Expected `aud` claim. Empty (the default) **disables audience validation** — any token from the issuer is accepted regardless of `aud`. The agent logs a startup `WARN` if an issuer is set but the audience is empty. | + +This mirrors the control plane's `AUTH_DISABLED` / `AUTH_ISSUER_URL` / +`AUTH_JWT_AUDIENCE` variables (see +[Control-plane configuration](../authentication/#control-plane-configuration)), +but with an `AGENT_` prefix and its own env vars — the two services are +configured independently, even when pointed at the same Keycloak realm. + +> **Audience is intentionally permissive by default.** Reference Keycloak +> clients for service accounts (used by SPs registering with the agent) don't +> ship with an audience mapper out of the box. Rather than reject every token +> from an unmapped client, the agent skips the audience check when +> `AGENT_AUTH_JWT_AUDIENCE` is empty, and only enforces `aud` matching when you +> explicitly set it. Set it once your SP clients have a matching audience +> mapper. + +### Calling the agent API with a bearer token + +Set `SP_TOKEN` to an access token issued by the same issuer configured in +`AGENT_AUTH_ISSUER_URL`, using the flow provisioned for the calling SP. For +background on obtaining issuer-issued tokens, see +[Obtaining and using tokens](../authentication/#obtaining-and-using-tokens). If +`AGENT_AUTH_JWT_AUDIENCE` is set, the token's `aud` claim must include that +value; configure the issuer or caller client to add the matching audience. + +```bash +curl -s \ + -H "Authorization: Bearer ${SP_TOKEN}" \ + -H "Content-Type: application/json" \ + -d '{"name":"db-provider","endpoint":"https://sp.example.com:8080","service_type":"database","schema_version":"v1alpha1"}' \ + http://localhost:8081/api/v1alpha1/providers +``` + +Without a valid token (auth enabled), this returns `401 Unauthorized`: + +```json +{ + "type": "UNAUTHORIZED", + "title": "Unauthorized", + "status": 401, + "detail": "invalid Bearer token", + "instance": "/api/v1alpha1/providers" +} +``` + +`GET /api/v1alpha1/health` always succeeds without a token: + +```bash +curl -s http://localhost:8081/api/v1alpha1/health +``` + +## Outbound: agent-to-control-plane authentication + +When the control plane has authentication enabled (see +[Authentication](../authentication/)), the agent's own registration +(`POST /api/v1alpha1/agents`) and heartbeat +(`PUT /api/v1alpha1/agents/{agent_id}/heartbeat`) calls must carry a valid +bearer token too. Three modes are supported, resolved at startup: + +1. **OAuth2 client credentials** (recommended for production) — the agent + fetches short-lived JWTs from an OIDC token endpoint and refreshes them + automatically before they expire. +2. **Static token** (dev / simple deployments) — a single pre-obtained JWT is + sent as-is on every request, with no refresh. +3. **No auth** (default, backward-compatible) — neither is configured, so no + `Authorization` header is sent. This is required for the unauthenticated + local-setup flow described in + [Local Setup](../local-setup/#verifying-the-deployment). + +If more than one mode is configured, **client credentials takes precedence over +the static token**. + +### Configuration + +| Variable | Mode | Purpose | +| ------------------------- | ------------------ | -------------------------------------------------------------------------------------------------- | +| `DCM_AUTH_TOKEN_ENDPOINT` | Client credentials | OIDC token endpoint (for example `http://keycloak:8080/realms/dcm/protocol/openid-connect/token`). | +| `DCM_AUTH_CLIENT_ID` | Client credentials | OAuth2 client ID for the agent's service account. | +| `DCM_AUTH_CLIENT_SECRET` | Client credentials | OAuth2 client secret. | +| `DCM_AUTH_TOKEN` | Static token | A pre-obtained JWT sent unchanged on every request. | + +All three client-credentials variables must be set together — a partial +configuration (for example an endpoint without a client ID) is a **startup-fatal +error** that names the missing variables. `DCM_AUTH_TOKEN_ENDPOINT` must also be +an absolute, host-qualified `http(s)://` URL. + +> **Caution:** `http://` token endpoints send the client secret unencrypted on +> every token request. The agent logs a startup warning in this case; prefer +> `https://` outside local development. The agent also refuses to follow any +> redirect returned by the token endpoint, so the secret is never resent to a +> different origin. + +### Token handling + +- Client-credentials tokens are cached in memory and refreshed proactively — 10 + seconds before the `expires_in` deadline from the token response, not + reactively on a `401`. +- A token fetch failure does **not** crash the agent. Registration and + re-registration retry transient failures with exponential backoff + (`DCM_REGISTRATION_INITIAL_BACKOFF` / + `DCM_REGISTRATION_MAX_BACKOFF`). A failed heartbeat is logged and retried on + the next heartbeat tick, controlled by `AGENT_HEARTBEAT_INTERVAL` (30 seconds + by default); heartbeat failures do not use the registration backoff. +- **Static tokens do not refresh.** Once the token expires, the control plane + returns `401`, which the agent treats as non-retryable — registration halts + until the agent is restarted with a fresh token. Use static tokens only where + the token's lifetime safely exceeds the agent's expected uptime. + +### Keycloak setup + +The reference Keycloak realm already includes the confidential `dcm-proxy` +client, with service accounts enabled and a `dcm-api` audience mapper. For this +setup, use the token endpoint and `dcm-proxy` credentials shown in the +[control-plane `.env.example`](https://github.com/dcm-project/control-plane/blob/main/deploy/.env.example): +set `DCM_AUTH_CLIENT_ID=dcm-proxy` and set `DCM_AUTH_CLIENT_SECRET` to the same +secret configured for `AUTH_PROXY_SECRET`. + +You can use a separate client if your deployment needs one. Enable **Client +authentication** and **Service accounts roles**, then set the three +`DCM_AUTH_*` variables to that client's token endpoint and credentials. The +control plane currently requires an authenticated actor context for agent +registration; the registration endpoint does not check for a particular +Keycloak role. + +> **Audience mapper for custom clients:** If the control plane enforces +> `AUTH_JWT_AUDIENCE=dcm-api`, a new client must include `dcm-api` in its token's +> `aud` claim. Add an audience mapper to that client. The reference `dcm-proxy` +> client already has this mapper, so it does not need additional configuration. + +### Kubernetes secrets + +Store the client secret in a Kubernetes `Secret` and inject it with `envFrom` +rather than embedding it in a pod spec or `ConfigMap`: + +```yaml +envFrom: + - secretRef: + name: environment-agent-auth +``` + +## Troubleshooting + +| Symptom | Things to check | +| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| SP registration returns `401` from the agent | Auth enabled on the agent (`AGENT_AUTH_DISABLED=false`); the SP's token is valid and not expired; issuer matches `AGENT_AUTH_ISSUER_URL`; if `AGENT_AUTH_JWT_AUDIENCE` is set, the token's `aud` must match. | +| Agent registration/heartbeat to the control plane returns `401` | Check the `DCM_AUTH_*` client credentials and token endpoint, then verify that the token issuer and (when enabled) audience match the control plane's `AUTH_*` settings. Add a `dcm-api` mapper for a custom client if required; the reference `dcm-proxy` client already has one. | +| Agent fails to start with `AGENT_AUTH_ISSUER_URL: required...` | `AGENT_AUTH_DISABLED=false` but no issuer was set — set `AGENT_AUTH_ISSUER_URL` or leave auth disabled. | +| Agent fails to start with a "partial client-credentials auth config" error | Only some of `DCM_AUTH_TOKEN_ENDPOINT` / `DCM_AUTH_CLIENT_ID` / `DCM_AUTH_CLIENT_SECRET` are set — set all three or none. | +| Registration halts permanently after working for a while | Static `DCM_AUTH_TOKEN` expired (no refresh) — switch to client credentials, or restart the agent with a fresh token. | +| `AGENT_AUTH_JWT_AUDIENCE` startup warning | Expected when an issuer is set without an audience — informational unless you intended to enforce `aud`. | + +For control-plane-side issuer, JWKS, and Keycloak troubleshooting, see +[Authentication troubleshooting](../authentication/#troubleshooting). diff --git a/content/docs/getting-started/local-setup.md b/content/docs/getting-started/local-setup.md index f10e46a..2112a8a 100644 --- a/content/docs/getting-started/local-setup.md +++ b/content/docs/getting-started/local-setup.md @@ -84,6 +84,11 @@ curl http://localhost:8080/api/v1alpha1/agents When authentication is enabled, add `Authorization: Bearer ` to API calls. See [Authentication](authentication/#authenticating-api-requests). +> **Note:** This is the control plane's own auth for the `/agents` endpoint. The +> environment agent process itself has separate, independent authentication for +> its own API and for its calls back to the control plane — see +> [Environment Agent Authentication](environment-agent-authentication/). + ## Setting Up the CLI The DCM CLI (`dcm`) lets you interact with the DCM control plane from the From 4a7457fa465a89bfa4e007d8586ff5f37bb574f3 Mon Sep 17 00:00:00 2001 From: gabriel-farache Date: Wed, 14 Oct 2026 10:28:21 +0200 Subject: [PATCH 2/3] Fix feedbacks and CI Signed-off-by: gabriel-farache --- .../docs/getting-started/authentication.md | 16 ++-- .../environment-agent-authentication.md | 78 ++++++++++--------- 2 files changed, 49 insertions(+), 45 deletions(-) diff --git a/content/docs/getting-started/authentication.md b/content/docs/getting-started/authentication.md index c0101d0..cfd3391 100644 --- a/content/docs/getting-started/authentication.md +++ b/content/docs/getting-started/authentication.md @@ -226,15 +226,15 @@ returns `403 Forbidden`. ## Troubleshooting -| Symptom | Things to check | -| ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `401 Unauthorized` on API or CLI | Auth enabled; token present and not expired; issuer matches `AUTH_ISSUER_URL`; if `AUTH_JWT_AUDIENCE` is set, token `aud` must match. | -| `dcm login` cannot reach issuer | Host maps `keycloak` (see [host access](#local-compose-host-access-to-keycloak)); issuer matches discovery; TLS if using HTTPS. | -| Issuer / JWKS errors in control-plane logs | `AUTH_ISSUER_URL` reachable from the control-plane container; Keycloak healthy (`auth` profile running). | -| CLI works but UI fails (or reverse) | Backstage SSO and control plane must trust the same IdP and audience; plugin backend URL points at the control plane. | -| `403 Forbidden` with valid token | Actor suspended or deactivated; wait up to `AUTH_CACHE_TTL` after status changes. | +| Symptom | Things to check | +| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `401 Unauthorized` on API or CLI | Auth enabled; token present and not expired; issuer matches `AUTH_ISSUER_URL`; if `AUTH_JWT_AUDIENCE` is set, token `aud` must match. | +| `dcm login` cannot reach issuer | Host maps `keycloak` (see [host access](#local-compose-host-access-to-keycloak)); issuer matches discovery; TLS if using HTTPS. | +| Issuer / JWKS errors in control-plane logs | `AUTH_ISSUER_URL` reachable from the control-plane container; Keycloak healthy (`auth` profile running). | +| CLI works but UI fails (or reverse) | Backstage SSO and control plane must trust the same IdP and audience; plugin backend URL points at the control plane. | +| `403 Forbidden` with valid token | Actor suspended or deactivated; wait up to `AUTH_CACHE_TTL` after status changes. | | Service provider workflow returns an auth error | Identify which request failed: SP-to-agent provider API calls use inbound `AGENT_AUTH_*` settings and the SP's token; agent registration and heartbeat calls use outbound `DCM_AUTH_*` settings and the control plane's `AUTH_*` settings. See [Environment Agent Authentication](../environment-agent-authentication/). | -| Device flow times out | Complete browser approval within the time shown; retry `dcm login`. | +| Device flow times out | Complete browser approval within the time shown; retry `dcm login`. | Verify Keycloak readiness when using compose: diff --git a/content/docs/getting-started/environment-agent-authentication.md b/content/docs/getting-started/environment-agent-authentication.md index 847664b..e891451 100644 --- a/content/docs/getting-started/environment-agent-authentication.md +++ b/content/docs/getting-started/environment-agent-authentication.md @@ -36,9 +36,8 @@ token on every request. This closes the gap called out in the external SP registration was previously unauthenticated, with network isolation as the only interim mitigation. -`GET /api/v1alpha1/health` is the only endpoint that stays public — the bypass -checks both the method and the path, so `GET /health` is unauthenticated but any -other method at that path still requires a token. +Only `GET /api/v1alpha1/health` stays public. The bypass checks both the method +and exact path, so `GET /health` and every other method or path require a token. ### How it works @@ -72,13 +71,12 @@ This mirrors the control plane's `AUTH_DISABLED` / `AUTH_ISSUER_URL` / but with an `AGENT_` prefix and its own env vars — the two services are configured independently, even when pointed at the same Keycloak realm. -> **Audience is intentionally permissive by default.** Reference Keycloak -> clients for service accounts (used by SPs registering with the agent) don't -> ship with an audience mapper out of the box. Rather than reject every token -> from an unmapped client, the agent skips the audience check when -> `AGENT_AUTH_JWT_AUDIENCE` is empty, and only enforces `aud` matching when you -> explicitly set it. Set it once your SP clients have a matching audience -> mapper. +> **Set an audience before production.** When `AGENT_AUTH_JWT_AUDIENCE` is +> empty, the agent skips audience validation: any otherwise-valid token from the +> configured issuer is accepted, regardless of its `aud` claim. For production, +> configure a dedicated audience and add it to tokens from every authorized SP +> client with an audience mapper. Leave the audience empty only for local +> development while configuring those mappers. ### Calling the agent API with a bearer token @@ -163,10 +161,10 @@ an absolute, host-qualified `http(s)://` URL. reactively on a `401`. - A token fetch failure does **not** crash the agent. Registration and re-registration retry transient failures with exponential backoff - (`DCM_REGISTRATION_INITIAL_BACKOFF` / - `DCM_REGISTRATION_MAX_BACKOFF`). A failed heartbeat is logged and retried on - the next heartbeat tick, controlled by `AGENT_HEARTBEAT_INTERVAL` (30 seconds - by default); heartbeat failures do not use the registration backoff. + (`DCM_REGISTRATION_INITIAL_BACKOFF` / `DCM_REGISTRATION_MAX_BACKOFF`). A + failed heartbeat is logged and retried on the next heartbeat tick, controlled + by `AGENT_HEARTBEAT_INTERVAL` (30 seconds by default); heartbeat failures do + not use the registration backoff. - **Static tokens do not refresh.** Once the token expires, the control plane returns `401`, which the agent treats as non-retryable — registration halts until the agent is restarted with a fresh token. Use static tokens only where @@ -174,24 +172,30 @@ an absolute, host-qualified `http(s)://` URL. ### Keycloak setup -The reference Keycloak realm already includes the confidential `dcm-proxy` -client, with service accounts enabled and a `dcm-api` audience mapper. For this -setup, use the token endpoint and `dcm-proxy` credentials shown in the -[control-plane `.env.example`](https://github.com/dcm-project/control-plane/blob/main/deploy/.env.example): -set `DCM_AUTH_CLIENT_ID=dcm-proxy` and set `DCM_AUTH_CLIENT_SECRET` to the same -secret configured for `AUTH_PROXY_SECRET`. - -You can use a separate client if your deployment needs one. Enable **Client -authentication** and **Service accounts roles**, then set the three -`DCM_AUTH_*` variables to that client's token endpoint and credentials. The -control plane currently requires an authenticated actor context for agent -registration; the registration endpoint does not check for a particular -Keycloak role. +The reference Keycloak realm includes the confidential `dcm-proxy` client, with +service accounts enabled and a `dcm-api` audience mapper. The reference Compose +and Helm setups reuse the `dcm-proxy` client secret as `AUTH_PROXY_SECRET`; the +control plane accepts that secret in `X-Auth-Proxy-Secret` requests and trusts +the accompanying forwarded identity headers. Someone who obtains the agent's +environment can use the shared secret with a forged `X-Forwarded-User` value to +act as any resolvable actor. Keep this shared-secret setup local to development. +In production, use a dedicated Keycloak client for the agent, with a client +secret independent from `AUTH_PROXY_SECRET`, and configure the deployment to +inject that secret as `DCM_AUTH_CLIENT_SECRET`. The reference Helm chart +currently sources `DCM_AUTH_CLIENT_SECRET` from the `AUTH_PROXY_SECRET` key, so +it needs separate secret wiring before using this production setup. + +To configure a dedicated client, enable **Client authentication** and **Service +accounts roles**, then set the three `DCM_AUTH_*` variables to that client's +token endpoint and credentials. The control plane currently requires an +authenticated actor context for agent registration; the registration endpoint +does not check for a particular Keycloak role. > **Audience mapper for custom clients:** If the control plane enforces -> `AUTH_JWT_AUDIENCE=dcm-api`, a new client must include `dcm-api` in its token's -> `aud` claim. Add an audience mapper to that client. The reference `dcm-proxy` -> client already has this mapper, so it does not need additional configuration. +> `AUTH_JWT_AUDIENCE=dcm-api`, a new client must include `dcm-api` in its +> token's `aud` claim. Add an audience mapper to that client. The reference +> `dcm-proxy` client already has this mapper, so it does not need additional +> configuration. ### Kubernetes secrets @@ -206,14 +210,14 @@ envFrom: ## Troubleshooting -| Symptom | Things to check | -| -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -| SP registration returns `401` from the agent | Auth enabled on the agent (`AGENT_AUTH_DISABLED=false`); the SP's token is valid and not expired; issuer matches `AGENT_AUTH_ISSUER_URL`; if `AGENT_AUTH_JWT_AUDIENCE` is set, the token's `aud` must match. | +| Symptom | Things to check | +| -------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| SP registration returns `401` from the agent | Auth enabled on the agent (`AGENT_AUTH_DISABLED=false`); the SP's token is valid and not expired; issuer matches `AGENT_AUTH_ISSUER_URL`; if `AGENT_AUTH_JWT_AUDIENCE` is set, the token's `aud` must match. | | Agent registration/heartbeat to the control plane returns `401` | Check the `DCM_AUTH_*` client credentials and token endpoint, then verify that the token issuer and (when enabled) audience match the control plane's `AUTH_*` settings. Add a `dcm-api` mapper for a custom client if required; the reference `dcm-proxy` client already has one. | -| Agent fails to start with `AGENT_AUTH_ISSUER_URL: required...` | `AGENT_AUTH_DISABLED=false` but no issuer was set — set `AGENT_AUTH_ISSUER_URL` or leave auth disabled. | -| Agent fails to start with a "partial client-credentials auth config" error | Only some of `DCM_AUTH_TOKEN_ENDPOINT` / `DCM_AUTH_CLIENT_ID` / `DCM_AUTH_CLIENT_SECRET` are set — set all three or none. | -| Registration halts permanently after working for a while | Static `DCM_AUTH_TOKEN` expired (no refresh) — switch to client credentials, or restart the agent with a fresh token. | -| `AGENT_AUTH_JWT_AUDIENCE` startup warning | Expected when an issuer is set without an audience — informational unless you intended to enforce `aud`. | +| Agent fails to start with `AGENT_AUTH_ISSUER_URL: required...` | `AGENT_AUTH_DISABLED=false` but no issuer was set — set `AGENT_AUTH_ISSUER_URL` or leave auth disabled. | +| Agent fails to start with a "partial client-credentials auth config" error | Only some of `DCM_AUTH_TOKEN_ENDPOINT` / `DCM_AUTH_CLIENT_ID` / `DCM_AUTH_CLIENT_SECRET` are set — set all three or none. | +| Registration halts permanently after working for a while | Static `DCM_AUTH_TOKEN` expired (no refresh) — switch to client credentials, or restart the agent with a fresh token. | +| `AGENT_AUTH_JWT_AUDIENCE` startup warning | Expected when an issuer is set without an audience — informational unless you intended to enforce `aud`. | For control-plane-side issuer, JWKS, and Keycloak troubleshooting, see [Authentication troubleshooting](../authentication/#troubleshooting). From 4aabeabb31898980065087a5f4c1aab157b51f25 Mon Sep 17 00:00:00 2001 From: gabriel-farache Date: Wed, 14 Oct 2026 11:04:16 +0200 Subject: [PATCH 3/3] docs: clarify environment agent authentication Signed-off-by: gabriel-farache --- .../environment-agent-authentication.md | 40 ++++++++++++------- 1 file changed, 25 insertions(+), 15 deletions(-) diff --git a/content/docs/getting-started/environment-agent-authentication.md b/content/docs/getting-started/environment-agent-authentication.md index e891451..81e8bde 100644 --- a/content/docs/getting-started/environment-agent-authentication.md +++ b/content/docs/getting-started/environment-agent-authentication.md @@ -36,14 +36,14 @@ token on every request. This closes the gap called out in the external SP registration was previously unauthenticated, with network isolation as the only interim mitigation. -Only `GET /api/v1alpha1/health` stays public. The bypass checks both the method -and exact path, so `GET /health` and every other method or path require a token. +When auth is enabled, only `GET /api/v1alpha1/health` bypasses authentication. +Every other request, including any other method at that path, requires a token. ### How it works -1. At startup, the agent discovers OIDC metadata from the issuer. When it - validates a token, it fetches signing keys from the issuer's JWKS endpoint as - needed and caches them. +1. At startup, the agent performs OIDC discovery to read issuer metadata, + including the JWKS URL. On the first token validation, it fetches signing + keys from that endpoint as needed and caches them. 2. On each protected request, the agent extracts the `Authorization: Bearer ` header (case-insensitive scheme) and validates signature, expiry, issuer, and — if configured — audience. @@ -59,11 +59,11 @@ and exact path, so `GET /health` and every other method or path require a token. ### Configuration -| Variable | Purpose | -| ------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `AGENT_AUTH_DISABLED` | When `true` (the default), auth middleware is bypassed. The agent still logs a startup `WARN` ("authentication is disabled") so the insecure default is visible in logs. | -| `AGENT_AUTH_ISSUER_URL` | OIDC issuer URL for JWT validation (for example `http://keycloak:8080/realms/dcm`). Required when `AGENT_AUTH_DISABLED=false`; startup fails otherwise. | -| `AGENT_AUTH_JWT_AUDIENCE` | Expected `aud` claim. Empty (the default) **disables audience validation** — any token from the issuer is accepted regardless of `aud`. The agent logs a startup `WARN` if an issuer is set but the audience is empty. | +| Variable | Purpose | +| ------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `AGENT_AUTH_DISABLED` | When `true` (the default), auth middleware is bypassed. The agent still logs a startup `WARN` ("authentication is disabled") so the insecure default is visible in logs. | +| `AGENT_AUTH_ISSUER_URL` | OIDC issuer URL for JWT validation (for example `http://keycloak:8080/realms/dcm`). Required when `AGENT_AUTH_DISABLED=false`; startup fails otherwise. | +| `AGENT_AUTH_JWT_AUDIENCE` | Expected token audience (the `aud` claim). Empty (the default) **disables audience validation** — any token from the issuer is accepted regardless of `aud`. The agent logs a startup `WARN` if an issuer is set but the audience is empty. | This mirrors the control plane's `AUTH_DISABLED` / `AUTH_ISSUER_URL` / `AUTH_JWT_AUDIENCE` variables (see @@ -80,6 +80,13 @@ configured independently, even when pointed at the same Keycloak realm. ### Calling the agent API with a bearer token +Start the agent through the utilities deployment script with +`--with-environment-agent` and the required `--agent-embedded-sps` list; see the +[environment-agent deployment instructions](https://github.com/dcm-project/utilities/blob/main/README.md#environment-agent-embedded-sps). +The host API port defaults to `8081`; set `--agent-port` or `AGENT_PORT` to use +another port. The standalone KubeVirt SP also uses `8081`, so choose a different +agent port when using both. + Set `SP_TOKEN` to an access token issued by the same issuer configured in `AGENT_AUTH_ISSUER_URL`, using the flow provisioned for the calling SP. For background on obtaining issuer-issued tokens, see @@ -166,9 +173,12 @@ an absolute, host-qualified `http(s)://` URL. by `AGENT_HEARTBEAT_INTERVAL` (30 seconds by default); heartbeat failures do not use the registration backoff. - **Static tokens do not refresh.** Once the token expires, the control plane - returns `401`, which the agent treats as non-retryable — registration halts - until the agent is restarted with a fresh token. Use static tokens only where - the token's lifetime safely exceeds the agent's expected uptime. + returns `401`. The agent treats that response as non-retryable, so initial + registration or re-registration stops retrying. If the agent has already + registered, its heartbeat loop continues sending requests at each + `AGENT_HEARTBEAT_INTERVAL`, but each request fails until the agent is + restarted with a fresh token. Use static tokens only where the token's + lifetime safely exceeds the agent's expected uptime. ### Keycloak setup @@ -216,8 +226,8 @@ envFrom: | Agent registration/heartbeat to the control plane returns `401` | Check the `DCM_AUTH_*` client credentials and token endpoint, then verify that the token issuer and (when enabled) audience match the control plane's `AUTH_*` settings. Add a `dcm-api` mapper for a custom client if required; the reference `dcm-proxy` client already has one. | | Agent fails to start with `AGENT_AUTH_ISSUER_URL: required...` | `AGENT_AUTH_DISABLED=false` but no issuer was set — set `AGENT_AUTH_ISSUER_URL` or leave auth disabled. | | Agent fails to start with a "partial client-credentials auth config" error | Only some of `DCM_AUTH_TOKEN_ENDPOINT` / `DCM_AUTH_CLIENT_ID` / `DCM_AUTH_CLIENT_SECRET` are set — set all three or none. | -| Registration halts permanently after working for a while | Static `DCM_AUTH_TOKEN` expired (no refresh) — switch to client credentials, or restart the agent with a fresh token. | -| `AGENT_AUTH_JWT_AUDIENCE` startup warning | Expected when an issuer is set without an audience — informational unless you intended to enforce `aud`. | +| Agent heartbeats return `401` after the static token expires | Heartbeat attempts continue but fail because static tokens do not refresh. Restart with a fresh token or use client credentials. | +| `AGENT_AUTH_JWT_AUDIENCE` startup warning | Expected when an issuer is set without an audience — informational unless you intended to enforce the token audience claim. | For control-plane-side issuer, JWKS, and Keycloak troubleshooting, see [Authentication troubleshooting](../authentication/#troubleshooting).