Design Decisions
The shape of Wayfinder Enterprise, from the B2B model through the quick start and each journey, rests on the choices below. Each decision names the default this section uses and when the alternative fits better.
Every organization in this section is an organization unit (OU), a node in the hierarchy that owns its own users, groups, and roles, beneath one platform OU. See Manage Organization Units.
Where Accounts Live
The two organization sign-up templates differ in where the new account is created.
| Account in the organization | Account in the platform organization, shared in | |
|---|---|---|
| Template | Organization Sign-up | Organization Sign-up with Shared Account |
| The account lives in | The new organization | The user type's OU, the platform organization |
| One person in several organizations | No: an invitation shares an account only into a direct child of the OU that owns it, so a Northstar Labs account cannot be invited into Initech, its sibling | Yes: the platform organization's direct children are the companies, so the account can be shared into any of them |
- Default in this section: a company's first admin lives in their organization, through Organization Sign-up. Each company's people belong to that company, which matches how most business customers think about their staff. Accounts that an invitation creates are the exception: they live in the platform organization and are shared in, so an invited person can later join another company.
- Choose shared accounts when one person works across organizations, such as consultants, agencies, or a support team serving every customer. See Switch Organizations.
See Go Further in Build a Multi-Factor Sign-In Flow for both templates.
How a Sign-In Picks the Organization
A shared application's sign-in must land in exactly one organization before ThunderID issues a token. Three places can decide it:
| Decided by | How | Fits when |
|---|---|---|
| The request | The application sends the organization's ID, at /ou/{ouId}/oauth2/authorize or as ouId on the flow start. | The application already knows the organization, such as from a company-specific link or subdomain your application maps to an ID. |
| The person, before sign-in | A Resolve OU step with directChildrenOnly asks for the organization's handle, such as northstar. | Each organization signs in differently, such as with its own identity provider, so the organization must be known before the credentials. |
| The flow, after sign-in | A Resolve OU step after the credential check picks the person's organization, and asks only when there are several. | People sign in with one method everywhere, and most belong to one organization. |
- Default in this section: the Basic + Enterprise SSO template uses both flow-based options: a handle prompt before enterprise SSO, and a pick after password sign-in.
- Choose the request when your application can tell the organization from context. It saves the person a step.
See Sign Users In to Organization Units for the full set of rules and refusals.
Shared Roles or Per-Organization Roles
- Default in this section:
Wayfinder AdminandWayfinder Memberare defined once in the platform organization and shared with every child organization. Every company gets the same roles, a sign-up flow can assign them in a company that did not exist a moment earlier, and a permission change reaches every company at once. - Choose per-organization roles when organizations need roles of their own. An organization can own roles, and a role name must be unique only among the roles an organization owns and those shared with it.
- Restrict shared roles when an organization may use a role but not hand it out. A sharing policy can turn assignments off for some organizations. Only a resource file or the Role Sharing API sets this rule. See Assignments Turned Off.
Who Configures Enterprise SSO
Each organization's identity provider is a connection that organization owns, chosen through the shared sign-in flow's enterpriseIdp variable.
- Default in this section: the organization's admin connects their own identity provider from inside your application, with
FlowVariablesFormbehind a backend route. Onboarding a company's identity provider needs nobody from the platform team. - Choose platform-managed SSO when enterprise customers expect a guided setup, or the connection details must not pass through an admin's browser. The platform team creates the connection in the organization and sets its
enterpriseIdpvalue through the API.
See Share a Flow for how an organization's values override a shared flow, and Plug In an Enterprise IdP for both paths.
How Admins Reach the Management API
- Default in this section: a backend route checks the admin's own application permission, pins every call to the admin's organization, and calls ThunderID with a backend client's token issued for that organization. The client holds the root
systempermission, so the route, not ThunderID, keeps each call inside that organization. The admin's token never carries a ThunderID management permission. See Let Organization Admins Manage Teams. - Choose direct calls when an internal tool's admins sign in with tokens that name their organization in
ouIdand carry organization-confined permissions such assystem:user:view. On the Data Plane, each of those permissions acts only in the OU the token names. If the deployment setsserver.security.rest.audience, the tokens must also be issued for that audience. See System Permissions.
Never let an organization admin's token carry the root system permission. It acts in every OU of the deployment, not only the admin's organization.
One Shared Application or One per Organization
- Default in this section: one application, shared with every company. A new company can sign in the moment it signs up, and one client ID serves every company.
- Choose an application per organization when each customer needs its own client registration, such as different redirect URIs, or a dedicated deployment of your product. An application that is not shared signs people in to its own OU only, so no organization step is needed in the flow.
A shared application's flow must decide the organization, or the sign-in is refused at its assertion step with FET-1124.
Flat or Nested Organizations
- Default in this section: companies are direct children of the platform organization. A handle such as
northstarnames one company, and a role shared with all child organizations reaches each of them. - Choose nested organizations when customers have departments, regions, or subsidiaries of their own. OUs nest to any depth, and a sharing policy can reach one OU or its whole subtree. Resolve OU without
directChildrenOnlyoffers OUs by their handle path from the top of the tree, such asdefault/wayfinder-enterprise/northstar/engineering.
Two rules shape a nested tree:
- A sign-up or invitation flow shares an account only into a direct child of the OU that owns it. A sharing policy set through the API or a resource file can reach a whole subtree.
- Groups are never shared: a group belongs to one OU, and its members must live in that OU or be shared into it.
See Resource Sharing Across Organization Units for every sharing mode.
What You Have Now
You have a platform where each business customer is its own organization. Companies sign themselves up, and people sign in to the organization they belong to, switching when they work in several. Each company can bring its own identity provider, and each company's admin manages its own team. Every sign-in lands in one organization, and only the roles assigned there count.
Most of these decisions can change later without unraveling the rest. Adding nested organizations, per-organization roles, or platform-managed SSO adds to the tree you have. Moving accounts between the organization and the platform organization is the expensive one to revisit, because it changes where existing people live, so settle it before you onboard customers at scale.
