[Design Discussion] Projects in ThunderID

[Malith-19]

Related Feature Issue

#5861

Related: #2645 (B2B support), #3346 (common resource architecture), #3310 (resource modeling first principles), #5511 (resource sharing specification)

Problem Summary

ThunderID has no way to group identity configuration by product. Inside one deployment, every application, resource server, role, flow and connection sits in one pool, so teams building several products cannot manage, promote or later delegate them separately. Developer platforms commonly organize work as organization > project, with dev, stage and prod environments as siblings of the project. Platforms that integrate with ThunderID in this way have nowhere to place the identities they create for a project, so they fall back on the default OU and encode the project in resource names.

This discussion proposes the smallest model that gives ThunderID projects without changing its core resource model, and asks for input on the open points listed at the end.

High-Level Approach

A project is a root organization unit.

• Every root OU (an OU with no parent) is presented as a project. The existing default OU becomes the Default project, so existing deployments need no data migration.
• Child OUs inside a project keep their current meaning: organizations, departments, partners or customer tenants of that project.
• A resource belongs to a project when its OU is the project's root OU or any descendant of it. Ownership is the existing ouId; no new column is added.
• To have another root, you create another project. A project holds exactly one root OU (root OU is the project).
• At runtime nothing changes. A project is an OU, and authentication, tokens and authorization behave as they do today.
• Projects are a control plane (management) concept. A project management API creates the root OU, and the root OU's ID is the project ID. That ID can be supplied by the caller, so a system that manages projects across several tools can use one ID everywhere, and the ID stays the same in every environment.
• Creating a root OU is only possible by creating a project. The OU API keeps creating child OUs.

Why a root OU and not a new construct: in ThunderID an OU is already the unit that owns resources, and the B2B work is making every resource OU-bound (#3310, #3346). The root OU is where a solution starts: nothing else in the tree can be created without it. Calling that starting point a project gives a grouping that every OU-bound resource, current and future, inherits without being changed. Platforms that run workloads often define a project as a runtime namespace; this is the equivalent definition from ThunderID's resource model.

Architecture Overview

How the concepts map

Control plane / Console	Data plane (runtime)
Organization (tenant of the management system)	One ThunderID deployment per environment
Environment (dev, stage, prod)	Separate deployment, separated by DEPLOYMENT_ID
Project	Root OU, ID = project ID
Default project	The existing default OU
Organizations, departments, customers inside a project	Child OUs
Resource in a project	Resource whose ouId is in the project's subtree
Resource not bound to any OU yet (flows, IDPs, themes, layouts, notification senders, translations)	Deployment-level resource, see question 3

Security Considerations

• Root OU creation becomes privileged. Only the project API, used by a root administrator or a trusted management client, can create a root OU. This also stops an OU administrator from creating a sibling tree.

• Externally supplied project IDs are accepted only from the control plane, through an authenticated, root-privileged client. The ID must be a valid UUID that is not already used by any OU.

• The project boundary is enforced at configuration time only. At runtime there is no project boundary; for example, a role assignment grants its permissions regardless of project. This is the same as today, but must be documented clearly so a project is not mistaken for runtime isolation. Hard isolation remains an environment (deployment) concern.

• Cross-project references. Until a sharing model exists, management APIs should refuse a reference from a resource in one project to a resource in another, for example an app in project A using a role or user type of project B.

• Runtime exposure. Projects can surface at runtime as root OUs:

  • in the ouId, ouName and ouHandle token claims;
  • in sign-up flows that let the user pick an OU.

  Project names should not be considered secret, and deployments that do not use B2B features may want to hide these surfaces (see question 6).

• Admin scoping. Until B2B delegated administration lands, most resource types (applications, resource servers, roles, flows) need root permission. A project does not yet restrict what an administrator can see.

Impacted Areas

• OU service and API: root creation rules, project ID supplied on create and all the resources should support the OU id filter in the APIs
• New project management API (control plane), OpenAPI spec, SDK management operations, MCP tools
• Console: project switcher, project-scoped lists and create flows, OU page, terminology
• Declarative resources, export and import: a root OU in a resource file is a project
• System authorization (sysauthz): project-scoped administration, together with B2B
• Resource sharing framework (Add Resource sharing framework specification #5511): future cross-project sharing
• Integrations that create identities on behalf of a project, such as agent identities and API consumer applications
• Documentation: concepts for project, environment and OU, and migration notes

Alternatives Considered

Option 1: a project label on resources. A project ID column is added to every resource, and a project may contain several root OUs.

• Pros: least change to existing behavior.
• Cons:
  • Two overlapping ways to say "this belongs to that".
  • Every resource type needs a decision on both.
  • Other products still don't know which OU to create an agent in.
• Decision: rejected.

Option 2: a label with exactly one root OU per project. The project still carries resources that are not OU-bound.

• Pros: one OU tree per project, while leaving room for resources outside it.
• Cons: still needs a project ID on non-OU resources, and the default OU has to be special-cased and hidden.
• Decision: rejected in favor of option 3, which reaches the same "one root per project" without a new column.

Option 3: project = root OU (proposed).

• Pros:
  • No change to the core resource model.
  • Aligns with B2B's "every resource is OU-bound".
  • An externally managed project ID can become the root OU ID.
  • Runtime is unchanged.
  • Smallest change to deliver a first iteration.
• Cons:
  • Overloads OU with a second meaning.
  • Projects are visible at runtime as root OUs.
  • Cross-project consumption depends on OU sharing.

Option 4: a project as a first-class construct.

• How it works:
  • A project can hold resources directly and can hold OUs, which hold resources.
  • In the data plane the project boundary disappears: project-level resources become deployment-level resources, and only the OUs created explicitly remain.
  • A B2C solution never sees an OU.
• Pros:
  • Matches how many developer platforms model projects.
  • Keeps OU purely for B2B and organizations.
  • No forced root OU.
• Cons:
  • Changes the core model. Today every resource must have an OU, which is enforced down to database constraints.
  • The sharing model would need an initial grant from something that is not an OU.
  • Too large a change for a first iteration.
• Decision: kept as the possible long-term target, reached from option 3 by migration (see question 8).

Earlier variants also considered:

• A tag kept only in an external management system, with no ThunderID change. It can't be enforced, and direct API, MCP and GitOps use bypass it.
• A separate PROJECT_ID scoping dimension next to DEPLOYMENT_ID. It largely duplicates OU ownership once B2B lands.
• An OU flag that marks project OUs. It was made unnecessary by treating every root OU as a project.

Questions for Community Input

1. How to handle the non OU bounded resources, by the current solution they will become deployment level resources automatically.
2. For the Management APIs do we need to support both OU ID and project ID in the request bodies? (because for non b2b scenarios CP admins don't need to know about the OU concept)
3. Can each project admin can view or edit the organization level resources (non ou bounded resources)
4. In the run time do we need to carry the project information without the project concept in there. (eg: we can still have the project name or the id as a label)

[Malith-19]

Update: outcome of the 19 Oct design sync

We refined option 3 ("a project is a root organization unit") in a design sync. This comment records what we agreed and what is still open.

Agreed

1. A project is a first-class record, backed by one root OU.

• A new project management API creates, reads, updates, lists and deletes projects.
• Projects are stored in their own table, which records each project's root OU.
• Creating a project creates its root OU and links the two. A project has exactly one root OU in this iteration.
• Resources keep referencing organization units only. No resource stores a project ID; a resource belongs to a project through its OU.
• Creating a root OU directly is no longer possible. A root OU only comes into existence by creating a project.

2. Control plane APIs take a project ID.

• Every configuration-time operation on resources inside a project carries the project ID in the request.
• The control plane checks that the caller may act on that project, resolves the project's root OU, and continues with the existing OU-based logic.
• Creating a sub-OU takes the project ID, plus the parent OU ID when the new OU is not directly under the project's root.

3. The data plane takes OU IDs only.

• The data plane does not use the project table.
• The OU comes from the request and is authorized against the caller's token, the same way B2B delegated administration works.

4. One codebase, plane-specific behavior.

• The control plane and data plane are built from the same code (see [Design Discussion] Separate ThunderID into a Control Plane and a Data Plane #4290).
• How the OU scope of a request is resolved differs by plane: from the project ID in a control plane build, and from the caller's token in a data plane build.
• This is fixed per build, not a deployment-time setting.
• The resolution has to apply in the service layer too, not only at the HTTP edge, because one service can create or read resources through another.

5. Project access is decided per request.

• A management token does not carry a project.
• One caller can work across several projects with the same token, for example an AI agent using MCP tools that creates two projects and then adds a resource to each.
• So the control plane asks, for every request, whether the caller may act on the given project. That decision point is pluggable, so a deployment can delegate it to an external authorization service.

6. Listings are scoped automatically, without an ouId filter.

• Listing logic keeps working on OU IDs internally. Only the source of the OU differs per plane:
  • Data plane: the caller's token decides which OU's resources are listed, as in B2B. An administrator of OU A sees OU A's resources.
  • Control plane: the project ID in the request is resolved to the project's root OU, and the listing is scoped to it. (This needs to be finalized on how we provide the project id)
• Listing APIs therefore do not need a separate ouId filter parameter.

7. Resources that are not OU-bound stay outside projects for now.

• Flows, notification senders, translations and server configuration remain deployment-level.
• To reuse one of them across projects, define it at deployment level.
• The B2B work is expected to make these OU-bound later, at which point they move into projects. There is no cross-project sharing in this iteration.

8. Option 4 remains the long-term direction. (One project can have resources directly without the OU and it also can have OUs)

• A project as its own construct, possibly with several root OUs, is still the target.
• Introducing the project table now keeps that path open: moving to option 4 changes how projects relate to OUs, not how resources are stored.

Still open

1. Same ID or different IDs. Should a project's ID be the same as its root OU's ID?
   • Same: one ID for developers to remember, but the separation would have to be undone for option 4.
   • Different: the two concepts stay apart from day one. Developers who never use sub-OUs only ever see the project ID.
2. Project access without an external authorization service. How is project access decided in a deployment that has no external service? A local policy, for example role assignments scoped to a project, is one option.
3. Which resources must live in a project. For integrations that organize their own work into projects, resource servers, applications and agents are the likely candidates. This is still being confirmed.
4. Sub-OUs in the control plane. How a control plane request targets a sub-OU inside a project, for example to list that sub-OU's resources, when the scope comes from the project ID.
5. Console experience. Where the project selector lives, and how the Console moves between a project and its sub-OUs.
6. How to get the project ID in CP To filter the resources we need either OU ID or Project ID. In CP we are honoring the project ID so, it should be derived in somehow to proceed.

Next steps

• Draft the project management API and the project table.
• Prototype the plane-specific OU scope resolution on users and groups, inside the package that already handles B2B access control, to confirm it can be done in one reusable place.

[Malith-19]

Final Solutions considered

1. Project is a collection of OUs

Pros

• Easy to implement as project is a new data model.

Cons

• Since project can have multiple OUs mapping with other products will be an issue as we need to pick default OU when someone creates a resource in a project in other product.

2. Project can only have one root OU

Pros

• Previous OU conflicting issue is not there.
• Easy to implement.

Cons

• Developers still use the OU ID when performing the operations.
• They need to aware about both project and OU concept but when they performing mgt operations they can't use the project IDs.

3. Project can only have one root OU and can use project ID

Pros

• Developers don't need to know about the OU concept unless they have hierarchical use case.

Cons

• Handling both project id and the OU id will be tricky in the management operations.
• CP/DP separation is also another complexity as project concept will not be present in the DP as a first class.

4. Resources can created under OU or project

Pros

• Exact 1:1 mapping with the other products.

Cons

• Resources are now owned by two types. 1. Project or 2. OU
• Implementation will be complex.

[Malith-19]

We had another discussion on finalizing the solution and addition to the proposed 4 solutions we have looked in to the proxy approach on solving the project ID mapping to the OU ID. Basically this proxy will be a separate service and thunderID will not be aware about the project concept.

Issues with the proxy approach

• Proxy will handle the APIs but from the UI we will still need to handle it from the product for supporting the project concept.
• Proxy will add additional service maintenance and additional hop to the whole flow.
• MCP tools also a new complexity to talk to the proxy rather than thunderID.
• Ensuring the trust between other product -> Proxy -> ThunderID will be a additional implementation step.

Due to above reasons we are in favour of proceeding with solution 2 in the above proposed solutions as it include the freedom for the product to extend it to any other solution in the future.

In the DP there will be a zero changes, and only CP will start to support the ProjectID and when users sends the projectID it will do the operation in the respective root OU and sending the OuId is optional. For any subOu related operations they have to send both projectId and the OuId.

[Malith-19]

Proposed UI for the projects

Project List

Project switch

Project creation wizard

Project details

Delete confirmation

@jeradrutnam @savindi7 @NipuniBhagya Appreciate your feedback on this.

[savindi7]

Hey @Malith-19 ,

Let's use the components coming from Oxygen UI once the project feature related components are finalized..