Revisiting user type flexibility: multiple user types or a single type?

[ThaminduDilshan]

Problem Summary

ThunderID lets an admin define their own user schema through user types, and attach each type to an organization unit. The flexibility is useful, but it has a knock-on effect: a user type is now an input to almost every other configuration that deals with user attributes. Some of those configurations ended up per user type, some did not, and a few lifecycle rules around user types were never defined.

We are about to add more attribute driven configuration (SP claim URI mapping) and to extend the same model to agents (multiple agent types). Before that, it is worth deciding whether we keep multiple user types or restrict the system to one.

Why We Need User Types

The concept exists to separate genuinely different kinds of users in one deployment. Worth being concrete about where that separation is actually needed.

At configuration time. Different types need different attributes. An Employee has an employee ID and a Customer does not, and required and unique constraints differ between them. This is a real requirement and nothing else in the product expresses it.

At runtime. Two levels:

• Different types signing in with different attributes, for example employees with employee ID and password, customers with mobile number and password. Already achievable with separate login screens, either the user picking one or each type landing on its own page. No user type awareness is needed inside a flow.
• Multiple types signing in through one screen, where a single input accepts an employee ID, an email or a mobile number depending on who is typing. This is multi attribute login and should be a separate feature built on flow configuration or a new concept, not something user types have to solve.

On this reasoning, user types are needed at configuration time only, not at runtime.

Current Design

A user type is the schema for one kind of user: its attributes, which are required, which are unique, which one holds a credential, and whether self registration is allowed. Every user has exactly one type. Agents share the same implementation but are currently restricted to a single type named default.

Three bindings matter for the rest of this:

• A user type belongs to one organization unit. Users of that type must be in that OU or below it.
• User type names are unique across the organization, so two OUs cannot define types with the same name.
• A user record references its type by name, and the name is mutable.

Where user types are already considered, and where they are not:

Configuration	User type aware?	Notes
Application allowed user types	Flat list	Applied during registration and onboarding only
Application subject attribute	Yes	Map keyed by user type, validated against that type's schema
Token, assertion, userinfo, scope to claim config	No	One attribute list, validated against all allowed types combined
Flow inputs, including registration prompts	Partly	Provisioning prompts from the resolved type at runtime, which makes registration tolerable. Flow definitions themselves are not user type aware
Connection attribute mappings	Yes	Per user type, plus claim driven user type resolution
SP claim URI mapping	Not built	Same decision applies

Issues and Limitations

Current Concerns Related to Type Revisit (A)

1. Token and claim configuration is not per user type.

   • Attributes configured on an application are validated against the combined attribute set of all its allowed types, so an attribute belonging to only one type can be configured for all of them.
   • There is no runtime impact, since a claim is simply absent for a user who does not have the attribute. This is a configuration experience issue.
   • Related: when a type's schema changes, existing application configs are not revalidated. Stale attributes are only dropped the next time that application is saved.

2. Flow inputs are not user type aware.

   • Node inputs are fixed when the flow is defined, and nothing checks them against a user type's schema, either at design time or at runtime.
   • This becomes even harder since the flow doesn't have a reference to the applicable user types. A flow gets attached to a application and the application has the allowed user types. However there can be flows without an application too, hence need a generic solution.
   • Registration is partly saved by dynamic prompts during provisioning. Authentication is not: if two types share an attribute such as username, one login can match both types. But if the two types have different schemas for the same attribute (ex: email_address and email), it fails at runtime.

Other Related Issues (B)

1. Allowed user types are not validated during authentication.

   • The config was designed for registration, and authentication was not considered at the time.
   • The setting sits at application level and reads as generic access control, so it is reasonable to expect it to apply at login too.

2. A user type is referenced by name, and the name can change.

   • Renaming a type does not update the users or the configurations pointing at it: allowed user types, subject attribute mapping, connection mappings and user type resolution, flow node properties.
   • Should the reference be an ID or a handle instead? And should rename be allowed at all?
   • The rename surface also grows with every attribute config we add per user type.

Organization unit changes and one directional uniqueness are tracked in a separate discussion:

Impact on Planned Work

