Skip to content

Switch organization units with the device secret in the Next.js and Nuxt SDKs - #180

Merged
AnuradhaSK merged 1 commit into
thunder-id:mainfrom
AnuradhaSK:nextjs-device-secret-switch
Nov 14, 2026
Merged

AnuradhaSK merged 1 commit into
thunder-id:mainfrom
AnuradhaSK:nextjs-device-secret-switch

Conversation

@AnuradhaSK

@AnuradhaSK AnuradhaSK commented Nov 14, 2026 •

Copy link
Copy Markdown
Contributor

Purpose

In a Next.js or Nuxt app, OrganizationUnitSwitcher switches by sending the browser to {baseUrl}/ou/{ouId}/oauth2/authorize and back to the app. The SSO session spares the user a password, but the page still leaves the app on every switch.

PR #160 added a back-channel switch to the browser SDK: a sign-in that asks for the device_sso scope returns a device secret, and exchanging it at the unit's token endpoint gets the unit's tokens without a redirect. The exchange itself lives in the core client and supports confidential clients, but only the browser client used it. This PR uses it on the Next.js and Nuxt servers, where the device secret stays in the server-side session store and never reaches the browser.

Approach

@thunderid/node

  • ThunderIDNodeClient.switchOrganizationUnitWithDeviceSecret(organizationUnitId, sessionId) is now public. It runs the core exchange for the session and, on success, indexes the session for back-channel logout, as the redirect switch's callback does.

@thunderid/javascript

  • The browser client's lists of errors that send a switch on to a sign-in (INTERACTION_ERRORS, UNUSABLE_DEVICE_SECRET_ERRORS) move to the core as OrganizationUnitSwitchFallbackErrors, which the browser client, the Next.js action and the Nuxt helper all read.

@thunderid/nextjs

  • In redirect mode, switchOrganizationUnitAction tries the device secret first.
    • On success, it rewrites the session cookie with the unit's tokens and returns {switched: true}. The provider already handles that result (it rereads the user and the current unit and refreshes the router), so it needs no change.
    • With no device secret, or on an interaction error or an unusable device secret, it falls back to the redirect, as before. redirect: false still fails with interaction_required.
    • unauthorized_client fails with UnauthorizedClient, and any other error with Failed, keeping the session.
  • The code that builds the session cookie from a token response moves out of handleOAuthCallbackAction into utils/setSessionCookie.ts, so the callback and the switch share it. The callback's behaviour is unchanged.

@thunderid/nuxt

  • New route POST /api/auth/switch (NuxtAPIRoutes.SWITCH). It follows the ouSwitch contract the browser SDK's backend mode already defines: the unit in the query and in a {"ouId"} body, the new state on success, and an OAuth error on a refusal.
    • On success, it rewrites the session cookie with issueSessionCookie and answers with the new auth state, including the organization unit.
    • No session answers 401 with login_required. No device secret answers 400 with interaction_required. A token endpoint error is passed on with 400, and a failed request answers 502 with server_error. The session stays as it was in each case.
  • switchOrganizationUnit in the plugin calls the route through utils/switchOrganizationUnitOnServer.ts.
    • On success, it replaces the auth state and calls refreshNuxtData(), so pages that fetch session data reload it, and resolves with the user.
    • When the user has to sign in, it falls back to the sign-in route bounded to the unit, as before. With redirect: false it fails with InteractionRequired instead.
    • unauthorized_client fails with UnauthorizedClient, and any other refusal with Failed.
  • OrganizationUnitSwitcher marks the new unit after a switch that stays on the page, and ends its busy state on success as well as on failure, as the Vue SDK's switcher does.

To get the in-place switch, an app adds device_sso to its scopes, and its ThunderID application allows the urn:ietf:params:oauth:grant-type:token-exchange grant. Apps that don't keep the redirect switch.

The SDK development specification still lists organization operations as a future target, so this PR, like #160, adds no specification text.

Related Issues

  • N/A

Related PRs

