Skip to content

docs: add Console OAuth/OIDC tutorial - #918

Open
rsdmike wants to merge 1 commit into
mainfrom
docs/console-oauth
Open

rsdmike wants to merge 1 commit into
mainfrom
docs/console-oauth

Conversation

@rsdmike

@rsdmike rsdmike commented Oct 23, 2026

Copy link
Copy Markdown
Member

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:

  • How the mode switch works (auth.clientId), the token rules Console enforces (RS256 JWT, exact iss, aud contains auth.clientId)
  • Provider tabs: Microsoft Entra ID, Amazon Cognito (Pre token generation V2_0 trigger to add aud, strict discovery off), Keycloak (audience mapper), other providers
  • config.yml and environment variable examples, a settings reference, behaviour changes in OAuth mode, verification steps and troubleshooting

Also 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 updated
  • Tutorials overview and the AUTH_CLIENT_ID row in Console Configuration link to the new page

Anything the reviewer should know when reviewing this PR?

  • Content is based on Console main (config/config.go, internal/controller/httpapi/v1/login.go, internal/controller/httpapi/ui.go) and the Sample Web UI OAuth setup.
  • The old URL Tutorials/modifyUserAuth/ will 404 after publish since the site has no redirect plugin.
  • zensical build --strict passes locally. The IdP steps have not been run end to end against live Entra, Cognito or Keycloak tenants.

Copilot AI balanced review requested due to automatic review settings October 23, 2026 15:41

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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

@rsdmike
rsdmike force-pushed the docs/console-oauth branch 4 times, most recently from b3b399b to f4a55db Compare October 23, 2026 16:06

@sudhir-intc sudhir-intc left a comment •

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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"

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
!!! warning "Warning - IdP Reachability at Startup"
!!! warning "Warning - IdP Reachability"

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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` |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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`. |

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
- **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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
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.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants