FLPATH-4479: Add authentication user guide

[gciavarrini]

Documents how to use DCM when authentication is enabled on the control plane

Adds a Getting Started Authentication page covering OIDC/JWT behavior, operator prerequisites (compose/Helm pointers to control-plane RUN.md), CLI device login and static tokens, API Authorization: Bearer usage, Backstage/UI login at a high level, and common troubleshooting. Updates CLI Configuration, Local Setup, Troubleshooting, and DCM UI with cross-links and auth-related settings (issuer-url, DCM_TOKEN, dcm login / logout).

Content matches current implementation (Keycloak reference stack, default AUTH_DISABLED=true, public health endpoint, service-provider auth caveat).

---

Fixes: FLPATH-4479

Summary by Sourcery

Document how to configure and use authenticated DCM control planes across the CLI, API, and web UI.

New Features:

• Add a getting-started authentication guide covering OIDC/JWT setup, CLI and UI login, bearer-token API access, operator prerequisites, and troubleshooting.

Enhancements:

• Document authentication configuration, issuer and audience behavior, static CLI tokens, login/logout workflows, and the distinction between unauthenticated health checks and protected endpoints.
• Add cross-links and authentication guidance to local setup, troubleshooting, CLI configuration, the user guide, and the DCM UI documentation.

Documentation:

• Add documentation for enabling authentication in compose and Helm deployments, including Keycloak-based local setup and service-provider limitations.

Chores:

• Update spell-check vocabulary for authentication and local-environment terminology.

[qodo-code-review]

Code Review by Qodo

🐞 Bugs (0) 📘 Rule violations (0) 📜 Skill insights (0)

1. Host CLI cannot reach the example issuer ✓ Resolved 🐞 Bug ≡ Correctness

Description

The CLI example sets DCM_ISSUER_URL to http://keycloak:8080/realms/dcm, a hostname available on
the compose network but not normally resolvable from the host running dcm login. Users following
the documented host-side command therefore cannot perform OIDC discovery or device login unless they
apply the fragile container-IP workaround described later.

Code

content/docs/getting-started/authentication.md[R109-113]

+```bash
+export DCM_ISSUER_URL=http://keycloak:8080/realms/dcm
+dcm login --control-plane-url http://localhost:8080
+dcm sp provider list
+```

Agent prompt

The issue below was found during a code review. Follow the provided context and guidance below and implement a solution

## Issue description
The primary CLI example uses `http://keycloak:8080/realms/dcm` while the command is run from the host, where the compose-only `keycloak` hostname is generally unavailable. This causes OIDC discovery and `dcm login` to fail for users following the example.

## Fix Focus Areas
- content/docs/getting-started/authentication.md[107-131]

## Recommended Fix
Use the externally reachable issuer URL returned by the deployed Keycloak configuration in the CLI example, or explicitly separate host and container URLs. Document the required host DNS/hosts mapping or port exposure before showing the command, and ensure the example issuer matches the issuer returned by the well-known discovery endpoint.

ⓘ Copy this prompt and use it to remediate the issue with your preferred AI generation tools

---

Context sources

⚠️ Tickets: not configured — ticket URL found in PR but could not be fetched — check ticket provider credentials

Review mode: 🚀 Fast: This is a self-contained documentation-only change with no runtime behavior, schema, configuration, or code effects, so a lightweight review is sufficient.

Tip of the day

💡 Did you know, you can type 'qodo, fix this' on a finding and the fix lands right on your PR

More tips ↗ | Customize Qodo ↗ | Qodo docs ↗

[qodo-code-review]

PR Summary by Qodo

Document authentication workflows for CLI, API, and UI

📝 Documentation ⚙️ Configuration changes 🕐 20-40 Minutes

AI Description

• Add an authentication guide covering OIDC setup, token flows, API usage, and limitations.
• Cross-link authentication guidance from setup, CLI, UI, and troubleshooting documentation.
• Add authentication terminology to spell-check configuration.

Diagram

sequenceDiagram
  actor User
  participant Client as DCM Clients
  participant IdP as OIDC Provider
  participant CP as Control Plane
  participant Actors as Actor Store
  User->>Client: Start authentication
  Client->>IdP: Device flow or SSO
  IdP-->>Client: JWT access token
  Client->>CP: Bearer API request
  CP->>IdP: Fetch discovery and JWKS
  IdP-->>CP: Issuer metadata and keys
  CP->>Actors: Resolve or provision actor
  Actors-->>CP: Actor status
  CP-->>Client: Authorized response

Loading

High-Level Assessment

A centralized authentication guide with focused cross-links is the best approach because OIDC configuration, token handling, and troubleshooting share common concepts across CLI, API, and UI users. Separate persona-specific guides were considered but would duplicate security-sensitive details and increase the risk of inconsistent guidance.

Files changed (8) +305 / -1

Documentation (7) +301 / -1

_index.mdAdd authentication to Getting Started navigation +2/-0

Add authentication to Getting Started navigation

• Adds the authentication guide to the Getting Started overview so users can discover login and bearer-token guidance.

content/docs/getting-started/_index.md

authentication.mdAdd comprehensive DCM authentication guide +209/-0

Add comprehensive DCM authentication guide

• Documents OIDC/JWT behavior, deployment prerequisites, control-plane settings, CLI device login, static tokens, API authorization, Backstage SSO, and troubleshooting. It also calls out the unauthenticated health endpoint and current service-provider authentication limitation.

content/docs/getting-started/authentication.md

local-setup.mdClarify authentication defaults in local setup +7/-1

Clarify authentication defaults in local setup

• Explains that local authentication is disabled by default and distinguishes unauthenticated provider requests from bearer-authenticated API calls. Links readers to the new authentication workflow.

content/docs/getting-started/local-setup.md

troubleshooting.mdAdd authentication troubleshooting checks +20/-0

Add authentication troubleshooting checks

• Adds checks for control-plane settings, CLI credentials, JWT audiences, and identity-provider reachability. Clarifies that the health endpoint remains publicly accessible.

content/docs/getting-started/troubleshooting.md

_index.mdLink authentication from the user guide +2/-0

Link authentication from the user guide

• Adds authentication to the user-guide overview for easier discovery of login and bearer-token instructions.

content/docs/user-guide/_index.md

cli-configuration.mdDocument CLI authentication configuration +49/-0

Document CLI authentication configuration

• Adds the issuer URL and token flags, configuration key, and environment variables. Documents interactive device login, logout, token storage and refresh behavior, and static-token usage for automation.

content/docs/user-guide/cli-configuration.md

ui.mdDocument Backstage authentication behavior +12/-0

Document Backstage authentication behavior

• Explains how the DCM plugin forwards Backstage OAuth2 bearer tokens and why operators must configure compatible SSO separately. Notes the local compose UI limitation and links to the full authentication guide.

content/docs/user-guide/ui.md

Other (1) +4 / -0

cspell.yamlAllow authentication terminology in spell checks +4/-0

Allow authentication terminology in spell checks

• Adds JWKS, Keycloak, keyring, and OIDC to the accepted spelling dictionary.

cspell.yaml

[sourcery-ai]

Hey - I've found 1 issue

Prompt for AI Agents

Please address the comments from this code review:

## Individual Comments

### Comment 1
<location path="content/docs/getting-started/authentication.md" line_range="110-131" />
<code_context>
+Example for the reference Keycloak realm (issuer must match OIDC discovery):
+
+```bash
+export DCM_ISSUER_URL=http://keycloak:8080/realms/dcm
+dcm login --control-plane-url http://localhost:8080
+dcm sp provider list
+```
+
+`dcm login` saves `issuer-url` in `~/.dcm/config.yaml`. Tokens are stored in the
+OS keyring when available, otherwise in `~/.dcm/tokens.json` (mode `0600`).
+
+To sign out and remove stored tokens:
+
+```bash
+dcm logout
+```
+
+See [CLI Configuration](../user-guide/cli-configuration/#authentication) for
+flags and environment variables.
+
+> **Local issuer hostname:** The reference stack advertises issuer
+> `http://keycloak:8080/realms/dcm`. The control plane resolves `keycloak` on
+> the compose network. On your host, map `keycloak` to the Keycloak container IP
+> (or use the same issuer URL your operator documents) so `dcm login` can reach
+> OIDC discovery and the device flow.
+
+### Web UI (Backstage)
</code_context>
<issue_to_address>
**issue:** The copy-pasted CLI example uses `http://keycloak:8080/realms/dcm`, but a CLI running on the host cannot resolve the `keycloak` container hostname by default, so `dcm login` fails during OIDC discovery. The suggested workaround of mapping the hostname to a container IP is not reproducible or stable, and replacing the hostname with `localhost` will fail issuer validation unless the IdP is configured to advertise that issuer.

**Triggers:** When a user runs the documented login command from the host against the local compose stack.

**Suggested fix:** Use an issuer hostname reachable from the host and configure Keycloak and `AUTH_ISSUER_URL` to advertise that same hostname, or provide explicit, stable host-to-container DNS/port-mapping instructions.
</issue_to_address>

Sourcery assessment

Approval pending. 1 finding to address first.

Blocking findings: content/docs/getting-started/authentication.md:131

---

Sourcery is free for open source - if you like our reviews please consider sharing them ✨

• X
• Mastodon
• LinkedIn
• Facebook

[vkolodny]

Separate from the inline /providers curl examples: the doc also uses dcm sp provider list in a few places. That CLI subcommand still calls the removed /api/v1alpha1/providers route (control-plane#51). The CLI should be updated to list registrations via the supported API (e.g. /agents) and then these doc examples can follow — worth a CLI follow-up so users are not pointed at a dead endpoint.

[chadcrum]

lgtm! thank you!

[testetson22]

lgtm

[jordigilh]

Reviewed in depth; no outstanding important findings.

[jordigilh]

Changing my earlier approval to request changes after a current-head audit. The authentication guide still instructs users to run dcm sp provider list, but the current CLI calls the removed /api/v1alpha1/providers route, so the documented smoke flow ends in 404. The existing review thread identifies this same issue; it must be fixed before approval/merge.

[sourcery-ai]

Sourcery assessment

Approved.

[gciavarrini]

Changing my earlier approval to request changes after a current-head audit. The authentication guide still instructs users to run dcm sp provider list, but the current CLI calls the removed /api/v1alpha1/providers route, so the documented smoke flow ends in 404. The existing review thread identifies this same issue; it must be fixed before approval/merge.

@jordigilh Fixed in 6ff7285

[jordigilh]

lgtm