Checklist

  • Followed the contribution guidelines.
  • Manual test round performed and verified.
    • Against ThunderID 2.0.0-m1 with the Next.js B2B quickstart's import, the token exchange grant added to its confidential application, and device_sso added to the apps' scopes. A user shared into three companies signed in to Initech, then switched to Umbrella and to Globex from OrganizationUnitSwitcher.
    • Next.js (the B2B quickstart): each switch stayed on http://localhost:3000 with no navigation to ThunderID and no password prompt.
    • Nuxt (a minimal app with OrganizationUnitSwitcher and a server route that reads the session's access token): each switch made no navigation at all.
    • In both, the token read on the server showed the new company and roles (Member without org in Umbrella, Admin with org in Globex).
    • Nuxt without device_sso: the switch went through ThunderID's sign-in and back, with no password prompt, and landed in Umbrella.
    • In both, signing out after a switch cleared the ThunderID session cookie, and the next sign-in asked for the password.
  • Documentation provided. (Add links if there are any)
  • Tests provided. (Add links if there are any)
    • Unit Tests
      • packages/node/src/__tests__/ThunderIDNodeClient.organizationUnit.test.ts: exchange at the unit token endpoint with client authentication, tokens replaced, device secret kept, session indexed; no device secret; a refused secret dropped with the session kept.
      • packages/nextjs/src/server/actions/auth/__tests__/switchOrganizationUnitAction.test.ts: in-place switch with the cookie rewritten; fallback on interaction_required, login_required, invalid_grant and invalid_request; redirect: false; unauthorized_client and other errors; a failed request.
      • packages/nextjs/src/utils/__tests__/setSessionCookie.test.ts
      • packages/nuxt/tests/unit/switch-post.test.ts: in-place switch with the cookie rewritten and the new state returned; the unit from the body; a missing unit; no session; no device secret; a token endpoint error; a failed request.
      • packages/nuxt/tests/unit/switch-organization-unit-on-server.test.ts: the new state; a sign-in on each fallback error and on 401; UnauthorizedClient and Failed.
      • packages/nuxt/tests/unit/organization-unit-switcher.test.ts: the new unit marked and the busy state ended, on success and on failure.
    • Integration Tests
  • Breaking changes. (Fill if applicable)
    • Breaking changes section filled.
    • breaking change label added.
  • Cross-SDK parity. Exactly one of parity/prs-raised or parity/prs-not-needed added.
    • If parity/prs-raised, the port links are posted as a reply on the parity check's comment.

SDK parity

  • ios-sdks: not needed, switchOrganizationUnit(_:options:) already exchanges the device secret before falling back to the browser
  • android-sdks: not needed, switchOrganizationUnit already exchanges the device secret before falling back to the browser
  • flutter-sdks: not applicable, the SDK has no organization unit switch yet, so there is no redirect switch to back with a device secret

Within this repository, @thunderid/express has no organization unit switch, so there is nothing to back with a device secret there.

Security checks

  • Followed secure coding standards.
  • Confirmed that this PR doesn't commit any keys, passwords, tokens, usernames, or other secrets.

The device secret stays in the server's session store: the Next.js and Nuxt SDKs both use the Node client's in-memory MemoryCacheStore, keyed by the session ID. It is not added to either session cookie, which carry the access and refresh tokens as before (HttpOnly and signed). The exchange authenticates with the client secret.

The store is per process. After a restart, or when a switch reaches another instance than the one that handled the sign-in, the session holds no device secret and the switch falls back to the redirect. Nuxt rebuilds a session from its cookie after a restart, and a rebuilt session has no device secret for the same reason.

🤖 Generated with Claude Code

@coderabbitai

coderabbitai Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

Important

  • Trigger review

This repository does not receive automatic reviews because it has fewer than 10 stars.

Run configuration

  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

Share

@github-actions

github-actions Bot commented Nov 14, 2026 •

Copy link
Copy Markdown

🔀 Cross-SDK feature parity, no ports needed

This pull request is labelled parity/prs-not-needed: nothing here has to ship in the other ThunderID SDKs. If that changes, swap the label for parity/prs-raised.

@AnuradhaSK AnuradhaSK added the parity/prs-not-needed Nothing here reaches another SDK label Nov 14, 2026
brionmario
brionmario previously approved these changes Nov 14, 2026
@AnuradhaSK AnuradhaSK changed the title Switch organization units with the device secret in the Next.js SDK Switch organization units with the device secret in the Next.js and Nuxt SDKs Nov 14, 2026
…uxt SDKs

Next.js and Nuxt apps switched organization units only by redirecting the
browser to the unit's sign-in and back. When the session holds a device
secret, the server now exchanges it at the unit's token endpoint, rewrites
the session cookie, and completes the switch without leaving the page. Both
fall back to the redirect when there is no device secret, or when the server
needs the user or cannot use the secret.

Signed-off-by: AnuradhaSK <anuradha199528@gmail.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: AnuradhaSK <anuradha199528@gmail.com>
@AnuradhaSK
AnuradhaSK merged commit 38ed2d7 into thunder-id:main Nov 14, 2026
7 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

parity/prs-not-needed Nothing here reaches another SDK

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants