From 5bbc7900cb4aefae16e11200292d2a39773717fa Mon Sep 17 00:00:00 2001 From: AnuradhaSK Date: Sat, 14 Nov 2026 00:32:22 +0530 Subject: [PATCH] Improve the B2B quickstarts Signed-off-by: AnuradhaSK --- README.md | 4 +- b2b/wayfinder-enterprise/.env.example | 12 ++-- b2b/wayfinder-enterprise/README.md | 15 ++--- .../thunderid-config/thunderid.env | 7 ++- quickstarts/nextjs-b2b/.env.example | 12 ++-- quickstarts/nextjs-b2b/README.md | 60 +++++++++--------- quickstarts/nextjs-b2b/app/page.tsx | 2 +- quickstarts/nextjs-b2b/package-lock.json | 32 +++++----- quickstarts/nextjs-b2b/package.json | 2 +- .../thunderid-config/organization-unit.yaml | 10 --- .../thunderid-config/thunderid-config.yaml | 51 ++++++++------- .../nextjs-b2b/thunderid-config/thunderid.env | 6 +- quickstarts/react-b2b/README.md | 63 ++++++++++--------- quickstarts/react-b2b/package-lock.json | 38 ++++------- quickstarts/react-b2b/package.json | 3 +- quickstarts/react-b2b/src/App.jsx | 14 +---- quickstarts/react-b2b/src/components/Nav.jsx | 3 +- quickstarts/react-b2b/src/main.jsx | 4 +- .../thunderid-config/organization-unit.yaml | 10 --- .../thunderid-config/thunderid-config.yaml | 57 +++++++++-------- quickstarts/react-b2b/vite.config.js | 5 +- 21 files changed, 191 insertions(+), 219 deletions(-) delete mode 100644 quickstarts/nextjs-b2b/thunderid-config/organization-unit.yaml delete mode 100644 quickstarts/react-b2b/thunderid-config/organization-unit.yaml diff --git a/README.md b/README.md index cdb6f13..7ddf3ae 100644 --- a/README.md +++ b/README.md @@ -16,11 +16,11 @@ The minimal app per platform that the [ThunderID docs](https://thunderid.dev) qu | [`flutter`](quickstarts/flutter) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/flutter/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fflutter&expanded=true) | Flutter app using the [`thunderid_flutter`](https://pub.dev/packages/thunderid_flutter) package | | [`ios`](quickstarts/ios) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/ios/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fios&expanded=true) | iOS (SwiftUI) app using the [ThunderID iOS SDK](https://github.com/thunder-id/ios-sdks) | | [`nextjs`](quickstarts/nextjs) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/nextjs/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnextjs&expanded=true) | Next.js app using `@thunderid/nextjs` | -| [`nextjs-b2b`](quickstarts/nextjs-b2b) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/nextjs-b2b/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnextjs-b2b&expanded=true) | B2B Next.js app using `@thunderid/nextjs`: company sign-up, organization switching and per-company enterprise SSO | +| [`nextjs-b2b`](quickstarts/nextjs-b2b) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/nextjs-b2b/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnextjs-b2b&expanded=true) | B2B Next.js app using `@thunderid/nextjs` | | [`node`](quickstarts/node) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/node/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnode&expanded=true) | Node.js service using `@thunderid/node` for machine-to-machine access | | [`nuxt`](quickstarts/nuxt) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/nuxt/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fnuxt&expanded=true) | Nuxt app using `@thunderid/nuxt` | | [`react`](quickstarts/react) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/react/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Freact&expanded=true) | React app using `@thunderid/react` | -| [`react-b2b`](quickstarts/react-b2b) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/react-b2b/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Freact-b2b&expanded=true) | B2B React app using `@thunderid/react`: company sign-up, organization switching and per-company enterprise SSO | +| [`react-b2b`](quickstarts/react-b2b) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/react-b2b/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Freact-b2b&expanded=true) | B2B React app using `@thunderid/react` | | [`vue`](quickstarts/vue) | [![release](https://img.shields.io/github/v/release/thunder-id/samples?filter=sample/quickstarts/vue/*)](https://github.com/thunder-id/samples/releases?q=sample%2Fquickstarts%2Fvue&expanded=true) | Vue app using `@thunderid/vue` | ### Integrations diff --git a/b2b/wayfinder-enterprise/.env.example b/b2b/wayfinder-enterprise/.env.example index d79b865..62687c7 100644 --- a/b2b/wayfinder-enterprise/.env.example +++ b/b2b/wayfinder-enterprise/.env.example @@ -1,16 +1,17 @@ ## Copy this file to .env.local. Values without NEXT_PUBLIC_ are read only on the server. -# The ThunderID server, and the application the declarative import creates. +# The ThunderID server, and the application the declarative import creates. Set THUNDERID_CLIENT_SECRET +# to the value you set as WAYFINDER_ENTERPRISE_CLIENT_SECRET when you imported thunderid.env. NEXT_PUBLIC_THUNDERID_BASE_URL=https://localhost:8090 NEXT_PUBLIC_THUNDERID_CLIENT_ID=WAYFINDER_ENTERPRISE -THUNDERID_CLIENT_SECRET=wayfinder-enterprise-secret +THUNDERID_CLIENT_SECRET= NEXT_PUBLIC_THUNDERID_APPLICATION_ID=019f0a10-0000-7000-8000-000000000031 NEXT_PUBLIC_THUNDERID_AFTER_SIGN_IN_URL=http://localhost:3000 NEXT_PUBLIC_THUNDERID_AFTER_SIGN_OUT_URL=http://localhost:3000 NEXT_PUBLIC_THUNDERID_SCOPES=openid profile email roles ou booking:view booking:create booking:manage policy:view policy:manage user:view user:manage group:view group:manage role:view role:manage sso:view sso:manage # Encrypts the session cookie. Generate it with `openssl rand -base64 32`. -THUNDERID_SECRET=replace-with-a-long-random-string +THUNDERID_SECRET= # Where the app runs. The admin components reach the backend routes under /api/admin from here. WAYFINDER_APP_URL=http://localhost:3000 @@ -27,7 +28,8 @@ WAYFINDER_USER_TYPE=wayfinder-user # The backend client that calls the root-only management APIs on a company admin's behalf, and the # resource server that holds the root "system" permission. The app gets the client's token at the -# admin's company's token endpoint (/ou/{ouId}/oauth2/token), so each token names that company. +# admin's company's token endpoint (/ou/{ouId}/oauth2/token), so each token names that company. Set +# WAYFINDER_BACKEND_CLIENT_SECRET to the value you set as WAYFINDER_ENTERPRISE_BACKEND_CLIENT_SECRET. WAYFINDER_BACKEND_CLIENT_ID=WAYFINDER_ENTERPRISE_BACKEND -WAYFINDER_BACKEND_CLIENT_SECRET=wayfinder-enterprise-backend-secret +WAYFINDER_BACKEND_CLIENT_SECRET= THUNDERID_SYSTEM_RESOURCE=https://localhost:8090/mcp diff --git a/b2b/wayfinder-enterprise/README.md b/b2b/wayfinder-enterprise/README.md index 59e93e7..3bc6751 100644 --- a/b2b/wayfinder-enterprise/README.md +++ b/b2b/wayfinder-enterprise/README.md @@ -44,10 +44,11 @@ cd my-app The `thunderid-config/` directory holds two importable files that create every resource the app needs, with fixed IDs so the app's configuration works unchanged. Import them through the ThunderID Console, in this order: -1. Sign in to the ThunderID Console. With the quickstart image it is the Control Plane console, `https://localhost:8095/console`. -2. Choose **Import / Export**, then **Import**. -3. Upload `thunderid-config/organization-unit.yaml` as the configuration file. It needs no environment file. Choose **Continue**, and once the import test passes, choose **Import configuration**. -4. Choose **Import / Export**, then **Import** again. Upload `thunderid-config/thunderid-config.yaml` as the configuration file and `thunderid-config/thunderid.env` as the environment variables file. Choose **Continue**, then **Import configuration**. +1. Generate a client secret for each of the two applications, for example with `openssl rand -base64 32`, and set them as `WAYFINDER_ENTERPRISE_CLIENT_SECRET` and `WAYFINDER_ENTERPRISE_BACKEND_CLIENT_SECRET` in `thunderid-config/thunderid.env`. The sample ships without them, and the Console does not import the file until both are set. You can also enter them in the Console's **Environment variables** editor during the import. Keep the values for the app's `.env.local`. +2. Sign in to the ThunderID Console. With the quickstart image it is the Control Plane console, `https://localhost:8095/console`. +3. Choose **Import / Export**, then **Import**. +4. Upload `thunderid-config/organization-unit.yaml` as the configuration file. It needs no environment file. Choose **Continue**, and once the import test passes, choose **Import configuration**. +5. Choose **Import / Export**, then **Import** again. Upload `thunderid-config/thunderid-config.yaml` as the configuration file and `thunderid-config/thunderid.env` as the environment variables file. Choose **Continue**, then **Import configuration**. The Console tests each import before it runs it, and that test only finds an organization unit that already exists. The second file places every resource in the organization unit the first one creates, so import the first one on its own. @@ -73,7 +74,7 @@ The bundle sets the `defaultResourceServer` server config. An import replaces th #### Environment variables in `thunderid-config/thunderid.env` -The defaults work as they are for a local setup. +The other defaults work as they are for a local setup. The two client secrets are empty in the sample, so set your own. | Variable | Description | |---|---| @@ -84,7 +85,7 @@ The defaults work as they are for a local setup. | `WAYFINDER_ENTERPRISE_BACKEND_CLIENT_ID` | Client ID of the `Wayfinder Enterprise Backend` application | | `WAYFINDER_ENTERPRISE_BACKEND_CLIENT_SECRET` | Client secret of the `Wayfinder Enterprise Backend` application | -Change a client secret here before you import, and set the same value in the app's `.env.local`. +Set the same client secrets in the app's `.env.local`, as `THUNDERID_CLIENT_SECRET` and `WAYFINDER_BACKEND_CLIENT_SECRET`. ### Configure the app @@ -94,7 +95,7 @@ Create your `.env.local`: cp .env.example .env.local ``` -The defaults match the import. Set `THUNDERID_SECRET` in `.env.local` to a long random string; the SDK encrypts the session cookie with it. Generate one with: +The other defaults match the import. In `.env.local`, set `THUNDERID_CLIENT_SECRET` and `WAYFINDER_BACKEND_CLIENT_SECRET` to the client secrets you set in `thunderid.env`, and `THUNDERID_SECRET` to a long random string; the SDK encrypts the session cookie with it. Generate one with: ```bash openssl rand -base64 32 diff --git a/b2b/wayfinder-enterprise/thunderid-config/thunderid.env b/b2b/wayfinder-enterprise/thunderid-config/thunderid.env index 3f178c5..b2d0320 100644 --- a/b2b/wayfinder-enterprise/thunderid-config/thunderid.env +++ b/b2b/wayfinder-enterprise/thunderid-config/thunderid.env @@ -1,6 +1,9 @@ +# Client secrets of the two applications. The sample ships without them: generate a value for each, +# for example with `openssl rand -base64 32`, and set the same values in the app's .env.local as +# THUNDERID_CLIENT_SECRET and WAYFINDER_BACKEND_CLIENT_SECRET. WAYFINDER_ENTERPRISE_CLIENT_ID=WAYFINDER_ENTERPRISE -WAYFINDER_ENTERPRISE_CLIENT_SECRET=wayfinder-enterprise-secret +WAYFINDER_ENTERPRISE_CLIENT_SECRET= WAYFINDER_ENTERPRISE_REDIRECT_URIS=["http://localhost:3000"] WAYFINDER_ENTERPRISE_POST_LOGOUT_REDIRECT_URIS=["http://localhost:3000"] WAYFINDER_ENTERPRISE_BACKEND_CLIENT_ID=WAYFINDER_ENTERPRISE_BACKEND -WAYFINDER_ENTERPRISE_BACKEND_CLIENT_SECRET=wayfinder-enterprise-backend-secret +WAYFINDER_ENTERPRISE_BACKEND_CLIENT_SECRET= diff --git a/quickstarts/nextjs-b2b/.env.example b/quickstarts/nextjs-b2b/.env.example index 797507f..2500611 100644 --- a/quickstarts/nextjs-b2b/.env.example +++ b/quickstarts/nextjs-b2b/.env.example @@ -1,9 +1,10 @@ # Base URL of your ThunderID server. NEXT_PUBLIC_THUNDERID_BASE_URL=https://localhost:8090 -# Credentials of the application the import creates. Match thunderid-config/thunderid.env. +# Credentials of the application the import creates. Set THUNDERID_CLIENT_SECRET to the client secret +# you set as NEXTJS_B2B_CLIENT_SECRET when you imported thunderid-config/thunderid.env. NEXT_PUBLIC_THUNDERID_CLIENT_ID=NEXTJS_B2B_QUICKSTART -THUNDERID_CLIENT_SECRET=nextjs-b2b-quickstart-secret +THUNDERID_CLIENT_SECRET= # Where ThunderID returns the browser after sign-in. NEXT_PUBLIC_THUNDERID_AFTER_SIGN_IN_URL=http://localhost:3000 @@ -13,13 +14,14 @@ NEXT_PUBLIC_THUNDERID_AFTER_SIGN_OUT_URL=http://localhost:3000 # `ou` and `roles` put the company and the user's roles there into the tokens. `org` asks for the # permission a company admin needs to manage their company, such as its identity provider. -NEXT_PUBLIC_THUNDERID_SCOPES=openid profile email roles ou org +# `device_sso` asks for a device secret, which lets the server switch companies without a redirect. +NEXT_PUBLIC_THUNDERID_SCOPES=openid profile email roles ou org device_sso # ID of the sign-in flow the import creates. A company admin sets the flow's enterpriseIdp variable for their company. NEXT_PUBLIC_THUNDERID_SIGN_IN_FLOW_ID=019f0b20-0000-7000-8000-000000000021 -# Encrypts the session cookie. Generate it with `openssl rand -base64 32`. -THUNDERID_SECRET=replace-with-a-long-random-string +# Signs the session cookie. Generate it with `openssl rand -base64 32`. +THUNDERID_SECRET= # DANGER: Disables ALL TLS verification. Only for local development with self-signed certs. NEVER use in production. NODE_TLS_REJECT_UNAUTHORIZED=0 diff --git a/quickstarts/nextjs-b2b/README.md b/quickstarts/nextjs-b2b/README.md index 5f70219..5b942eb 100644 --- a/quickstarts/nextjs-b2b/README.md +++ b/quickstarts/nextjs-b2b/README.md @@ -2,12 +2,12 @@ # ThunderID Next.js B2B Quickstart -A Next.js App Router app for a B2B SaaS product, built with the [ThunderID Next.js SDK](https://www.npmjs.com/package/@thunderid/nextjs) (`@thunderid/nextjs`). Each company that signs up becomes its own organization in ThunderID. People sign in to one company at a time, their tokens name that company and the roles they hold there, and a company admin plugs in the company's own identity provider. Tokens stay on the server. +A Next.js App Router app for a B2B SaaS product, built with the [ThunderID Next.js SDK](https://www.npmjs.com/package/@thunderid/nextjs) (`@thunderid/nextjs`). | What it shows | How | |---|---| | Company sign-up | The sign-in page offers **Register your company**. It creates the company as an organization unit, creates the first admin and signs them in. | -| Account inside the company, or shared | Sign-up asks where the account lives. **My account belongs to this company** creates it inside the company. **I work with several companies** creates it in the platform organization and shares it into the company, so it can join more companies later. | +| Account inside the company, or shared | Sign-up asks where the account lives. **My account belongs to this company** creates it inside the company. **I work with several companies** creates it in the Default organization unit and shares it into the company, so it can join more companies later. | | Organization and roles in the token | The page reads the access token on the server and shows its `ouId`, `ouHandle`, `ouName`, `roles` and `scope`. | | Switching companies | `OrganizationUnitSwitcher` lists the companies the account belongs to. See [Switching companies](#switching-companies). | | Enterprise SSO per company | A company admin adds an OpenID Connect identity provider through the SDK's management fetcher, and selects it with `FlowVariablesForm`. Employees then choose **Sign in with enterprise SSO** and enter the company's handle. | @@ -30,33 +30,31 @@ cd my-app ### Import the ThunderID resources -`thunderid-config/` holds two files that create everything the app needs, with fixed IDs so the app's configuration works unchanged. Import them in the ThunderID Console, in this order: +`thunderid-config/thunderid-config.yaml` creates everything the app needs in the Default organization unit, with fixed IDs so the app's configuration works unchanged. Every company that signs up becomes a child of the Default organization unit. Import it in the ThunderID Console: -1. Sign in to the Console. With the quickstart image it is the Control Plane console, `https://localhost:8095/console`. -2. On the **welcome screen** (shown on first sign-in, or from the user profile menu), choose **Open** and upload `thunderid-config/organization-unit.yaml`. It needs no environment file. -3. Open the welcome screen again, upload `thunderid-config/thunderid-config.yaml`, then `thunderid-config/thunderid.env` for its variables. - -The Console tests each import before it runs it, and that test only finds an organization unit that already exists. The second file places every resource in the organization unit the first one creates, so import the first one on its own. +1. Generate a client secret for the application, for example with `openssl rand -base64 32`, and set it as `NEXTJS_B2B_CLIENT_SECRET` in `thunderid-config/thunderid.env`. The sample ships without one, and the Console does not import the file until it is set. You can also enter it in the Console's **Environment variables** editor during the import. Keep the value for the app's `.env`. +2. Sign in to the Console. With the quickstart image it is the Control Plane console, `https://localhost:8095/console`. +3. Choose **Import / Export**, then **Import**. Upload `thunderid-config/thunderid-config.yaml` as the configuration file and `thunderid-config/thunderid.env` as the environment variables file. +4. Choose **Continue**, then **Import configuration**. | Resource | Name | What it does | |---|---|---| -| Organization unit | Next.js B2B Quickstart (`nextjs-b2b-quickstart`) | The platform organization, a root organization unit in the Default project. Every company that signs up becomes its child. | | User type | Next.js B2B User (`nextjs-b2b-user`) | The account schema, with self-registration on. Usable in every company. | | Server config | `defaultResourceServer` | Makes the System resource server the default. The app names no resource when it signs in or switches, so its tokens are issued for the System resource server and an admin's token carries `org`. | -| Role | Admin | Grants the `org` permission, which manages the organization the token names. Shared with every company. | -| Role | Member | Grants no permission. Shared with every company. | +| Role | Next.js B2B Admin | Grants the `org` permission, which manages the organization the token names. The role is shared with every company. | +| Role | Next.js B2B Member | Grants no permission. The role is shared with every company. | | Flow | Next.js B2B Quickstart Company Sign-up | Creates the company and its first admin, with the account inside the company or shared into it | | Flow | Next.js B2B Quickstart Sign-in | Password, enterprise SSO, or company sign-up. Keeps a single sign-on session, so a switch does not ask for the password again. Shared with every company, which may set `enterpriseIdp`. | -| Application | Next.js B2B Quickstart | Confidential client with PKCE, redirecting to `http://localhost:3000`. Shared with every company. | +| Application | Next.js B2B Quickstart | Confidential client with PKCE, redirecting to `http://localhost:3000`. Allows the token exchange grant, so the app's server can switch companies with its device secret. The application is shared with every company. | -The imports create a root organization unit and replace the `defaultResourceServer` setting, and only the Control Plane writes those, so import there. Imported straight into a Data Plane, both are refused. +The import replaces the `defaultResourceServer` setting, which only the Control Plane writes, so import there. Imported straight into a Data Plane, it is refused. `thunderid.env` sets two variables: | Variable | Description | |---|---| | `NEXTJS_B2B_CLIENT_ID` | Client ID of the application. Defaults to `NEXTJS_B2B_QUICKSTART`. | -| `NEXTJS_B2B_CLIENT_SECRET` | Client secret of the application. Change it before you import, and set the same value in `.env`. | +| `NEXTJS_B2B_CLIENT_SECRET` | Client secret of the application. Empty in the sample: set your own before you import, and the same value as `THUNDERID_CLIENT_SECRET` in `.env`. | ### Configure the app @@ -64,7 +62,7 @@ The imports create a root organization unit and replace the `defaultResourceServ cp .env.example .env ``` -Set `THUNDERID_SECRET` to a long random string, for example from `openssl rand -base64 32`. The other defaults match the import. +Set `THUNDERID_CLIENT_SECRET` to the client secret you set as `NEXTJS_B2B_CLIENT_SECRET`, and `THUNDERID_SECRET` to a long random string, for example from `openssl rand -base64 32`. The other defaults match the import. | Variable | Description | |---|---| @@ -72,9 +70,9 @@ Set `THUNDERID_SECRET` to a long random string, for example from `openssl rand - | `NEXT_PUBLIC_THUNDERID_CLIENT_ID`, `THUNDERID_CLIENT_SECRET` | Credentials of the application | | `NEXT_PUBLIC_THUNDERID_AFTER_SIGN_IN_URL` | Where ThunderID returns the browser after sign-in | | `NEXT_PUBLIC_THUNDERID_AFTER_SIGN_OUT_URL` | Where ThunderID returns the browser after sign-out | -| `NEXT_PUBLIC_THUNDERID_SCOPES` | `ou` and `roles` put the company and the roles held there into the tokens. `org` asks for the permission a company admin needs. | +| `NEXT_PUBLIC_THUNDERID_SCOPES` | `ou` and `roles` put the company and the roles held there into the tokens. `org` asks for the permission a company admin needs. `device_sso` asks for a device secret, which the server uses to switch companies. | | `NEXT_PUBLIC_THUNDERID_SIGN_IN_FLOW_ID` | ID of the sign-in flow, whose `enterpriseIdp` variable a company admin sets | -| `THUNDERID_SECRET` | Encrypts the session cookie | +| `THUNDERID_SECRET` | Signs the session cookie | | `NODE_TLS_REJECT_UNAUTHORIZED` | Set to `0` in the example to accept a local server's self-signed certificate. Local development only. | ## Run @@ -92,33 +90,39 @@ Open [http://localhost:3000](http://localhost:3000). 1. Choose **Sign in**, then **Register your company** on the ThunderID sign-in page. 2. Choose **My account belongs to this company**. Enter a username, an email and a password, then `Northstar Labs` as the company name and `northstar` as its handle. -3. You land in the app, signed in to Northstar Labs. The access token names it in `ouId`, `ouHandle` and `ouName`, lists `Admin` in `roles`, and carries `org` in `scope`. +3. You land in the app, signed in to Northstar Labs. The access token names it in `ouId`, `ouHandle` and `ouName`, lists `Next.js B2B Admin` in `roles`, and carries `org` in `scope`. ### Plug in the company's identity provider 1. Register an OpenID Connect application in your identity provider, with the callback URL the app shows, `https://localhost:8090/gate/callback`. 2. In the app's **Enterprise SSO** section, choose **Create a connection** and enter the application's client ID, client secret and endpoints. 3. Select the new connection and choose **Save changes**. -4. Sign out, choose **Sign in**, then **Sign in with enterprise SSO**, and enter `northstar`. ThunderID sends you to the company's identity provider. A first-time employee joins the company as a `Member`. +4. Sign out, choose **Sign in**, then **Sign in with enterprise SSO**, and enter `northstar`. ThunderID sends you to the company's identity provider. A first-time employee joins the company as a `Next.js B2B Member`. ### One account across several companies -1. Sign out, choose **Sign in**, then **Register your company**, and choose **I work with several companies**. Register `Initech` with the handle `initech`. The account lives in the platform organization and is shared into Initech as its `Admin`. -2. As a platform administrator, in the ThunderID Console: - 1. Under **Organization units**, open `Next.js B2B Quickstart` and add two child organization units, `Globex` and `Umbrella`. - 2. Under **Users**, open the account and select the **Affiliations** tab. Add `Globex` with access to that unit only and the mandated role `Admin`, then `Umbrella` with the mandated role `Member`. Save. -3. Sign out and sign in with the account's password. ThunderID asks which company to sign in to. Pick **Umbrella**: the page shows `Member`, the token's `scope` has no `org`, and the Enterprise SSO section is gone. Sign in again and pick **Globex**: you are its `Admin`, and you can plug in Globex's own identity provider. +Until the sample has a flow that invites an existing account into another company, create an account that belongs to every company in the Console: + +1. Register a second company, such as `Initech` with the handle `initech`, so there are two to switch between. +2. In the Control Plane console, `https://localhost:8095/console`, open **Users** and choose **Add user**. Select the user type **Next.js B2B User**, which places the account in the Default organization unit. Enter a username, such as `nextjs-consultant`, an email and a password, then choose **Create user**. +3. Open the account and select the **Affiliations** tab. Choose **Default and chosen organization units**, keep **All child organization units**, and choose **Save**. The account now belongs to every company beneath the Default organization unit, including the ones that sign up later. +4. Sign out of the app, choose **Sign in**, and sign in with the account. ThunderID asks which company to sign in to. Pick **northstar**. +5. Open the organization menu in the header and pick **Initech**. The page switches to Initech without leaving the app or asking for the password. + +The account holds no role in these companies, so the token's `roles` is empty and the Enterprise SSO section does not show. ### Switching companies -The organization menu in the header lists every company the account belongs to. Picking one sends the browser to that company's sign-in, where the single sign-on session signs the user in without the password. +The organization menu in the header lists every company the account belongs to. Picking one switches the session to that company without leaving the page: the app's server exchanges the session's device secret at the company's token endpoint and rewrites the session cookie with the new tokens. The device secret stays in the server's session store, and the browser never receives it. + +When the session holds no device secret, for example after the dev server restarts, the switch sends the browser to that company's sign-in instead, where the single sign-on session signs the user in without the password. ## How it works -- **One application, many companies.** The application, both roles and the sign-in flow belong to the platform organization and are shared with every child, so a company works the moment it signs up. -- **Sign-up.** The sign-up flow creates the company beneath the platform organization (`OUExecutor`). For an account inside the company, it creates the user there and assigns `Admin`. For a shared account, it creates the user in the platform organization, shares the user into the company (`SharingExecutor`) and assigns `Admin` there (`RoleExecutor`). The sign-in flow calls the sign-up flow, so the new admin lands in the app signed in. +- **One application, many companies.** The application, both roles and the sign-in flow belong to the Default organization unit and are shared with every child, so a company works the moment it signs up. +- **Sign-up.** The sign-up flow creates the company beneath the Default organization unit (`OUExecutor`). For an account inside the company, it creates the user there and assigns `Next.js B2B Admin`. For a shared account, it creates the user in the Default organization unit, shares the user into the company (`SharingExecutor`) and assigns `Next.js B2B Admin` there (`RoleExecutor`). The sign-in flow calls the sign-up flow, so the new admin lands in the app signed in. - **Which company a sign-in lands in.** Enterprise SSO decides it from the handle. A password sign-in picks the one company the user belongs to, or asks. -- **What a company admin can do.** The `Admin` role grants `org` on the System resource server. On a Data Plane, `org` reaches only the organization unit the token names. The SDK sends the management calls from the server with the admin's session, so the admin's changes apply to their own company and the token never reaches the browser. +- **What a company admin can do.** The `Next.js B2B Admin` role grants `org` on the System resource server. On a Data Plane, `org` reaches only the organization unit the token names. The SDK sends the management calls from the server with the admin's session, so the admin's changes apply to their own company and the app's browser code never receives the token. - **Enterprise SSO.** The sign-in flow declares `enterpriseIdp` as a connection variable, and its sharing policy lets every company set its own value. The OpenID Connect step reads the connection from `{{var(enterpriseIdp)}}`. ## Before you go to production diff --git a/quickstarts/nextjs-b2b/app/page.tsx b/quickstarts/nextjs-b2b/app/page.tsx index 45576d0..1653bb9 100644 --- a/quickstarts/nextjs-b2b/app/page.tsx +++ b/quickstarts/nextjs-b2b/app/page.tsx @@ -7,7 +7,7 @@ const decodePayload = (token: string): Record => JSON.parse(Buffer.from(token.split('.')[1], 'base64url').toString('utf8')) /** - * Reads the access token on the server, so it never reaches the browser, and passes its claims to the + * Reads the access token on the server, so the app's browser code never receives it, and passes its claims to the * page. They change with every switch, because a switch signs the user in to another company and * replaces the session's tokens. */ diff --git a/quickstarts/nextjs-b2b/package-lock.json b/quickstarts/nextjs-b2b/package-lock.json index 46146ab..3e12b0b 100644 --- a/quickstarts/nextjs-b2b/package-lock.json +++ b/quickstarts/nextjs-b2b/package-lock.json @@ -8,7 +8,7 @@ "name": "@thunderid/nextjs-b2b-quickstart", "version": "0.0.0", "dependencies": { - "@thunderid/nextjs": "1.19.0", + "@thunderid/nextjs": "1.20.0", "next": "16.4.5", "react": "19.2.3", "react-dom": "19.2.3" @@ -986,9 +986,9 @@ } }, "node_modules/@thunderid/javascript": { - "version": "1.20.0", - "resolved": "https://registry.npmjs.org/@thunderid/javascript/-/javascript-1.20.0.tgz", - "integrity": "sha512-Uu56subIW+GJgkF4nVuJyUNRwEPsg0fE9WUkc1GkJSSPt6WnmSMNmDYU+0XWFs/TYbEm4ACUJdGoyxDOnVpb/w==", + "version": "1.21.0", + "resolved": "https://registry.npmjs.org/@thunderid/javascript/-/javascript-1.21.0.tgz", + "integrity": "sha512-p2tVpFv8S46BCX4smJ6z+aKuFxTB9IIAqbIbpj+5yDkpO5h7ePWZubXEyeB3MKQvhqhjNKxcMFTUjBE6N41FaQ==", "license": "Apache-2.0", "dependencies": { "jose": "6.2.3", @@ -996,13 +996,13 @@ } }, "node_modules/@thunderid/nextjs": { - "version": "1.19.0", - "resolved": "https://registry.npmjs.org/@thunderid/nextjs/-/nextjs-1.19.0.tgz", - "integrity": "sha512-TLp0v9vPPHUV/vz2rZEKvmU7fnTGLQvn0MYnFJGoxzBJ4CyoqZrDiFcn+OJ6zHXXoBYh8ZRQ1lBPpfJtmBohPA==", + "version": "1.20.0", + "resolved": "https://registry.npmjs.org/@thunderid/nextjs/-/nextjs-1.20.0.tgz", + "integrity": "sha512-pAHhhDD+4TBdWfTyFll5U/FeeRt4DSIqKACbRODzczYpq5Byl14XSy4bBl1hmTe2gvpCclFSb+Yzs+JyqStvOw==", "license": "Apache-2.0", "dependencies": { - "@thunderid/node": "^1.17.0", - "@thunderid/react": "^1.22.0", + "@thunderid/node": "^1.18.0", + "@thunderid/react": "^1.22.1", "@types/react": "19.2.14", "jose": "6.2.3", "tslib": "2.8.1" @@ -1013,9 +1013,9 @@ } }, "node_modules/@thunderid/nextjs/node_modules/@thunderid/react": { - "version": "1.22.0", - "resolved": "https://registry.npmjs.org/@thunderid/react/-/react-1.22.0.tgz", - "integrity": "sha512-cow2A12tErdfZuH6efrdqa07UzZMmar1loLmFozH4jhsWctc8oP33egv5UzRaOmKA1ymOLlVoY7SebHOms1SZA==", + "version": "1.22.1", + "resolved": "https://registry.npmjs.org/@thunderid/react/-/react-1.22.1.tgz", + "integrity": "sha512-Kd75Mn0IedrTDEIb8mi9dEo+fh7WhbI0jcX7Mvf0LFaksMHxNVcoWHE6k9GJEB4kRfdtKOAEN9FH9emn1igWNw==", "license": "Apache-2.0", "dependencies": { "@emotion/css": "11.13.5", @@ -1059,12 +1059,12 @@ } }, "node_modules/@thunderid/node": { - "version": "1.17.0", - "resolved": "https://registry.npmjs.org/@thunderid/node/-/node-1.17.0.tgz", - "integrity": "sha512-PE2R2+KZ202AEVSsY4Ej2767wZNvQtnDh+rIo8uoJnMvu3g2bkOShI57wkEs6xTQ7SZ7sBxKKt4tcWVVptn5qg==", + "version": "1.18.0", + "resolved": "https://registry.npmjs.org/@thunderid/node/-/node-1.18.0.tgz", + "integrity": "sha512-6Njj8P5onKE3puipqcK8CD/t7hs0Uf5x2Fm+V+f+z8zJ/wxMzzacY4XU0jKl1rAKx2hLWbCnnV34a9pfEavcYg==", "license": "Apache-2.0", "dependencies": { - "@thunderid/javascript": "^1.20.0", + "@thunderid/javascript": "^1.21.0", "base64url": "3.0.1", "cross-fetch": "4.1.0", "fast-sha256": "1.3.0", diff --git a/quickstarts/nextjs-b2b/package.json b/quickstarts/nextjs-b2b/package.json index 4b54585..9fbeacc 100644 --- a/quickstarts/nextjs-b2b/package.json +++ b/quickstarts/nextjs-b2b/package.json @@ -8,7 +8,7 @@ "start": "next start" }, "dependencies": { - "@thunderid/nextjs": "1.19.0", + "@thunderid/nextjs": "1.20.0", "next": "16.4.5", "react": "19.2.3", "react-dom": "19.2.3" diff --git a/quickstarts/nextjs-b2b/thunderid-config/organization-unit.yaml b/quickstarts/nextjs-b2b/thunderid-config/organization-unit.yaml deleted file mode 100644 index a623e53..0000000 --- a/quickstarts/nextjs-b2b/thunderid-config/organization-unit.yaml +++ /dev/null @@ -1,10 +0,0 @@ -# The platform organization: every company that signs up becomes a child of it. It is a root -# organization unit in the Default project. Import this file before thunderid-config.yaml, which -# places the user type, roles, flows and application here. - -resource_type: organization_unit -id: 019f0b20-0000-7000-8000-000000000001 -handle: nextjs-b2b-quickstart -name: Next.js B2B Quickstart -projectId: 01900000-0000-7000-8000-000000000002 -description: Parent of every company that signs up to the Next.js B2B Quickstart app diff --git a/quickstarts/nextjs-b2b/thunderid-config/thunderid-config.yaml b/quickstarts/nextjs-b2b/thunderid-config/thunderid-config.yaml index baba4fa..8a65355 100644 --- a/quickstarts/nextjs-b2b/thunderid-config/thunderid-config.yaml +++ b/quickstarts/nextjs-b2b/thunderid-config/thunderid-config.yaml @@ -1,19 +1,16 @@ # Next.js B2B Quickstart: the ThunderID resources of the B2B quickstart. # -# Every company that signs up becomes a child organization unit of "Next.js B2B Quickstart". The -# user type, the two roles, the sign-in flow and the application belong to that parent unit and are -# shared with every child, so a company works the moment it signs up. -# -# Import organization-unit.yaml first. Every resource here is placed in the organization unit that -# file creates, and the Console's test import only finds an organization unit that already exists. +# Every company that signs up becomes a child organization unit of the Default organization unit. +# The user type, the two roles, the sign-in flow and the application belong to the Default +# organization unit and are shared with every child, so a company works the moment it signs up. -# Owned by the platform organization, so every company beneath it can use it. +# Owned by the Default organization unit, so every company beneath it can use it. resource_type: user_type id: 019f0b20-0000-7000-8000-000000000002 category: user handle: nextjs-b2b-user displayName: Next.js B2B User -ouHandle: nextjs-b2b-quickstart +ouHandle: default allowSelfRegistration: true systemAttributes: display: username @@ -66,9 +63,9 @@ value: resource_type: role id: 019f0b20-0000-7000-8000-000000000011 projectId: 01900000-0000-7000-8000-000000000002 -name: Admin +name: Next.js B2B Admin description: Manages a company, including its enterprise identity provider -ouHandle: nextjs-b2b-quickstart +ouHandle: default permissions: - resourceServerId: 01900000-0000-7000-8000-000000000020 permissions: @@ -83,9 +80,9 @@ sharingPolicies: resource_type: role id: 019f0b20-0000-7000-8000-000000000012 projectId: 01900000-0000-7000-8000-000000000002 -name: Member +name: Next.js B2B Member description: A member of a company -ouHandle: nextjs-b2b-quickstart +ouHandle: default sharingPolicies: - id: 019f0b20-0000-7000-8000-0000000000a2 childUnits: @@ -93,15 +90,15 @@ sharingPolicies: --- # Company sign-up. The first screen asks where the new admin's account lives: -# - Inside the company: creates the company beneath the platform organization, creates the user in +# - Inside the company: creates the company beneath the Default organization unit, creates the user in # it and makes the user the company's Admin. The account belongs to that company only. -# - Shared: creates the company, creates the user in the platform organization, shares the user into +# - Shared: creates the company, creates the user in the Default organization unit, shares the user into # the company and makes the user the company's Admin there. The account can join more companies. # The sign-in flow calls this flow, so the new admin is signed in when it completes. resource_type: flow id: 019f0b20-0000-7000-8000-000000000022 projectId: 01900000-0000-7000-8000-000000000002 -ouHandle: nextjs-b2b-quickstart +ouHandle: default name: Next.js B2B Quickstart Company Sign-up handle: nextjs-b2b-quickstart-signup flowType: REGISTRATION @@ -296,7 +293,7 @@ nodes: type: TEXT_INPUT required: true properties: - parentOuId: 019f0b20-0000-7000-8000-000000000001 + parentOuId: 01900000-0000-7000-8000-000000000001 onSuccess: provisioning onIncomplete: prompt_company - id: provisioning @@ -479,7 +476,7 @@ nodes: type: TEXT_INPUT required: true properties: - parentOuId: 019f0b20-0000-7000-8000-000000000001 + parentOuId: 01900000-0000-7000-8000-000000000001 onSuccess: provisioning_shared onIncomplete: prompt_company_shared - id: provisioning_shared @@ -554,7 +551,7 @@ nodes: resource_type: flow id: 019f0b20-0000-7000-8000-000000000021 projectId: 01900000-0000-7000-8000-000000000002 -ouHandle: nextjs-b2b-quickstart +ouHandle: default name: Next.js B2B Quickstart Sign-in handle: nextjs-b2b-quickstart-signin flowType: AUTHENTICATION @@ -674,7 +671,7 @@ nodes: required: true properties: resolveFrom: prompt - parentOuId: 019f0b20-0000-7000-8000-000000000001 + parentOuId: 01900000-0000-7000-8000-000000000001 directChildrenOnly: true onSuccess: company_settings onIncomplete: prompt_company @@ -765,8 +762,8 @@ nodes: assignRole: 019f0b20-0000-7000-8000-000000000012 onSuccess: session # The app is shared with every company, so a password sign-in or a new company's admin names no -# organization unit. This decides the company: the one company directly under the platform -# organization the user belongs to, or the one they pick when there are several. A sign-in that +# organization unit. This decides the company: the one company directly under the Default +# organization unit the user belongs to, or the one they pick when there are several. A sign-in that # already names a company, such as a switch, passes straight through. - id: resolve_user_company type: TASK_EXECUTION @@ -774,7 +771,7 @@ nodes: name: OUResolverExecutor properties: resolveFrom: prompt - parentOuId: 019f0b20-0000-7000-8000-000000000001 + parentOuId: 01900000-0000-7000-8000-000000000001 directChildrenOnly: true onSuccess: session onIncomplete: prompt_user_company @@ -849,13 +846,14 @@ sharingPolicies: editable: true --- -# One application serves every company, so it is shared with every child of the platform -# organization. The roles and ou scopes put the company and the user's roles in that company into -# the tokens. +# One application serves every company, so it is shared with every child of the Default +# organization unit. The roles and ou scopes put the company and the user's roles in that company into +# the tokens. The token exchange grant lets the app's server trade its device secret for another +# company's tokens, so a switch stays on the page. resource_type: application id: 019f0b20-0000-7000-8000-000000000031 projectId: 01900000-0000-7000-8000-000000000002 -ouHandle: nextjs-b2b-quickstart +ouHandle: default name: Next.js B2B Quickstart description: Next.js app of the ThunderID B2B quickstart type: fullstack @@ -887,6 +885,7 @@ inboundAuthConfig: grantTypes: - authorization_code - refresh_token + - urn:ietf:params:oauth:grant-type:token-exchange responseTypes: - code tokenEndpointAuthMethod: client_secret_basic diff --git a/quickstarts/nextjs-b2b/thunderid-config/thunderid.env b/quickstarts/nextjs-b2b/thunderid-config/thunderid.env index f07a9ca..06bc424 100644 --- a/quickstarts/nextjs-b2b/thunderid-config/thunderid.env +++ b/quickstarts/nextjs-b2b/thunderid-config/thunderid.env @@ -1,2 +1,6 @@ +# Client ID of the application. NEXTJS_B2B_CLIENT_ID=NEXTJS_B2B_QUICKSTART -NEXTJS_B2B_CLIENT_SECRET=nextjs-b2b-quickstart-secret + +# Client secret of the application. The sample ships without one: generate a value, for example +# with `openssl rand -base64 32`, and set the same value as THUNDERID_CLIENT_SECRET in the app's .env. +NEXTJS_B2B_CLIENT_SECRET= diff --git a/quickstarts/react-b2b/README.md b/quickstarts/react-b2b/README.md index a5a059b..06d0208 100644 --- a/quickstarts/react-b2b/README.md +++ b/quickstarts/react-b2b/README.md @@ -2,14 +2,14 @@ # ThunderID React B2B Quickstart -A React and Vite app for a B2B SaaS product, built with the [ThunderID React SDK](https://www.npmjs.com/package/@thunderid/react) (`@thunderid/react`). Each company that signs up becomes its own organization in ThunderID. People sign in to one company at a time, their tokens name that company and the roles they hold there, and a company admin plugs in the company's own identity provider. +A React and Vite app for a B2B SaaS product, built with the [ThunderID React SDK](https://www.npmjs.com/package/@thunderid/react) (`@thunderid/react`). | What it shows | How | |---|---| | Company sign-up | The sign-in page offers **Register your company**. It creates the company as an organization unit, creates the first admin and signs them in. | -| Account inside the company, or shared | Sign-up asks where the account lives. **My account belongs to this company** creates it inside the company. **I work with several companies** creates it in the platform organization and shares it into the company, so it can join more companies later. | +| Account inside the company, or shared | Sign-up asks where the account lives. **My account belongs to this company** creates it inside the company. **I work with several companies** creates it in the Default organization unit and shares it into the company, so it can join more companies later. | | Organization and roles in the token | The app shows the access token's `ouId`, `ouHandle`, `ouName`, `roles` and `scope`. | -| Switching companies | `OrganizationUnitSwitcher` lists the companies the account belongs to and switches the session to the one picked. The new tokens name that company and the roles held there. | +| Switching companies | `OrganizationUnitSwitcher` lists the companies the account belongs to and switches the session to the one picked, without leaving the page. The new tokens name that company and the roles held there. | | Enterprise SSO per company | A company admin adds an OpenID Connect identity provider with `createConnection`, and selects it with `FlowVariablesForm`. Employees then choose **Sign in with enterprise SSO** and enter the company's handle. | ## Prerequisites @@ -30,26 +30,23 @@ cd my-app ### Import the ThunderID resources -`thunderid-config/` holds two files that create everything the app needs, with fixed IDs so the app's configuration works unchanged. Import them in the ThunderID Console, in this order: +`thunderid-config/thunderid-config.yaml` creates everything the app needs in the Default organization unit, with fixed IDs so the app's configuration works unchanged. Every company that signs up becomes a child of the Default organization unit. Import it in the ThunderID Console: 1. Sign in to the Console. With the quickstart image it is the Control Plane console, `https://localhost:8095/console`. -2. On the **welcome screen** (shown on first sign-in, or from the user profile menu), choose **Open** and upload `thunderid-config/organization-unit.yaml`. It needs no environment file. -3. Open the welcome screen again, upload `thunderid-config/thunderid-config.yaml`, then `thunderid-config/thunderid.env` for its variables. +2. Choose **Import / Export**, then **Import**. Upload `thunderid-config/thunderid-config.yaml` as the configuration file and `thunderid-config/thunderid.env` as the environment variables file. +3. Choose **Continue**, then **Import configuration**. -The Console tests each import before it runs it, and that test only finds an organization unit that already exists. The second file places every resource in the organization unit the first one creates, so import the first one on its own. - -The imports create a root organization unit and set a server config, and only the Control Plane writes those, so import there. Imported straight into a Data Plane, both are refused. +The import replaces the `defaultResourceServer` setting, which only the Control Plane writes, so import there. Imported straight into a Data Plane, it is refused. | Resource | Name | What it does | |---|---|---| -| Organization unit | React B2B Quickstart (`react-b2b-quickstart`) | The platform organization, a root organization unit in the Default project. Every company that signs up becomes its child. | | User type | React B2B User (`react-b2b-user`) | The account schema, with self-registration on. Usable in every company. | | Server config | `defaultResourceServer` | Makes the System resource server the default, for authorization requests that name no resource | -| Role | Admin | Grants the `org` permission, which manages the organization the token names. Shared with every company. | -| Role | Member | Grants no permission. Shared with every company. | +| Role | React B2B Admin | Grants the `org` permission, which manages the organization the token names. The role is shared with every company. | +| Role | React B2B Member | Grants no permission. The role is shared with every company. | | Flow | React B2B Quickstart Company Sign-up | Creates the company and its first admin, with the account inside the company or shared into it | | Flow | React B2B Quickstart Sign-in | Password, enterprise SSO, or company sign-up. Keeps a single sign-on session, so a switch does not ask for the password again. Shared with every company, which may set `enterpriseIdp`. | -| Application | React B2B Quickstart | Public client with PKCE, redirecting to `https://localhost:5173`. Shared with every company. | +| Application | React B2B Quickstart | Public client with PKCE and the token exchange grant, redirecting to `http://localhost:5173`. The application is shared with every company. | `thunderid.env` sets one variable: @@ -57,7 +54,7 @@ The imports create a root organization unit and set a server config, and only th |---|---| | `REACT_B2B_CLIENT_ID` | Client ID of the application. Defaults to `REACT_B2B_QUICKSTART`. | -Then add `https://localhost:5173` to the CORS allowed origins (**Settings → CORS**), so the browser lets the app call ThunderID. +Then add `http://localhost:5173` to the CORS allowed origins, so the browser lets the application call ThunderID. Clear the project selection, choose **Configurations** in the sidebar, then **CORS**. Choose **Add origin**, enter `http://localhost:5173`, and choose **Save changes**. ### Configure the app @@ -81,7 +78,7 @@ npm install npm run dev ``` -Open [https://localhost:5173](https://localhost:5173). The dev server uses a self-signed certificate, so accept the browser's warning once. The app runs on https, like ThunderID, so the two are the same site and a switch can reuse the ThunderID sign-in in a hidden frame. +Open [http://localhost:5173](http://localhost:5173). ## Try it @@ -89,40 +86,46 @@ Open [https://localhost:5173](https://localhost:5173). The dev server uses a sel 1. Choose **Sign in**, then **Register your company** on the ThunderID sign-in page. 2. Choose **My account belongs to this company**. Enter a username, an email and a password, then `Northstar Labs` as the company name and `northstar` as its handle. -3. You land in the app, signed in to Northstar Labs. The access token names it in `ouId`, `ouHandle` and `ouName`, lists `Admin` in `roles`, and carries `org` in `scope`. +3. You land in the app, signed in to Northstar Labs. The access token names it in `ouId`, `ouHandle` and `ouName`, lists `React B2B Admin` in `roles`, and carries `org` in `scope`. ### Plug in the company's identity provider 1. Register an OpenID Connect application in your identity provider, with the callback URL the app shows, `https://localhost:8090/gate/callback`. 2. In the app's **Enterprise SSO** section, choose **Create a connection** and enter the application's client ID, client secret and endpoints. 3. Select the new connection and choose **Save changes**. -4. Sign out, choose **Sign in**, then **Sign in with enterprise SSO**, and enter `northstar`. ThunderID sends you to the company's identity provider. A first-time employee joins the company as a `Member`. +4. Sign out, choose **Sign in**, then **Sign in with enterprise SSO**, and enter `northstar`. ThunderID sends you to the company's identity provider. A first-time employee joins the company as a `React B2B Member`. The setting applies to Northstar Labs only. Another company sees its own value, or none. ### One account across several companies -1. Sign out, choose **Sign in**, then **Register your company**, and choose **I work with several companies**. Register `Initech` with the handle `initech`. The account lives in the platform organization and is shared into Initech as its `Admin`. -2. As a platform administrator, in the ThunderID Console: - 1. Under **Organization units**, open `React B2B Quickstart` and add two child organization units, `Globex` and `Umbrella`. - 2. Under **Users**, open the account and select the **Affiliations** tab. Add `Globex` with access to that unit only and the mandated role `Admin`, then `Umbrella` with the mandated role `Member`. Save. -3. Back in the app, open the organization menu in the header. It lists Initech, Globex and Umbrella. Pick **Umbrella**: the page shows `Member`, the token's `scope` has no `org`, and the Enterprise SSO section is gone. Pick **Globex**: you are its `Admin`, and you can plug in Globex's own identity provider. +Until the sample has a flow that invites an existing account into another company, create an account that belongs to every company in the Console: + +1. Register a second company, such as `Initech` with the handle `initech`, so there are two to switch between. +2. In the Control Plane console, `https://localhost:8095/console`, open **Users** and choose **Add user**. Select the user type **React B2B User**, which places the account in the Default organization unit. Enter a username, such as `react-consultant`, an email and a password, then choose **Create user**. +3. Open the account and select the **Affiliations** tab. Choose **Default and chosen organization units**, keep **All child organization units**, and choose **Save**. The account now belongs to every company beneath the Default organization unit, including the ones that sign up later. +4. Sign out of the app, choose **Sign in**, and sign in with the account. ThunderID asks which company to sign in to. Pick **northstar**. +5. Open the organization menu in the header and pick **Initech**. The page switches to Initech without leaving the app or asking for the password. -A password sign-in for an account in several companies asks which company to sign in to. +The account holds no role in these companies, so the token's `roles` is empty and the Enterprise SSO section does not show. ## How it works -- **One application, many companies.** The application, both roles and the sign-in flow belong to the platform organization and are shared with every child, so a company works the moment it signs up. -- **Sign-up.** The sign-up flow creates the company beneath the platform organization (`OUExecutor`). For an account inside the company, it creates the user there and assigns `Admin`. For a shared account, it creates the user in the platform organization, shares the user into the company (`SharingExecutor`) and assigns `Admin` there (`RoleExecutor`). The sign-in flow calls the sign-up flow, so the new admin lands in the app signed in. -- **Which company a sign-in lands in.** Enterprise SSO decides it from the handle. A password sign-in picks the one company the user belongs to, or asks. A switch signs in to the company the app names, at `/ou/{ouId}/oauth2/authorize`, and the flow's single sign-on session skips the password. -- **What a company admin can do.** The `Admin` role grants `org` on the System resource server. On a Data Plane, `org` reaches only the organization unit the token names, so the admin's `createConnection` and `FlowVariablesForm` calls change their own company. +- **One application, many companies.** The application, both roles and the sign-in flow belong to the Default organization unit and are shared with every child, so a company works the moment it signs up. +- **Sign-up.** The sign-up flow creates the company beneath the Default organization unit (`OUExecutor`). For an account inside the company, it creates the user there and assigns `React B2B Admin`. For a shared account, it creates the user in the Default organization unit, shares the user into the company (`SharingExecutor`) and assigns `React B2B Admin` there (`RoleExecutor`). The sign-in flow calls the sign-up flow, so the new admin lands in the app signed in. +- **Which company a sign-in lands in.** Enterprise SSO decides it from the handle. A password sign-in picks the one company the user belongs to, or asks. +- **Switching.** The app asks for the `device_sso` scope, so the sign-in also returns a device secret, which carries the flow's single sign-on session. A switch exchanges it at `/ou/{ouId}/oauth2/token` for tokens bounded to the company the app names, with no redirect and no password. When the exchange needs the user, the SDK sends the browser to `/ou/{ouId}/oauth2/authorize` instead. +- **What a company admin can do.** The `React B2B Admin` role grants `org` on the System resource server. On a Data Plane, `org` reaches only the organization unit the token names, so the admin's `createConnection` and `FlowVariablesForm` calls change their own company. - **Enterprise SSO.** The sign-in flow declares `enterpriseIdp` as a connection variable, and its sharing policy lets every company set its own value. The OpenID Connect step reads the connection from `{{var(enterpriseIdp)}}`. -`src/App.jsx` has a short effect that finishes a switch that returns to the app through a redirect. `@thunderid/react` 1.21.0 redeems a returning code only when no session exists, so without it a switch stays on the previous company. Remove the effect once the SDK finishes the switch itself. - ## Before you go to production -The app runs entirely in the browser, and a company admin's token carries `org`, which manages everything in their company. Grant it only to people you trust with the whole company, or route management calls through a backend that holds the permission and checks each call, as the [Wayfinder Enterprise sample](https://github.com/thunder-id/samples/tree/main/b2b/wayfinder-enterprise) does. +The app runs entirely in the browser, so the SDK keeps the tokens and the device secret in browser storage, where any script on the page can read them. The device secret matters most: until the single sign-on session ends, whoever holds it can get tokens for every company the account belongs to, without the user. The app also can't support single logout: if users sign in to this app and another app through single sign-on, signing out of the other app leaves them signed in here until their tokens stop working. If either matters, pick one of these setups: + +- **Build with Next.js (recommended).** The Next.js SDK signs users in on the server, keeps the tokens in an `HttpOnly` cookie that scripts cannot read, and receives back-channel logout. See the [Next.js B2B quickstart](https://github.com/thunder-id/samples/tree/main/quickstarts/nextjs-b2b). +- **Add a Backend for Frontend (BFF).** Keep this React app and add a small server that signs users in and holds the tokens, so the browser gets only an `HttpOnly` session cookie. See the [React and Express BFF sample](https://github.com/thunder-id/samples/tree/main/patterns/react-express-bff) and [how to set up a BFF](https://thunderid.dev/docs/next/sdks-and-tools/react/guides/backend-for-frontend). + +A company admin's token also carries `org`, which manages everything in their company. Grant it only to people you trust with the whole company, or route management calls through a backend that holds the permission and checks each call, as the [Wayfinder Enterprise sample](https://github.com/thunder-id/samples/tree/main/b2b/wayfinder-enterprise) does. ## Learn more diff --git a/quickstarts/react-b2b/package-lock.json b/quickstarts/react-b2b/package-lock.json index 23f8b07..87b2446 100644 --- a/quickstarts/react-b2b/package-lock.json +++ b/quickstarts/react-b2b/package-lock.json @@ -8,12 +8,11 @@ "name": "@thunderid/react-b2b-quickstart", "version": "0.0.0", "dependencies": { - "@thunderid/react": "1.21.0", + "@thunderid/react": "1.22.1", "react": "19.2.3", "react-dom": "19.2.3" }, "devDependencies": { - "@vitejs/plugin-basic-ssl": "^2.3.0", "@vitejs/plugin-react": "6.0.2", "vite": "8.3.4" } @@ -687,12 +686,12 @@ "license": "MIT" }, "node_modules/@thunderid/browser": { - "version": "1.18.0", - "resolved": "https://registry.npmjs.org/@thunderid/browser/-/browser-1.18.0.tgz", - "integrity": "sha512-CMycJ4cEB0ztgJD7mCzoFG/zGxo9TczeLee5GhmRTx3asNcQCAnaJfS2KVM0JvEmjAq8uuBaNBhtPm01NYgMTA==", + "version": "1.19.0", + "resolved": "https://registry.npmjs.org/@thunderid/browser/-/browser-1.19.0.tgz", + "integrity": "sha512-9FgwTaBwIFozB73xXeh5LvwHri3blW+zozAYYlMpNPWagzMfOxx7XRd6Qm7ajPm6lXJA1vIbYixiC4a8o+A5EQ==", "license": "Apache-2.0", "dependencies": { - "@thunderid/javascript": "^1.19.0", + "@thunderid/javascript": "^1.20.0", "base64url": "3.0.1", "buffer": "6.0.3", "core-js": "3.42.0", @@ -705,9 +704,9 @@ } }, "node_modules/@thunderid/javascript": { - "version": "1.19.0", - "resolved": "https://registry.npmjs.org/@thunderid/javascript/-/javascript-1.19.0.tgz", - "integrity": "sha512-fYinwhNQn8oicjIk1Gb/wY4fXaOCrFYCLXVoVLJxiSmVck367zsJYO5azRE2EYSgAwotmfoRoDOwmpUB19wDDw==", + "version": "1.20.0", + "resolved": "https://registry.npmjs.org/@thunderid/javascript/-/javascript-1.20.0.tgz", + "integrity": "sha512-Uu56subIW+GJgkF4nVuJyUNRwEPsg0fE9WUkc1GkJSSPt6WnmSMNmDYU+0XWFs/TYbEm4ACUJdGoyxDOnVpb/w==", "license": "Apache-2.0", "dependencies": { "jose": "6.2.3", @@ -715,14 +714,14 @@ } }, "node_modules/@thunderid/react": { - "version": "1.21.0", - "resolved": "https://registry.npmjs.org/@thunderid/react/-/react-1.21.0.tgz", - "integrity": "sha512-yeTFhmS2p6lXEMcJVL9XizIqQKE9cTxe0I59xii0bu9z3Mp7g7+ONU8cm3wuRul230fpeVobvizkfsGgU7M3lA==", + "version": "1.22.1", + "resolved": "https://registry.npmjs.org/@thunderid/react/-/react-1.22.1.tgz", + "integrity": "sha512-Kd75Mn0IedrTDEIb8mi9dEo+fh7WhbI0jcX7Mvf0LFaksMHxNVcoWHE6k9GJEB4kRfdtKOAEN9FH9emn1igWNw==", "license": "Apache-2.0", "dependencies": { "@emotion/css": "11.13.5", "@floating-ui/react": "0.27.12", - "@thunderid/browser": "^1.18.0", + "@thunderid/browser": "^1.19.0", "dompurify": "3.4.17", "tslib": "2.8.1" }, @@ -766,19 +765,6 @@ "license": "MIT", "optional": true }, - "node_modules/@vitejs/plugin-basic-ssl": { - "version": "2.3.0", - "resolved": "https://registry.npmjs.org/@vitejs/plugin-basic-ssl/-/plugin-basic-ssl-2.3.0.tgz", - "integrity": "sha512-bdyo8rB3NnQbikdMpHaML9Z1OZPBu6fFOBo+OtxsBlvMJtysWskmBcnbIDhUqgC8tcxNv/a+BcV5U+2nQMm1OQ==", - "dev": true, - "license": "MIT", - "engines": { - "node": "^18.0.0 || ^20.0.0 || >=22.0.0" - }, - "peerDependencies": { - "vite": "^6.0.0 || ^7.0.0 || ^8.0.0" - } - }, "node_modules/@vitejs/plugin-react": { "version": "6.0.2", "resolved": "https://registry.npmjs.org/@vitejs/plugin-react/-/plugin-react-6.0.2.tgz", diff --git a/quickstarts/react-b2b/package.json b/quickstarts/react-b2b/package.json index 1cd1995..cba5791 100644 --- a/quickstarts/react-b2b/package.json +++ b/quickstarts/react-b2b/package.json @@ -9,12 +9,11 @@ "preview": "vite preview" }, "dependencies": { - "@thunderid/react": "1.21.0", + "@thunderid/react": "1.22.1", "react": "19.2.3", "react-dom": "19.2.3" }, "devDependencies": { - "@vitejs/plugin-basic-ssl": "2.3.0", "@vitejs/plugin-react": "6.0.2", "vite": "8.3.4" } diff --git a/quickstarts/react-b2b/src/App.jsx b/quickstarts/react-b2b/src/App.jsx index f0d499e..bd81038 100644 --- a/quickstarts/react-b2b/src/App.jsx +++ b/quickstarts/react-b2b/src/App.jsx @@ -1,4 +1,4 @@ -import { useEffect, useState } from 'react' +import { useState } from 'react' import { SignInButton, SignedIn, SignedOut, useGrantedPermissions, useTheme, useThunderID } from '@thunderid/react' import EnterpriseSso from './components/EnterpriseSso.jsx' import Nav from './components/Nav.jsx' @@ -138,20 +138,10 @@ function Workspace() { } export default function App() { - const { currentOrganizationUnit, isSignedIn, signIn } = useThunderID() + const { currentOrganizationUnit } = useThunderID() const [dark, setDark] = useState(false) const { toggleTheme } = useTheme() - // A switch returns to the app with an authorization code while the previous company's session is - // still signed in, and @thunderid/react 1.21.0 only redeems a code when no session exists. Calling - // signIn() lets the SDK finish the switch. Remove this once the SDK completes the switch itself. - useEffect(() => { - const params = new URLSearchParams(window.location.search) - if (isSignedIn && params.has('code') && params.has('state')) { - signIn().catch(() => undefined) - } - }, [isSignedIn, signIn]) - const toggleDark = () => { const next = !dark setDark(next) diff --git a/quickstarts/react-b2b/src/components/Nav.jsx b/quickstarts/react-b2b/src/components/Nav.jsx index 48bbdf5..05a4305 100644 --- a/quickstarts/react-b2b/src/components/Nav.jsx +++ b/quickstarts/react-b2b/src/components/Nav.jsx @@ -34,7 +34,8 @@ export default function Nav({ dark, onToggleDark }) {
{/* Lists the companies the user belongs to and switches the session to the one picked. A switch - is a new sign-in, so it names the same resource server as the first one. */} + that falls back to a redirect is a new sign-in, so it names the same resource server as the + first one. */}