feat(oidc-client): add no redirect support for response type none

Author: vatsalparikh

e2e/oidc-app/src/ping-am/index.html

@@ -21,7 +21,8 @@ <h1>OIDC App | PingAM Login</h1>
       <button id="logout">Logout</button>
       <button id="user-info-btn">User Info</button>
       <button id="revoke">Revoke Token</button>
-      <button id="session-check-btn">Session Check (none)</button>
+      <button id="session-check-btn">Session Check (none, iframe)</button>
+      <button id="session-check-no-redirect-btn">Session Check (none, no redirect)</button>
       <button id="session-check-id-token-btn">Session Check (id_token)</button>
       <a href="/ping-am/">Start Over</a>
     </div>

e2e/oidc-app/src/ping-one/index.html

@@ -21,7 +21,8 @@ <h1>OIDC App | P1 Login</h1>
       <button id="logout">Logout</button>
       <button id="user-info-btn">User Info</button>
       <button id="revoke">Revoke Token</button>
-      <button id="session-check-btn">Session Check (none)</button>
+      <button id="session-check-btn">Session Check (none, iframe)</button>
+      <button id="session-check-no-redirect-btn">Session Check (none, no redirect)</button>
       <button id="session-check-id-token-btn">Session Check (id_token)</button>
       <a href="/ping-one/">Start Over</a>
     </div>

e2e/oidc-app/src/utils/oidc-app.ts

@@ -218,7 +218,16 @@ export async function oidcApp({
     const result = await oidcClient.user?.session();
     const appEl = document.getElementById('app');
     const el = document.createElement('div');
-    el.innerHTML = `<p><strong>Session Check (none):</strong></p><pre id="session-check-result">${JSON.stringify(result, null, 2)}</pre>`;
+    el.innerHTML = `<p><strong>Session Check (none, iframe):</strong></p><pre id="session-check-result">${JSON.stringify(result, null, 2)}</pre>`;
+    appEl?.appendChild(el);
+  });
+
+  document.getElementById('session-check-no-redirect-btn')?.addEventListener('click', async () => {
+    const options: SessionCheckOptions = { redirectUri: '' };
+    const result = await oidcClient.user?.session(options);
+    const appEl = document.getElementById('app');
+    const el = document.createElement('div');
+    el.innerHTML = `<p><strong>Session Check (none, no redirect):</strong></p><pre id="session-check-no-redirect-result">${JSON.stringify(result, null, 2)}</pre>`;
     appEl?.appendChild(el);
   });
 

packages/oidc-client/README.md

