[Design Discussion] Improve and Resolve User/Agent Type Handling

[ThaminduDilshan]

Related Feature Issue

#5436

Problem Summary

Note: This discussion originated from the ideation in #5219.

Main Problem

Currently user and agent types are first class, so everything that references an attribute has to be type aware. Even so, a deployment that doesn't need several user or agent types stil sees the same complexity.

Also some places don't qualify the type today.

• Flows: A flow's inputs read and write attributes of a type, but the allowed types sit on the application or agent the flow is attached to. So the flow can't validate its inputs on its own.
  • Not every flow has an application or agent. Ex: administration flows such as user onboarding.
  • Making the flow also type aware duplicates the list in the flow and the application, and needs validation between the two.
• Application and agent token config: It's a flat list validated against the union of the allowed types. Making it per type (D or E) needs a list of types to key on.

Related Concerns

• Types are referenced by name, so renaming one breaks every reference (Renaming a user type breaks existing users of that type #5329).
• The application's user type list only gates sign up. At sign in only agent types are checked (PermitsSubject).
• App onboarding by default selects every user type in the system once there are two or more.

High-Level Approach

Note: This assumes an application or an agent binds a single flow, discussed in #5494. Options continue the lettering from the earlier comment, which used A to E.

Entity types:

• User and agent types get an immutable handle, and every reference to a type uses it.

Flow:

• The flow holds the allowed user and agent types. The application and the agent drop theirs.
• A flow can only call a flow that allows all or a subset of its types. There's no runtime inference from the caller.
• A flow with a node that needs a type must have a list.
• Changing a flow's types is checked against the flows it calls and the flows calling it, not against applications or agents.
• Flow handle needs to uniquely identify a flow and it requires dropping flowType from the current unique key constraint.
• The organization unit keeps a single default flow, in place of one per flow type.

Allowed type validation:

• Sign in checks the subject's type against the running flow's list, in the authn provider manager where agent types are checked today.
• User type resolver will not be restricted to registration flows and can be used in any flow to resolve/select a single user type. Same applies to agent type resolver (when added).
• UserTypeResolver will no longer carry an allowedUserTypes property at the node level. It will not have any meaning when the allowed type is moved to the flow level.

Application and agent:

• They refer to their flow by handle and read the allowed types from it.
• Token config is keyed by the flow's types, split by user and agent. The client's own token (client credentials) stays flat.

Console:

• Flow onboarding and the builder ask who can use the flow: users, agents, and the types of each.
• Application onboarding also asks who can use the application: users, agents, and the types of each.
  • There are two choices: either application onboarding asks it always or asks only when it generates a flow (otherwise it shows an existing flow's types read only).
• The application's Flows tab merges into Access, which shows who can access, but will be read only.
• The agent shows who can access on its Flows tab or its Access tab, two choices.
• Token tabs show a type selector only when the flow allows more than one type.
• With one type in a category, no picker is shown for it, users and agents alike. Storage is per type regardless.

Migration Impact

• Existing user/agent types get a handle derived from their name, and references are rewritten from names to handles.
  • Due to the format constraints in handle, it won't always match the original name.
• An application's and an agent's flow reference, and a CALL node's flow.ref, change from a flow id to a flow handle.
  • Previously it had to be id due to the combined unique key constraint with flow type.
• An application's or agent's allowed lists move to the flow it binds. A flow bound by several with different lists is copied per distinct list, so none widens.
• An organization unit's per type default flows become one, the same way as an application's.
• UserTypeResolver's node level allowedUserTypes is removed. Its value narrows the migrated flow's list.
• A flat token list becomes one entry per type of the flow, dropping attributes that type's schema doesn't have.
• Sign in starts checking user types. A user whose type isn't in the list can sign in today and can't after.

Architecture Overview

1. Entity Types

Types are referenced by name today; the application's allowed lists, connection mappings, the subject attribute map, node properties and each user record. Renaming one breaks all of them (#5329).

POST /user-types
{
  "handle": "customer",
  "name": "Customer",
  "ouId": "<ou-id>",
  "schema": {}
}

• handle is immutable.
• handle will have the same format constraints as other handles in the system (e.g., lowercase, hyphen-separated).
• Every reference to a type uses the handle.
• Whether name becomes displayName is open, see question 1.

name is unique within its category today (UNIQUE (NAME, CATEGORY, DEPLOYMENT_ID)), so a user type and an agent type can share a name. Two choices for handle:

F. Unique within its category (recommended)

• Same as name today, so migration derives handles without clashes.
• A reference also needs the category, which I and K carry anyway.

G. Unique across the deployment

• A handle alone identifies a type, so a flat token map (J) works.
• A user type and an agent type with the same name get a changed handle during migration.

2. Flow

2.1 Allowed Types

AllowedUserTypes and AllowedAgentTypes in the application will be moved to the flow level, either as separate fields per category or as a single field keyed by category.

H. A field per category

"allowedUserTypes": ["customer", "employee"],
"allowedAgentTypes": []

• Today's field names, moved as they are.
• A new category needs a new field.

I. One field keyed by category (recommended)

"allowedTypes": {
  "user": ["customer", "employee"],
  "agent": []
}

• One field, with the same outer shape as the token config in K.
• A new category is a new key.

Per flow type:

Flow type	Allowed types	Empty means
AUTHENTICATION	Required, at least one user or agent type	Not allowed
CUSTOM	Optional	No type
ADMINISTRATION	Optional	No type. Ex: application deletion

• A flow with a node that needs a type must declare a list. A called flow doesn't get one from its caller.
• A node needs a type when its executor reads a type's schema (UserTypeResolver, ProvisioningExecutor, OUExecutor, AttributeUniquenessValidator), or when it prompts for an attribute. ExecutorMeta can flag those executors, next to SupportedFlowTypes.
  • We can even say an executor requires type if it expects some input that relates to a schema attribute.

2.2 Flow References

• The application, the agent and a CALL node refer to a flow by handle.
• Today the application stores authFlowId, and takes authFlowHandle only at import. A CALL node's flow.ref is a flow id, including in the bootstrap resources.
• A handle reference needs flow handles unique per deployment. They're unique per flow type today.

2.3 Organization Unit Default Flow

• The organization unit keeps a single default flow, in place of one per flow type (authFlowId, registrationFlowId, recoveryFlowId and so on).
• An application that follows the organization unit's flow takes its types from it.

2.4 Full Example, with I

PUT /flows/{flowId}
{
  "handle": "customer-experience",
  "name": "Customer Experience",
  "flowType": "AUTHENTICATION",
  "allowedTypes": {
    "user": ["customer", "employee"],
    "agent": []
  },
  "nodes": [
    {
      "id": "call_registration",
      "type": "CALL",
      "flow": { "ref": "employee-signup" },
      "onSuccess": "auth_assert"
    }
  ]
}

Type values are type handles, and flow.ref is a flow handle.

3. Flow Validation

When a flow calls another, the calling flow's list must cover the called flow's list, whatever the flow types. Ex: an AUTHENTICATION flow calling a CUSTOM one, or a CUSTOM flow calling an AUTHENTICATION one. There's no runtime inference.

Ex: customer-experience allows customer and employee, and calls three flows.

Called flow	Its allowed user types	Result
employee-signup	employee	Valid
recovery	customer, employee	Valid
partner-signup	partner	Rejected, customer-experience doesn't allow partner

• While a called flow runs, its own list is what's checked. Ex: inside employee-signup a customer can't register, even though the caller allows customers.
• A flow called from several flows can only allow what all of them allow.
• The check runs at any depth. GetReachableCallTargets already walks the chain and visits each flow once, so a cycle doesn't loop. In a cycle every flow ends up with the same list.

Changing a flow's types:

Change	Check
Remove a type from a calling flow	Fails if a flow it calls allows that type
Add a type to a calling flow	None
Remove a type from a called flow	None
Add a type to a called flow	Fails if a flow calling it doesn't allow that type
Remove a type from a flow an application or agent binds	None. The application keeps a stale entry, which is never used
Add a type to a flow an application or agent binds	None. The token tab shows the type with no attributes

• The checks against calling flows go through the resource dependency registry. The flow service already reports flows that reference an IDP or a notification sender, so a flow referencing a flow is one more case.
• The builder's error offers to add the missing type to the calling flow.
• Validating a flow's prompt inputs against its types can come later, not in the first cut.
• Same rules for agent types.

4. Allowed Type Validation at Runtime

• Today the engine passes the allowed types to the authn providers only in authentication flows, and takes them from the application. The running flow's list is passed in every flow instead.
• checkSubjectAllowed in the authn provider manager already rejects an agent whose type isn't allowed, right after a provider resolves the subject. PermitsSubject returns true for every user. The change is to check user types there as well.
• It runs for every provider below the graph, so a flow author can't leave it out. The subject's category is known by then, so users and agents need no separate handling.
• It's a membership check on a list carried on the context, the same as for agents.
• UserTypeResolver works in any flow, not only registration. It resolves or prompts for one type from the flow's list, and the picked type narrows the check to that one type. Same for an agent type resolver when there is one.
• OUExecutor and ProvisioningExecutor read the running flow's list where they read the application's today.

5. Application

Covers users and agents signing in to the application.

• flow is the flow's handle. No allowedUserTypes or allowedAgentTypes.
• On save, the application reads the flow's types and validates each entry against that type's schema.
• A type added to or removed from the flow later needs no check on the application, see section 3.

5.1 Token Configuration

Two shapes for the per type lists:

J. One map keyed by type

"attributes": {
  "customer": ["email", "given_name"],
  "default": ["name"]
}

• Flat, but only safe with G. With F, a user type and an agent type can share a handle.

K. Keyed by category, then type (recommended)

"attributes": {
  "user": {
    "customer": ["email", "given_name"],
    "employee": ["email", "given_name", "employee_number"]
  },
  "agent": {
    "default": ["name"]
  }
}

• Works with F or G, and matches allowedTypes in I.
• Same shape for the access token, ID token, user info and assertion.

With one category and one type, the tab is the flat list as today, stored under that type.

With several user types, it's D or E from the earlier comment, yet to be picked.

With agents allowed as well, two ways to separate them.

L. Both categories in the type selector

• Each category lists its types. A category with one type shows as the category alone, users and agents alike.
• The other category is hidden when the flow allows only one.
• User and agent attributes barely overlap, so switching between them swaps the whole chip list.

M. Issued to first, then the type (recommended)

• Reuses the "Issued to" list on the agent's Tokens tab.
• The list is hidden when the flow allows only one category, and the type selector when a category has one type.

For E, L adds the agent types as extra columns, and M shows a matrix per category.

5.2 Full Example, with I and K

PUT /applications/{id}
{
  "name": "Customer Portal",
  "flow": "customer-experience",
  "assertion": {
    "attributes": {
      "user": {
        "customer": ["email"],
        "employee": ["email", "employee_number"]
      }
    }
  },
  "inboundAuthConfig": [
    {
      "type": "oauth2",
      "config": {
        "token": {
          "accessToken": {
            "userConfig": {
              "attributes": {
                "user": {
                  "customer": ["email"],
                  "employee": ["email", "employee_number"]
                },
                "agent": {
                  "default": ["name", "modelProvider"]
                }
              }
            },
            "clientConfig": {
              "attributes": ["ouId"]
            }
          },
          "idToken": {
            "attributes": {
              "user": {
                "customer": ["email", "given_name"],
                "employee": ["email", "given_name", "employee_number"]
              }
            }
          }
        },
        "userInfo": {
          "attributes": {
            "user": {
              "customer": ["email", "given_name"],
              "employee": ["email", "given_name", "employee_number"]
            }
          }
        }
      }
    }
  ]
}

• clientConfig is the application's own token from client credentials. There's no signed in user or agent, so it stays flat. Same for an agent's own token.
• scopeClaims follows the same shape, as noted under Next in the earlier comment.

6. Agent

Covers users and agents signing in through the agent, which is delegated mode. In client credentials mode the agent runs no flow, and its own token config stays flat.

• Same API changes as the application: flow, no allowed lists, and token config per K.
• Advanced loses Allowed User Types and Agent Sign-In.

Today the Tokens tab lists Agent and User under "Issued to", in delegated mode. With M it becomes This agent, Users and Agents, and Users gets the type selector.

7. Configuration Experience

7.1 Flow Onboarding

P. On the details step

• No extra step.
• A category with one type still shows a picker holding one option.
• We need to do some improvement to the UI to hide multiple type complexity when there's one category and/or type.

Q. An access step before the template

• Users, agents or both, then a picker per picked category. A category with one type skips its picker.
• Being before the template, templates can be filtered by what's picked, or adjusted later if needed.
• One more step.

R. Same as Q, in one step (recommended)

• The category and its types in one place, still before the template.
• A category with one type shows only its checkbox.

7.2 Flow Configuration

• "Who can use this flow" in the side panel edits the same fields as R.
• A few chips show, the rest sit behind "+N more", and edit opens a searchable picker.
• A category with one type shows only its checkbox.
• A CALL target allowing a type this flow doesn't is an error in the notifications panel, with an action to add the type here. The node is highlighted and save is blocked.

• The CALL node's properties show the referenced flow's types read only, and mark any this flow doesn't allow.

7.3 Application Onboarding

The user type block on the details step goes away, and with it the default of selecting every type. The type owned by the application's organization unit is preselected, else the first one.

S. Only when a flow is generated, on the security step

• Sign in options generate a flow, and its types are picked here.
• A pre-configured flow, or the organization unit's flow, shows its types read only.
• No extra step, but the block sits above a choice that can turn it read only.

T. Always, on an access step before security (recommended)

• Who can access is picked first.
• Sign in options then generate a flow with those types.
• A pre-configured flow that doesn't allow them is listed, but can't be picked, with the reason shown.
• Skipped when every category has one type. Users are allowed, agents aren't, and both can change on the flow later.

7.4 Application Access Tab

• The Flows tab is left with one picker and Access with only the application URL, so Flows merges into Access.
• Access shows the flow, who can access it (read only, linking to the builder), and the application URL.
• The Overview's flows card becomes one row.

7.5 Agent Access Tab

N. On the Flows tab

• The Access tab stays about the agent's own groups and roles.

O. On the Access tab, as for applications

• Same place as for applications, and the Flows tab goes away.
• Access then holds both what the agent can access and who can access through it.

Security Considerations

• Allowed types are enforced in the authn provider manager, below the graph, so a flow author can't drop the check by editing nodes.
• A called flow can't admit a type its caller doesn't, so the bound flow's list is an upper bound.
• A type added to a shared flow admits it to every application bound to it. The builder lists the bound applications before saving.
• A stale token entry for a type removed from the flow is never used, since the flow's list decides who gets in.
• An administration flow without a list can only hold nodes that need no type, and stays behind the same caller check.

Impacted Areas

• User and agent types: a new handle, and every reference to a type
• Flow definition, versions, management API and declarative flows
• Organization unit default flows
• Application and agent config, API and declarative resources
• Inbound client validation for token, user info, assertion, scope claims and subject attribute
• Flow engine, authn provider manager, UserTypeResolver, OUExecutor, ProvisioningExecutor
• Executor metadata, for nodes that need a type
• Resource dependency registry, for flows referencing flows
• Console: flow onboarding, flow builder, application onboarding, the application Overview, Access, Flows and Token tabs, and the agent Flows, Access, Advanced and Tokens tabs
• Migration for types, applications, agents, organization units and flows

Alternatives Considered

N/A. Each decision lists its options by letter, with one marked recommended.

Questions for Community Input

1. Should name on user and agent types become displayName? An earlier discussion agreed on an immutable handle and a displayName for every resource. For types it's a breaking change with a migration.

   U. Rename name to displayName

   • Matches the handle and display name split agreed earlier.
   • Breaks every client and declarative file that sets name.

   V. Accept both name and displayName as the display name

   • Nothing breaks, and each resource decides which one it uses.
   • Two fields for the same thing.

2. Should flow references refer by handle instead of the ID? Breaking change wil be the concern, but anyway we'll have to do it in certain places to address the overall concern.

3. Should the agent access tab be merged with the application access tab?

4. Should entity type handle be unique across all entity types or only within its category?