Skip to content

Add the Wayfinder Enterprise B2B sample - #25

Merged
AnuradhaSK merged 1 commit into
thunder-id:mainfrom
AnuradhaSK:add-wayfinder-enterprise-sample
Nov 13, 2026
Merged

AnuradhaSK merged 1 commit into
thunder-id:mainfrom
AnuradhaSK:add-wayfinder-enterprise-sample

Conversation

@AnuradhaSK

@AnuradhaSK AnuradhaSK commented Nov 12, 2026 •

Copy link
Copy Markdown
Contributor

Purpose

Adds the first B2B sample, Wayfinder Enterprise: a Next.js travel management app where every customer company is an organization unit (OU) in ThunderID. The app, its roles and its sign-in flow are defined once in a root OU and shared with every company, so a company can use the app as soon as it registers.

The sample shows how to:

  • Let a company sign itself up. A registration flow creates the company OU and the first admin in it, assigns Wayfinder Admin, and signs the admin in to the app.
  • Sign in with a password or the company's identity provider. For enterprise SSO, the user enters the organization handle. The flow finds the company and uses the connection in the company's own enterpriseIdp flow variable. On their first sign-in, employees are added to the company as members.
  • Let company admins run their own company. Admins manage users, groups and role assignments, add an OpenID Connect identity provider, and choose it for enterprise SSO. All of this uses @thunderid/nextjs components.
  • Brand the sign-in screens with a theme and layout assigned to the application.
  • Set up everything declaratively. Two files under thunderid-config/ create every ThunderID resource the app needs, with fixed IDs.

It also adds a b2b area to the repository:

  • A B2B section and index row in the root README, and an area row in AGENTS.md.
  • A B2B SAMPLE badge in the sample-banner skill, and the sample's banner.
  • A sample_b2b_wayfinder_enterprise input in the release workflow.

The PR builder finds the sample through its package.json, so it is built and linted without any workflow change.

Screenshots

Landing Sign-in (ThunderID, Wayfinder theme)
01-landing Screenshot 2026-11-13 at 08 35 08
Admin: flight booking Admin: travel policy
03-admin-flight-booking 04-travel-policy
Team: users Team: roles
05-team-users 06-team-roles
Enterprise SSO Member: flight booking
07-enterprise-sso 08-member-flight-booking

Approach

Resource model. The Wayfinder Enterprise root OU owns the application, the backend client, both roles, both flows and the user type. The application, the two roles and the sign-in flow have a sharing policy for every child OU. Each company is a child OU and holds only its own users, groups and identity provider.

Choosing the company at sign-in. The app is shared with every company, so a sign-in has to settle on one company before ThunderID issues a token:

  • Enterprise SSO: an OUResolverExecutor finds the company from the handle before the user authenticates.
  • Password sign-in and new company admins: a second OUResolverExecutor (directChildrenOnly) runs after authentication. It picks the user's company, and asks the user to choose when they belong to more than one.

Security design.

User tokens are issued for the app's own resource server (urn:wayfinder-enterprise:api) and carry only Wayfinder permissions. They are never sent to the ThunderID management API. This keeps the app working when server.security.rest.audience is enabled. For the same reason, the SDK reads the user profile from the ID token (fetchUserProfile: false).

The admin components call the app's /api/admin/[...path] route, which:

  1. Verifies the caller's token and checks the Wayfinder permission for the call: view to read and manage to change, on user, group, role or sso. Only Wayfinder Admin has these permissions.
  2. Allows only the calls the admin pages make.
  3. Replaces the OU in every request with the caller's ouId.
  4. Forwards the call with a token of the shared Wayfinder Enterprise Backend client, issued for the caller's company. The token comes from POST /ou/{ouId}/oauth2/token (client_credentials) and is cached per company.

The route exists because roles, connections, flows and flow variables have no OU-scoped permission today. Managing them needs the root system permission, which company admins must not hold. If OU-scoped permissions for these resources are added later, the route can be made smaller.

Two import files. The Console tests an import before running it. That test does not create organization units, but it still looks up the organization unit that resource servers, roles and flows are placed in. So organization-unit.yaml has to be imported first, on its own.

Other choices.

  • Packaging: like the other samples, it uses npm with a lockfile and pins the published @thunderid/nextjs 1.18.1.
  • Storage: bookings and travel policies are kept in data/wayfinder.json, so no database is needed. The README notes that two changes made at the same moment can overwrite each other.
  • Server version: the sample needs ThunderID 2.0.0-m1 or later, for flow sharing, per-organization flow variables and the organization token endpoint.

Related Issues

  • N/A

Related PRs

  • N/A

Checklist

  • Followed the contribution guidelines.
  • Manual test round performed and verified.
  • Documentation provided. (b2b/wayfinder-enterprise/README.md)
  • Tests provided. (Add links if there are any)
    • Unit Tests
    • Integration Tests
  • Breaking changes. (Fill if applicable)
    • Breaking changes section filled.
    • breaking change label added.

Security checks

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

The sample ships placeholder client secrets for a local setup (wayfinder-enterprise-secret and wayfinder-enterprise-backend-secret in thunderid-config/thunderid.env and .env.example). They are not real credentials, and the README explains how to change them before importing.

🤖 Generated with Claude Code

@AnuradhaSK AnuradhaSK mentioned this pull request Nov 12, 2026
5 of 12 tasks
@AnuradhaSK
AnuradhaSK force-pushed the add-wayfinder-enterprise-sample branch 5 times, most recently from 01dc4f1 to 5d3b905 Compare November 13, 2026 02:35
Moves the sample from the ThunderID repository into a new b2b area, switches
it to npm and the published @thunderid/nextjs release, and adds its banner,
README index row and release workflow input.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Signed-off-by: AnuradhaSK <anuradha199528@gmail.com>
@AnuradhaSK
AnuradhaSK force-pushed the add-wayfinder-enterprise-sample branch from 5d3b905 to eb22ec4 Compare November 13, 2026 03:06
@AnuradhaSK
AnuradhaSK merged commit 5f4840a into thunder-id:main Nov 13, 2026
19 checks passed
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.

2 participants