• Any new attribute driven configuration inherits the same decision. Per user type mapping will be required for all of them, SP claim URI mapping being the next.
• Multiple agent types would repeat every item above on the agent side.

Proposed Solution

Option 1: Restrict to a Single User Type

One user type per organization, the way agent types work today. Differences between kinds of users move to groups and roles.

Pros

• Attribute configuration has one unambiguous schema, so no per user type mapping is needed anywhere.
• Removes A.1, A.2 and B.1 by construction, and the uniqueness asymmetry with them.
• Consistent with the current agent type model, and a much smaller surface to maintain.

Cons

• Will not be able to provide user type flexibility which can model CIAM login cases to a greater extent.
• One schema for the entire organization, which is limiting when OUs represent genuinely different parts of the business.
• Per persona constraints are lost. A single schema can only mark an attribute required if it is required for every user.

Option 2: Keep the Current Design and Add Per User Type Mapping Everywhere

Accept that the user type is the unit of attribute configuration. Every configuration that names an attribute becomes a map keyed by user type, following the pattern already used by the application subject attribute and connection attribute mappings.

Token, assertion, userinfo and scope to claim configs get per type entries, flow inputs get per type entries, and SP claim URI mapping is built that way from the start.

Expand Concept Example

Application OAuth config, every attribute list keyed by user type:

{
  "allowedUserTypes": ["Customer", "Staff"],
  "token": {
    ...
    "idToken": {
        "userAttributes": {
          "Customer": ["email", "given_name"],
          "Staff": ["email", "employee_id"]
        }
    }
  },
  ...
  "scopeClaims": {
    "Customer": {
        "profile": ["given_name", "family_name"]
    },
    "Staff": {
        "profile": ["displayName", "employee_id"]
    }
  }
}

Note: Above example just shows the concept. Field names and exact structure has to be defined through the feature design process.

Flow keeps its nodes as they are, and gains a separate per user type mapping section. Node inputs stay generic, and the mapping resolves them to attributes per type.

{
  "handle": "basic-login",
  "name": "Basic Login Flow",
  "flowType": "AUTHENTICATION",
  "nodes": [
    {
      "id": "prompt_credentials",
      "type": "PROMPT",
      "prompts": [
        {
          "inputs": [
            { "identifier": "identifier", "type": "TEXT_INPUT", "required": true },
            { "identifier": "password", "type": "PASSWORD_INPUT", "required": true }
          ],
          "action": { "ref": "action_001", "nextNode": "authenticate" }
        }
      ]
    },
    {
      "id": "authenticate",
      "type": "TASK_EXECUTION",
      "executor": { "name": "CredentialsAuthExecutor" },
      "onSuccess": "end"
    }
  ],
  "inputConfig": {
    "identifierMappings": {
        "identifier": {
            "Customer": "email",
            "Staff": "employee_id"
        },
        "password": {
            "Customer": "password",
            "Staff": "password"
        }
    }
  }
}

Note: Above example just shows the concept. Field names and exact structure has to be defined through the feature design process.

Pros

• Fixes A.1 properly: each config validates against one concrete schema.
• Smallest conceptual change, and can be done one config surface at a time.
• Keeps user type flexibility intact.

Cons

• Config effort grows as types times config surfaces.
• Console needs a per user type section in many more places.
• Every new per type map widens the rename surface, making B.2 worse.
• Does not answer A.2: a flow not attached to an application has no types to key against.
• Leaves B.1 and B.2 untouched.

Option 3: Keep Multiple User Types, with a Shared Attribute List

Define attributes once at organization level. A user type then selects from that list and adds its own constraints (required, unique, credential, regex).

Attribute identity is global and referenced by an immutable handle: a type either includes a shared attribute or it does not, and cannot rename it. Other configurations reference the shared attribute list rather than a specific type, with per user type overrides available but not required.

Expand Concept Example

New organization level attribute list:

{
  "attributes": [
    {
        "handle": "email", 
        "displayName": "Email", 
        "type": "string"
    },
    {
        "handle": "given_name",
        "displayName": "First Name",
        "type": "string"
    },
    {
        "handle": "employee_id",
        "displayName": "Employee ID",
        "type": "string"
    }
  ]
}

