Repository navigation
Conversation
There was a problem hiding this comment.
🟡 Changes recommended
Provider setup and authentication behavior guidance contain inaccuracies that can block sign-in or mislead operators.
4 open issues
What changed in this PR
Adds a Console OAuth/OIDC tutorial and groups authentication guides together in the documentation.
Changes:
- Documents provider setup, Console configuration, token requirements, verification, and troubleshooting.
- Moves the MPS authentication tutorial under Authentication and adjusts its relative links and image paths.
- Adds navigation and reference links to the new tutorial.
| File | Description |
|---|---|
mkdocs.yml |
Groups both tutorials under Authentication. |
docs/Tutorials/overview.md |
Introduces links to both authentication guides. |
docs/Tutorials/Authentication/modifyUserAuth.md |
Updates relative paths after relocation. |
docs/Tutorials/Authentication/consoleOAuth.md |
Adds the Console OAuth/OIDC setup guide. |
docs/Reference/Console/configuration.md |
Links AUTH_CLIENT_ID to the new tutorial. |
Review effort: Balanced
b3b399b to
f4a55db
Compare
There was a problem hiding this comment.
Nice work.
I tried out this document through copilot with a local keycloak installation and latest console main. I was able to have successfully have console work with keycloak and also activate devices using rpc-go and provding the keycloak token.
Comments which I provided are based on suggestions from Copilot. Feel free to either accept or reject them.
| - At startup, the Console host can reach `<issuer>/.well-known/openid-configuration` and the JWKS URL it points to. | ||
| - You know the exact public URL users will open, for example `https://console.example.com:8181/`. | ||
|
|
||
| !!! warning "Warning - IdP Reachability at Startup" |
There was a problem hiding this comment.
| !!! warning "Warning - IdP Reachability at Startup" | |
| !!! warning "Warning - IdP Reachability" |
There was a problem hiding this comment.
Going to keep this one. On current main, Console actually panics in NewRouter when discovery fails, so it does stop at startup. I reproduced it with an unreachable issuer.
| | `clientId`, `ui.clientId` | `dmt-console` | | ||
| | `issuer`, `ui.issuer` | `https://keycloak.example.com/realms/<realm>` | | ||
| | `ui.scope` | `openid profile` | | ||
|
|
There was a problem hiding this comment.
You could add note here:
For a local Keycloak instance with a self-signed certificate, set AUTH_TLS_SKIP_VERIFY=true only for Console's discovery and JWKS requests, and separately trust or accept the Keycloak certificate in the browser. The environment variable does not change browser certificate validation and is for lab use only.
There was a problem hiding this comment.
Good call, added it as a note in the Keycloak tab. Thanks!
| | AUTH_UI_ISSUER | auth.ui.issuer | Issuer the browser uses. Normally the same as `AUTH_ISSUER`. | | ||
| | AUTH_UI_SCOPE | auth.ui.scope | Space separated scopes. | | ||
| | AUTH_UI_REDIRECT_URI | auth.ui.redirectUri | Must match the IdP registration exactly. | | ||
| | AUTH_UI_RESPONSE_TYPE | auth.ui.responseType | Keep `code`. | |
There was a problem hiding this comment.
Not required.
The embedded Sample Web UI currently uses the Authorization Code response type (code). Although auth.ui.responseType / AUTH_UI_RESPONSE_TYPE exists in Console config, Console does not inject it into the embedded UI; changing it has no effect.
There was a problem hiding this comment.
Agreed, Console never actually passes that through, so I pulled it from the table and the YAML example.
|
|
||
| - **Basic auth tokens stop working on the API.** The API middleware validates only IdP tokens. `POST /api/v1/authorize` is still mounted, and Console still generates and saves an admin password when none is set, so the endpoint can still issue local HS256 tokens to anyone who knows the admin credentials. The API rejects those tokens in OAuth mode, and redirection rejects them because they are not bound to a device. Still treat the admin password as a secret. | ||
| - **The session cookie is disabled** whenever `auth.clientId` is set, and the `AUTH_COOKIE_*` settings are ignored. The UI keeps the IdP tokens and sends them as `Authorization: Bearer`. | ||
| - **Session length is the IdP access token lifetime.** `auth.jwtExpiration` no longer applies to user sessions. The embedded UI does not renew tokens (no silent refresh and no refresh token use), so requesting `offline_access` does not extend sessions. When the access token expires, the API returns `401`, the UI signs the user out, and the user signs in again (usually without a password prompt while the IdP session is still active). To lengthen sessions, raise the access token lifetime in the IdP. |
There was a problem hiding this comment.
| - **Session length is the IdP access token lifetime.** `auth.jwtExpiration` no longer applies to user sessions. The embedded UI does not renew tokens (no silent refresh and no refresh token use), so requesting `offline_access` does not extend sessions. When the access token expires, the API returns `401`, the UI signs the user out, and the user signs in again (usually without a password prompt while the IdP session is still active). To lengthen sessions, raise the access token lifetime in the IdP. | |
| - **Session length is governed by the IdP access token lifetime.** `auth.jwtExpiration` no longer applies to user sessions. The UI does not configure automatic in-session token renewal. During application initialization, it attempts `silentRefresh()` when it has no valid access token; success depends on the IdP session and browser behavior. If a token expires while the application is open, API calls can return `401` and the user may need to sign in again. To lengthen sessions, raise the access token lifetime in the IdP. |
There was a problem hiding this comment.
Keeping this as is. The only silentRefresh() call is inside runInitialLoginSequence(), and nothing calls that on sample-web-ui main yet. Token renewal is coming separately, and the Subject to Change note at the top covers it.
| - You know the exact public URL users will open, for example `https://console.example.com:8181/`. | ||
|
|
||
| !!! warning "Warning - IdP Reachability at Startup" | ||
| Console runs OIDC discovery against `auth.issuer` when it starts. If the issuer cannot be reached, the login routes cannot be created and Console fails to start. Check DNS, proxy and certificate trust before you switch to OAuth. |
There was a problem hiding this comment.
| Console runs OIDC discovery against `auth.issuer` when it starts. If the issuer cannot be reached, the login routes cannot be created and Console fails to start. Check DNS, proxy and certificate trust before you switch to OAuth. | |
| Console needs the discovery document and JWKS endpoint to validate IdP tokens. A failed discovery request does not currently stop the Console process from starting, so a healthy `/healthz` response alone does not confirm OIDC is working. Verify IdP reachability and certificate trust, then test an authenticated API call. |
There was a problem hiding this comment.
Same as the title comment. Discovery failing panics on startup today, so Console never comes up.
Groups it with the MPS user auth tutorial under Tutorials > Authentication. Refs: device-management-toolkit/deployment#682
f4a55db to
cbe894a
Compare

PR Checklist
What are you changing?
Adds a tutorial for turning on OAuth 2.0 / OIDC in Console, aimed at ISVs replacing the default admin login:
auth.clientId), the token rules Console enforces (RS256 JWT, exactiss,audcontainsauth.clientId)aud, strict discovery off), Keycloak (audience mapper), other providersconfig.ymland environment variable examples, a settings reference, behaviour changes in OAuth mode, verification steps and troubleshootingAlso creates Tutorials > Authentication and moves the existing MPS tutorial there:
Tutorials/modifyUserAuth.md->Tutorials/Authentication/modifyUserAuth.md(nav label "MPS User Authentication"), relative links and image paths updatedAUTH_CLIENT_IDrow in Console Configuration link to the new pageAnything the reviewer should know when reviewing this PR?
main(config/config.go,internal/controller/httpapi/v1/login.go,internal/controller/httpapi/ui.go) and the Sample Web UI OAuth setup.Tutorials/modifyUserAuth/will 404 after publish since the site has no redirect plugin.zensical build --strictpasses locally. The IdP steps have not been run end to end against live Entra, Cognito or Keycloak tenants.