Auth: Un-deprecate getLatestToken and route per-request fetches through it (closes #22647, #22816)

[iOvergaard]

Summary

Fixes #22647

Since version 17.3, getLatestToken() had been limited in functionality, but that turned out to be a behavioral breaking change, because certain guides/tutorials/older dotnet templates advised to use this method. In the spirit of keeping this functionality working, because it is not limiting us in any way, we have decided to un-deprecate this method and actually make it work again. You can use it for any fetch clients (hey-api, ky, axios, etc), although it is advisable to use getOpenApiConfiguration instead, because that will also give you the base URL and cookie configuration.

If you follow the dotnet template and generate the API client with @hey-api/openapi-ts, you should use configureClient() instead. This PR includes a change to the dotnet template that enables its usage:

import type {
  UmbEntryPointOnInit,
  UmbEntryPointOnUnload,
} from "@umbraco-cms/backoffice/extension-api";
import { UMB_AUTH_CONTEXT } from "@umbraco-cms/backoffice/auth";
import { client } from "../api/client.gen.js";

export const onInit: UmbEntryPointOnInit = async (host, _extensionRegistry) => {
  const authContext = await host.getContext(UMB_AUTH_CONTEXT);
  if (!authContext) {
    console.warn("UMB_AUTH_CONTEXT not available — extension API client will not be authenticated");
    return;
  }
  authContext.configureClient(client);
}

Changes

• Removes the @deprecated JSDoc tag and the UmbDeprecation.warn() call.
• configureClient's auth callback and getOpenApiConfiguration's token callback both delegate to getLatestToken.bind(this) — single implementation, single gate.
• unlinkLogin and #makeLinkTokenRequest previously sent a hard-coded Authorization: Bearer [redacted] header. Replaced with Bearer ${await this.getLatestToken()} so those fetches participate in the refresh coordination rather than firing with a possibly-stale cookie.
• Wires the UmbracoExtension template's entrypoint to call authContext.configureClient(client). The framework awaits onInit, so this guarantees the API client is fully configured before any element in the extension can hit it. (Same change is going out on v18 in Build: Upgrade @hey-api/openapi-ts to 0.97 #22735.)

Minor changes discovered while working on this

• configureClient(client) now accepts a new structural UmbApiClient type exported from @umbraco-cms/backoffice/http-client. Each @hey-api/openapi-ts generation produces a fully-bound Client<…>; the backoffice's umbHttpClient and an extension's regenerated client are structurally identical but TS treats them as distinct generic instantiations. The widened parameter lets extensions wire their own client without as never casts at call sites. bindDefaultInterceptors keeps its strict typeof umbHttpClient parameter (preserving autocomplete inside interceptor callbacks); the cast happens once, internally.
• The auth context now holds a single UmbApiInterceptorController, lazy-initialised on first configureClient() call. Previously each call instantiated a new controller, which re-provided the UmbAuthSignalerContext on the host and stacked listeners — visible the moment an extension also called configureClient. One controller for the lifetime of the host, all configured clients share it.
• completeAuthorizationRequest checks sessionStorage before asking window.opener for the PKCE verifier. The previous order hung for the full postMessage timeout whenever oauth_complete loaded with a non-OAuth window.opener (which is set for any window.open target). The opener postMessage timeout is also dropped from 5s to 1.5s.
• The cross-tab 'authorized' BroadcastChannel handler now routes through #setSessionLocally so the timestamp math stays in one place. The 'sessionUpdate' handler still applies pre-computed timestamps directly (peer broadcast already did the math) but does so inside the #inSessionUpdateCallback guard, so a synchronous session$ observer can no longer trigger a spurious /token refresh on top of a peer's update.
• #ensureTokenReady drops its query-then-request pattern. Now always queues behind the umb:token-refresh lock with a no-op callback — eliminates the race window between query() and request().
• destroy() invokes #popupCleanup before tearing down so an in-flight popup flow's window-level message listener and closed-poll interval don't leak past the context's lifetime. The cleanup helper itself now resolves the popup-flow Promise — every termination path (authorized, popup closed, superseded, destroyed) is observable to the awaiter instead of hanging forever.
• makeAuthorizationRequest is annotated Promise<void>.
• unlinkLogin wraps the parsed problem-details payload in a real Error (with the original payload exposed on .cause) so callers using instanceof Error or expecting a stack trace get sane behaviour.

Test plan

• npm run test — the auth-context test suite (23 tests) passes
• No new TS or lint errors in changed files
• Scaffold a fresh extension via dotnet new umbraco-extension --include-example true, run it, and verify the dashboard's three buttons work — the entrypoint now wires configureClient(client) instead of relying on the inherited umbHttpClient config copy

Backport

Self-contained. I'll cherry-pick this manually to release/17.4.0 and release/18.0 after it lands here.

🤖 Generated with Claude Code

[claude]

Claude finished @iOvergaard's task in 3m 5s —— View job

---

PR Review

Target: origin/main · Based on commit: 15970f3e · Skipped: 0 noise files

Un-deprecates getLatestToken() (removing the JSDoc tag and runtime UmbDeprecation.warn()) and routes all per-request token fetches — configureClient, getOpenApiConfiguration, unlinkLogin, #makeLinkTokenRequest — through it as the single authoritative token gate. Also adds configureClient(client) wiring to the extension template's onInit.

• Modified public API: UmbAuthContext.getLatestToken (removed @deprecated and runtime deprecation warning); UmbAuthContext.getOpenApiConfiguration().token callback (was () => Promise.resolve('[redacted]'), now routes through getLatestToken.bind(this))
• Other changes: unlinkLogin and #makeLinkTokenRequest now call getLatestToken() instead of hardcoding Bearer [redacted] — these requests now participate in token refresh coordination; extension template onInit now wires configureClient(client) as part of scaffolded setup

---

Suggestions

• templates/UmbracoExtension/Client/src/entrypoints/entrypoint.ts:10-15: The comment block describes what configureClient() does (baseUrl, credentials, auth callback, interceptors). This restates the API docs. The non-obvious part worth keeping is just the last sentence about onInit ordering — the rest can be dropped. Trimming to a single line preserves the useful signal without narrating the implementation:

  // Resolving UMB_AUTH_CONTEXT here guarantees the client is fully configured
  // before any element in this extension can call it (framework awaits onInit).
  const authContext = await host.getContext(UMB_AUTH_CONTEXT);

• src/Umbraco.Web.UI.Client/src/packages/core/auth/auth.context.ts:720-724 and :833-838: unlinkLogin and #makeLinkTokenRequest now correctly route through getLatestToken(). Neither is covered by a test — the existing test only checks method existence. A test verifying the Authorization header is set (e.g., via a stubbed getLatestToken) would be valuable given these methods touch the external login provider flow, which is hard to catch manually. Low priority given the auth context's overall test strategy, but worth noting.

---

Approved with Suggestions for improvement

Good to go, but please carefully consider the importance of the suggestions.

The core change is correct and well-motivated. The consolidation into a single token gate (getLatestToken as the source of truth) is a clear improvement over three diverging implementations. The behavioral fix for unlinkLogin/#makeLinkTokenRequest — which previously sent hardcoded [redacted] without going through refresh coordination — is a genuine bug fix. The un-deprecation is justified: no clean alternative existed for non-@hey-api consumers.

No breaking changes: un-deprecating a method is additive, and getLatestToken's signature is unchanged.

[Copilot]

Pull request overview

This PR re-establishes UmbAuthContext.getLatestToken() as the canonical public API for “get a request-safe token right now” (including refresh coordination), and routes internal auth-related requests and OpenAPI client configuration through it. It also updates the UmbracoExtension client template entrypoint to configure the generated API client via the backoffice auth context.

Changes:

• Un-deprecates getLatestToken() by removing the @deprecated JSDoc tag and UmbDeprecation.warn() call, while keeping its refresh-coordination behavior.
• Makes configureClient() and getOpenApiConfiguration() delegate their token/auth callbacks to getLatestToken() to centralize token readiness logic.
• Updates link/unlink login fetches to use Bearer ${await this.getLatestToken()} instead of a hard-coded Bearer [redacted] header; updates the extension template to call authContext.configureClient(client) during initialization.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

File	Description
templates/UmbracoExtension/Client/src/entrypoints/entrypoint.ts	Wires the generated extension API client through UMB_AUTH_CONTEXT.configureClient(...) during entrypoint initialization.
src/Umbraco.Web.UI.Client/src/packages/core/auth/auth.context.ts	Un-deprecates getLatestToken() and routes OpenAPI + internal auth-related requests through it for coordinated refresh readiness.

[iOvergaard]

@leekelleher You already tested part of this for v18 earlier today (the UmbracoExtension part). This PR brings it back to v17 and takes care of another bug that Matt Brailsford discovered, which we'll merge forward to v18, too. So it's a bit of back and forth, but I hope that explains why, at least.

[AndyButland]

Cherry-picked to release/17.4.0 and release/17.5.0 and release/18.0.