Note: Above example just shows the concept. Field names and exact structure has to be defined through the feature design process.

Each attribute also carries an id like any other resource, but configurations reference the immutable handle, never the display name.

A user type then contributes constraints only, and no longer declares the attribute's type or name:

{
  "name": "Customer",
  "ouId": "01900000-0000-7000-8000-000000000001",
  "schema": {
    "email": { "required": true, "unique": true },
    "given_name": { "required": false }
  }
}

Note: Above example just shows the concept. Field names and exact structure has to be defined through the feature design process.

Application OAuth config stays flat, exactly as it is today:

{
  "allowedUserTypes": ["Customer", "Staff"],
  "token": {
    "idToken": {
        "userAttributes": ["email", "given_name"]
    }
  },
  "scopeClaims": {
    "profile": ["given_name", "family_name"]
  }
}

Adding employee_id to that list would be accepted even if neither Customer nor Staff included it, because the check is against the shared list. That is the weaker check noted in the cons.

Flow prompt node keeps today's shape, one definition for every type:

{
  "prompts": [
    {
        "inputs": [
            {
                "identifier": "email", 
                "type": "TEXT_INPUT", 
                "required": true
            }
        ]
    }
  ]
}

Note: Above example just shows the concept. Field names and exact structure has to be defined through the feature design process.

Configs that pick which attribute plays a role still stay per user type:

{
    "subjectAttribute": {
        "Customer": "email",
        "Staff": "employee_id"
    }
}

Pros

• Keeps per persona schemas.
• Per user type maps drop out of most configs, so the surface stops growing with each new attribute config.
• One attribute per concept, referenced by an immutable handle, which is the same fix B.2 asks for.
• B.1 is an independent fix either way.

Cons

• Reduces the surface, does not remove it. We still have to decide which level the abstraction belongs at, because it cannot be solved everywhere.
• Does not fix the core of A.1 or A.2. A config can still name an attribute a user's type does not include. The check only moves from "some allowed type has it" to "the shared list has it", which is weaker than what app configs get today. See question 5.
• Nothing stops two shared attributes for the same concept (email and email_address). It makes divergence deliberate rather than accidental, not impossible. This may not be a problem we need to resolve in this level as well. Something like this goes to the user store level configs where email is actually stored as email_address in one user store and email in another.
• Configs that pick which attribute plays a role stay per user type, so one screen mixes shared and per type sections.
  • Example: an app sets its ID token attribute list once, but the subject attribute stays per type because Customer identifies by email and Staff by employee_id.
• Larger change: a new concept in the API, console and declarative format, plus a migration of existing schemas.

Questions for Community Input

1. Is a user type a schema or an access boundary? If access were expressed through groups and roles, would allowed user types still be needed?
2. Does any deployment actually need more than one user type within a single organization unit?
3. How should any configuration point know which user types apply to it, so that an attribute reference can be validated against a real schema? An application has allowed user types, though it is validated against their union rather than per type. A flow has nothing. This question is orthogonal to the three options, and Option 1 is the only one that removes it, since there is a single schema.
4. For Option 3, should user attributes and agent attributes be separate shared lists? They barely overlap, an agent type carries things like modelProvider while a user type carries email, so one combined list would put agent attributes in an user type's attribute picker.

[ThaminduDilshan]

Scoped out other related concerns to a separate discussion: #5223

[VivekVinushanth]

Are we using the usertype to define anonymous users that has no credential? What impact it will have on the non-credential user types?

[ThaminduDilshan]

Meeting Summary, 1 September 2026

Participants:

TL;DR:

• Multiple user types stay. Option 1 is the least preferred and unlikely.
• User type should be a first class concept rather than a secondary one, so configuration stays qualified by type.
• No decision between Option 2 and Option 3. Option 2 is preferred, and its cost is the configuration experience of per type mappings in many places.
• Option 3 on its own does not fix the problem. A central attribute registry still needs configuration qualified by type, for example when two types share only a few claims.
• Governance such as account locking belongs to the type. A flow may restrict further but cannot grant what the type disallows.
• Next is to check whether the Option 2 experience can be made acceptable, and to define what belongs centrally versus at the user type, then reconvene.

