Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions content/docs/getting-started/_index.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
32 changes: 19 additions & 13 deletions content/docs/getting-started/authentication.md
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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:

Expand Down
Loading
Loading