[Design Discussion] Flexible OU and User Type Resolution Order in Onboarding Flows

[DonOmalVindula]

Related Feature Issue

#2140

---

Problem Summary

In the current user onboarding (invite) flow, the admin must select a user type first, then an OU. The OU tree picker is scoped to the selected user type's schema OU, hiding OUs outside that subtree. This is limiting for multi-tenant deployments (e.g., WSO2 Cloud) where admins need to see the full OU tree and pick an OU first — then have the system narrow down which user types are valid for that OU. Today, only one ordering is possible because OUResolverExecutor hard-depends on UserTypeResolver having run first.

---

High-Level Approach

• Make OUResolverExecutor and UserTypeResolver order-independent so either can run first in a flow.
• Add a new OU resolution strategy ("promptAll") that shows the full OU tree without depending on a pre-selected user type.
• Add OU-aware filtering to UserTypeResolver so it can narrow schemas based on a previously selected OU.
• Both orderings become first-class flow configurations — the flow author picks which to use by reordering nodes and setting a property. No code changes needed to switch between them.

Supported flow variants:

Variant	Node order	When to use
UserType-first (existing)	UserTypeResolver → OUResolverExecutor("prompt")	User types are the primary organizing concept; OUs are secondary
OU-first (new)	OUResolverExecutor("promptAll") → UserTypeResolver	OUs are the primary concept (multi-tenant); user types are secondary

---

Architecture Overview

Current coupling

OUResolverExecutor in "prompt" mode reads defaultOUID from RuntimeData, which is set by UserTypeResolver. If defaultOUID is missing, execution fails. This forces the UserType-first ordering.

Proposed: order-independent executors

Each executor checks what RuntimeData is already available and adapts:

OU-first flow:

UserType-first flow (unchanged):

Filtering logic: which user types are valid for a given OU?

Each user schema has an OUID — the OU it was created under. A schema is valid for any OU that is a descendant of (or equal to) the schema's OU. This uses the same IsParent() validation that user/service.go:validateOrganizationUnitForUserType() already enforces at user creation time.

OU Tree:                     Schemas:

Root
├── Customers (OU-C)  ←────  b2b_person (OUID = OU-C)
│   ├── Acme Corp
│   └── Globex
├── Internal (OU-I)   ←────  internal_employee (OUID = OU-I)
│   └── Engineering
└── Default (OU-D)    ←────  Person (OUID = OU-D)

Selected OU	Valid user types	Why
Acme Corp	b2b_person	Acme is a descendant of OU-C
Engineering	internal_employee	Engineering is a descendant of OU-I
Customers (OU-C)	b2b_person	Self-match (OU-C = OU-C)

---

Security Considerations

• No new permissions or APIs introduced. The change is internal to the flow engine — it controls which UI options are shown to the admin during onboarding.
• OU visibility: The "promptAll" strategy shows the full OU tree to the admin, including OUs above their own level. This is intentional for the use case (admin inviting users across the org). Deployments that want to restrict OU visibility should continue using "prompt" or "caller" strategies.
• No bypass of existing validation. user/service.go:validateOrganizationUnitForUserType() continues to enforce that the user's OU is valid for the selected schema at user creation time. The flow-level filtering is a UX convenience, not a security boundary.

---

Impacted Areas

• Flow Engine — OUResolverExecutor, UserTypeResolver, executor registry
• Flow Configuration — Onboarding flow JSON/YAML (node ordering, strategy property)
• Gate App (Frontend) — OU tree picker may need to handle rendering the full tree when no rootOuId is provided (needs verification)

---

Alternatives Considered

Alternative 1: Single executor that handles both OU and user type selection

• Pros: No inter-executor dependency to manage; single node in flow
• Cons: Violates single-responsibility; large executor; less flexible for flow authors; breaks existing flows that use the executors independently
• Decision: Keep separate executors but make them order-independent

Alternative 2: Make "prompt" strategy fall back to full tree when defaultOUID is absent

• Pros: No new strategy name; fewer concepts to learn
• Cons: Changes existing behavior (currently errors when defaultOUID is missing, which catches misconfiguration); implicit behavior harder to reason about
• Decision: Introduce explicit "promptAll" strategy — clearer intent, no risk to existing flows

Alternative 3: Scope "promptAll" to caller's OU subtree instead of full tree

• Pros: More restrictive, potentially safer
• Cons: Doesn't meet the requirement — admin needs to see OUs above their own level for cross-org user placement
• Decision: Show full tree; rely on existing RBAC and OU membership policies for access control

---

Questions for Discussion

1. Frontend OU tree picker behavior: When no rootOuId is provided in AdditionalData, does the gate app's OU tree picker render the full tree from root by default? Or does it need an explicit root OU ID? This determines whether "promptAll" needs to look up and pass the root OU.

2. Validation on OU selection in "promptAll": Should we validate that at least one user type exists for the selected OU at the OU selection step? Or defer that to UserTypeResolver (which would show "no valid user types" if none match)? Early validation is better UX but adds coupling.

3. Should "promptAll" be the name? Other candidates: "tree", "fullTree", "global". The name should clearly convey "shows the entire OU hierarchy without scoping."

4. Auto-selection behavior in OU-first flow: When UserTypeResolver filters schemas by OU and only one remains, it auto-selects (admin never sees a user type prompt). Should this auto-selection be configurable, or is it always the right behavior?

[ThaminduDilshan]

Rather than adding a new promptAll resolve strategy, what if we reuse the same prompt for this. Only impact is we'll lose the default OUID existence check in [1]. Rather we use that to identify whether to scope down ou selection or prompt for all ous.

I'm thinking whether we need to have this error. Even with this improvement, it is still mandatory to have the UserTypeResolver executor in registration flows. Given that, if someone need to have OU picker, it is just about placing OUResolverExecutor before or after the UserTypeResolver node. I feel like we can reuse the same strategy rather than introducing a new one.

[1]

thunder/backend/internal/flow/executor/ou_resolver_executor.go

Line 144 in f099634

return nil, errors.New(