Notes:

• Revisited why the concept exists. Organizations genuinely have different kinds of users, at a high level (employees, customers, partners) and a lower level within one of those (interns, permanent, contract). The product should address the high level and leave the lower level aside. Older guidance was to separate B2C and B2E into different tenants, so the open question is whether we support both in one deployment.
• The requirement holds even for pure B2C. Self signup customers and help desk or admin users have different identity requirements, and administrators inside a CIAM organization are a second type. Applications also need to restrict which types can log in, and registration needs separate flows per type.
• Agent types have the same requirement. Enterprise managed and externally onboarded agents differ in governance and attributes, and profiles vary by onboarding platform.
• Dual identity, the same person as both employee and customer, is real but uncommon. Preference is to keep them as separate identities unless there is a specific need to link. OOS for this discussion.
• The criticism was not of the concept but of how it is built. A type is defined from the ground up where it should inherit a base set and add on top, comparable to how others models it, with attributes agnostic of the type. Configuration time is where the experience breaks, not the concept itself.
• Global attributes without a type association do not work. An employee needs a department and a customer must not be prompted for one, so attributes still have to be grouped to a type.
• Policies such as account locking belong to the type rather than the flow, and apply regardless of which application is accessed.
• A flow may restrict further but cannot grant what the type disallows.
• Need to decide whether these policies belong on the user type at all, or in a separate control layer with user type, groups and roles as control points.
• Caution against overusing flows. Reusable flows shared across applications give consistency, but nothing enforces their use.
• User type selection at self registration is business logic. The application already filters the eligible types, and the business decides the path through separate portals, separate buttons, or an invitation that qualifies the type. Shipping multiple types by default should come with a default path that is changeable by config.
• The same attribute can carry different policy per type, for example mobile prefix restrictions for employees but not consumers (ex: employees can only use mobile no from certain vendor). Attribute name and format consistency is orthogonal to whether claims returned to an application must be qualified by type.
• If we're going ahead with option 3, custom attributes should register centrally on creation, so an admin never has to visit the registry first and the application side always refers to one place.
• The product should not dictate attribute names. Cosmetic aids such as email validation are fine, but knowing where email and mobile live for OTP and SMS should be solved with a system attribute mapping, starting from the application rather than forcing our dialect onto it.
• Token configuration could be defined globally per user type and overridden per application, avoiding the same token shape being defined across many applications.
• Option 1 was not formally discarded, but is the least preferred and unlikely. It could be revised to mean shipping one type now and onboarding multiple later.
• Option 2 is the preferred direction: user type must be first class and rooted in the code rather than secondary. Its cost is configuring type mappings in many places, which is the thing to look for.
• Option 3 drew the main objection. It makes attributes prominent and user type secondary, reproducing the older shape where claim configuration asks for attributes directly. The concern is that it does not solve the problem but changes the architecture to hide it, and could resurfaces later.
• A central registry also does not solve the token problem on its own. If a customer has 5 claims and an employee 10 with 2 in common, configuration still has to be qualified by type, so the registry is orthogonal to the user type concept.
  • Counterpoint: most attributes are common across types, so where both share the set the token is simply the same set. With a large registry and little overlap, you either flatten or select by type.
• No agreement was reached on Option 2 versus Option 3. The outcome was a shared understanding of the problem rather than a decision.
• Landing position is a hybrid: keep user type first class as in Option 2, with configuration qualified by type everywhere, while limiting how far attributes inside a type are allowed to diverge. This does not solve the UX problem by itself.
• On tokens, the attribute section should show what each type receives, either as two token views when an application allows both, or one view annotated with which type each attribute comes from. Two tabs or one view is a UX decision.
• Mandatory attributes cannot be defined centrally, since it depends on the type. Useful input to the registry question.

Action items:

• Explore the Option 2 UX. Ask why for each limitation, and find whether the user type question can be asked in a better way.
• Define the registry requirement for Option 3. What goes centrally and what is defined or overridden at the user type level, covering mandatory status, self registration enabled or disabled, and governance.
• Schedule another meeting to discuss this further with outcomes for the above two action items.