@@ -180,6 +180,53 @@ Logs out the user by revoking tokens and clearing the storage. Uses the end sess
 const logoutResponse = await oidcClient.user.logout();
 ```
 
+#### `user.session(options?)`
+
+Checks whether the user has an active session at the AS without prompting for login (`prompt=none`).
+
+- **Parameters**: `SessionCheckOptions` (optional)
+- **Returns**: `Promise<SessionCheckSuccess | GenericError>`
+
+```js
+const session = await oidcClient.user.session();
+if ('error' in session) {
+  // No active session
+}
+```
+
+##### `responseType: 'none'` (default)
+
+Use when you only need to know if a session is alive — no claims are returned.
+
+Requires a stored `id_token` to send as `id_token_hint`. Fails immediately with `no_id_token_hint` if storage is empty.
+
+How the check runs depends on `redirectUri`:
+
+- **With `redirectUri`** (iframe): a hidden iframe loads the authorization URL. The AS redirects to `redirectUri` on success or appends error params on failure. The `redirectUri` must be same-origin — the browser blocks cross-origin iframe content access.
+- **Without `redirectUri`** (fetch): a plain GET to the authorization endpoint — no iframe. The AS returns `204` on success or `400` on failure. Use this when no same-origin callback page is available.
+
+Returns `{ mode: 'none' }` on success.
+
+##### `responseType: 'id_token'`
+
+Use when you need the user's claims back from the session. The AS issues a fresh `id_token` whose decoded claims are returned on success.
+
+Always uses the iframe path — `redirectUri` is required. A stored `id_token` is sent as `id_token_hint` if available but is not required.
+
+`state` and `nonce` are validated before claims are returned. If `subject` is provided, the `sub` claim must also match — otherwise any active session's claims are returned.
+
+```js
+const session = await oidcClient.user.session({
+  responseType: 'id_token',
+  subject: knownUserId, // optional — omit to get claims for whoever is logged in
+});
+if (!('error' in session)) {
+  console.log(session.claims); // JWTPayload
+}
+```
+
+Returns `{ mode: 'id_token', claims: JWTPayload }` on success.
+
 ## Usage Examples
 
 ### Redirect-Based Login (`authorize.url()`)

packages/oidc-client/api-report/oidc-client.api.md

@@ -135,6 +135,11 @@ responseType: SessionCheckResponseType;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
 params: Record<string, string>;
 }, "oidc", unknown>;
+sessionCheckFetch: MutationDefinition<    {
+url: string;
+}, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
+status: 204;
+}, "oidc", unknown>;
 authorizeIframe: MutationDefinition<    {
 url: string;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, AuthorizationSuccess, "oidc", unknown>;
@@ -177,6 +182,11 @@ responseType: SessionCheckResponseType;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
 params: Record<string, string>;
 }, "oidc", unknown>;
+sessionCheckFetch: MutationDefinition<    {
+url: string;
+}, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
+status: 204;
+}, "oidc", unknown>;
 authorizeIframe: MutationDefinition<    {
 url: string;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, AuthorizationSuccess, "oidc", unknown>;

packages/oidc-client/api-report/oidc-client.types.api.md

@@ -135,6 +135,11 @@ responseType: SessionCheckResponseType;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
 params: Record<string, string>;
 }, "oidc", unknown>;
+sessionCheckFetch: MutationDefinition<    {
+url: string;
+}, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
+status: 204;
+}, "oidc", unknown>;
 authorizeIframe: MutationDefinition<    {
 url: string;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, AuthorizationSuccess, "oidc", unknown>;
@@ -177,6 +182,11 @@ responseType: SessionCheckResponseType;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
 params: Record<string, string>;
 }, "oidc", unknown>;
+sessionCheckFetch: MutationDefinition<    {
+url: string;
+}, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, {
+status: 204;
+}, "oidc", unknown>;
 authorizeIframe: MutationDefinition<    {
 url: string;
 }, BaseQueryFn<string | FetchArgs, unknown, FetchBaseQueryError, {}, FetchBaseQueryMeta>, never, AuthorizationSuccess, "oidc", unknown>;

packages/oidc-client/src/lib/client.store.test.ts

@@ -734,9 +734,8 @@ describe('user.session()', async () => {
     customStorage.remove(storageKey);
   });
 
-  it('returns a GenericError when no tokens are stored (best-effort: dispatch is attempted)', async () => {
-    // No tokens in storage — best-effort: id_token_hint is omitted, dispatch still runs.
-    // In Vitest (no real DOM), the iframe manager cannot run and surfaces a session_check_error.
+  it('returns a GenericError when no tokens are stored', async () => {
+    // response_type=none requires a stored id_token; failing before dispatch.
     const oidcClient = await oidc({ config, storage: customStorageConfig });
     if ('error' in oidcClient) throw new Error('Error creating OIDC Client');
 
@@ -745,8 +744,8 @@ describe('user.session()', async () => {
     if (!('error' in result)) {
       expect.fail('Expected SessionCheckError, got success');
     }
-    expect(result.error).toBe('session_check_error');
-    expect(result.type).toBe('network_error');
+    expect(result.error).toBe('no_id_token_hint');
+    expect(result.type).toBe('argument_error');
   });
 
   it('returns wellknown_error when authorization_endpoint is missing from the wellknown config', async () => {

packages/oidc-client/src/lib/oidc.api.ts

@@ -273,6 +273,74 @@ export const oidcApi = createApi({
         >;
       },
     }),
+    sessionCheckFetch: builder.mutation<{ status: 204 }, { url: string }>({
+      queryFn: async ({ url }, api, _, baseQuery) => {
+        const { requestMiddleware, logger } = api.extra as Extras;
+
+        const request: FetchArgs = {
+          url,
+          method: 'GET',
+          credentials: 'include',
+          headers: {
+            Accept: 'application/json',
+          },
+        };
+
+        logger.debug('OIDC session check fetch request', request);
+
+        const response = await initQuery(request, 'authorize')
+          .applyMiddleware(requestMiddleware)
+          .applyQuery(async (req: FetchArgs) => await baseQuery(req));
+
+        if (response.error) {
+          const responseError = response.error;
+          const isNetworkError = typeof responseError.status === 'string';
+          const errorData = responseError.data;
+          const message =
+            !isNetworkError &&
+            errorData &&
+            typeof errorData === 'object' &&
+            'error_description' in errorData &&
+            typeof errorData.error_description === 'string'
+              ? errorData.error_description
+              : 'The request requires login.';
+
+          logger.error('Error in session check fetch', responseError);
+
+          return {
+            error: {
+              status: 400,
+              statusText: 'SESSION_CHECK_ERROR',
+              data: {
+                error: isNetworkError ? 'session_check_error' : 'login_required',
+                message,
+                type: isNetworkError ? 'network_error' : 'auth_error',
+              } satisfies GenericError,
+            } as FetchBaseQueryError,
+          };
+        }
+
+        if (response.meta?.response?.status !== 204) {
+          logger.error('Unexpected status in session check fetch', {
+            status: response.meta?.response?.status,
+          });
+          return {
+            error: {
+              status: 'CUSTOM_ERROR',
+              error: 'SESSION_CHECK_ERROR',
+              data: {
+                error: 'session_check_error',
+                message: `Unexpected response status: ${response.meta?.response?.status}`,
+                type: 'network_error',
+              } satisfies GenericError,
+            } as FetchBaseQueryError,
+          };
+        }
+
+        logger.debug('OIDC session check fetch response', response);
+        return { data: { status: 204 } };
+      },
+    }),
     authorizeIframe: builder.mutation<AuthorizationSuccess, { url: string }>({
       queryFn: async ({ url }, api) => {
         const { requestMiddleware, logger } = api.extra as Extras;