[Design Discussion] Revisit binding flows to an application and what the flow type is for

[ThaminduDilshan]

Related Feature Issue

#5493

Problem Summary

Currently an application binds a separate flow for each flow type. Authentication, registration, recovery and sign out each have their own config field.

• The application and the OU each carry one flow id per type, with enabled flags for registration and recovery.
• A client sends applicationId and flowType, and the type picks the binding.
• Call targets are walked on every application save so cross type bindings stay consistent.

Concerns;

• Revisiting user type flexibility: multiple user types or a single type? #5219 discusses on an approach to move allowed user types into the flow itself. Having multiple flow types for an app complicates the resolution logic for the app configs such as token attributes.
• A new flow type touches the application schema, the OU schema, resolution, validation, console and SDKs.
• One root flow branching into other types can't be expressed in a consistent and clear way and the root flow need to be one of the defined types.
• Two flows of the same type can't be attached in a clear and consistent way. One would have to pick a primary and the rest would be secondary, which adds complexity and ambiguity.
• The initiation guard is keyed on the type. Only authentication and sign out are guarded, and a call node crosses into a guarded type unchecked.
• A flow doing authentication, registration and recovery together (a single flow) has no type to be.

Two things to settle;

1. How an application binds to flows.

2. What the flow type is for.

   Currently it serves 3 purposes:

   1. Naming the application config field.
   2. Picking the flow to execute at runtime.
   3. Validating the flow's contents.

Note: where allowed user types live is tracked in #5219, so it's out of scope. Allowed agent types inherit the same decision.

High-Level Approach

Approach

• The application binds one flow:

  • The four flow id fields collapse into a single flowId.
  • An agent binds one the same way.

• The flow declares its own entry points:

  • START carries a list of entries in place of its single onSuccess.
  • An entry is a name and a target node, and one is the default. Any node can be a target, so an entry can lead to a CALL node or into inline nodes.
  • Umbrella flow and all in one flow are the same mechanism, and a designer can mix them.
  • Entry names are author defined. The name is the client contract. The console suggests signin, signup, recovery and signout rather than restricting to them.

• The client (at execution) names an entry instead of a type:

  • POST /flow/execute takes applicationId and an optional entry.
  • Omitting it runs the default.
  • This is what lets a client start registration directly, and what lets one flow offer two sign in paths.

• Three flow types remain, down from six:

  Type	What it is	Validated
  AUTHENTICATION	What an application or an agent binds	Must contain an AuthAssertExecutor
  CUSTOM	Any other flow	No
  ADMINISTRATION	Operational flow, gated on who may call it	Existing rules

  • REGISTRATION, RECOVERY and SIGNOUT stop being types.
  • Registration and recovery become entries, or CUSTOM flows an entry calls.
  • USER_ONBOARDING folds into ADMINISTRATION.

• Validation is limited, but remains on the flow itself:

  • Validation stays on the flow, not per branch, so there are no per entry rules to write.
  • The assertion can be inline or inside an AUTHENTICATION flow that is called.
  • A CALL to a CUSTOM flow is not validated.

Other Considerations

• Apps can bind sub flows directly as well:

  • A flow built as a sub flow can also be bound directly to an app or agent.
  • If a super app's root flow calls an employee flow and a customer flow, a management app can bind the employee flow on its own.

• flowType stops doing two of its three jobs:

  Job today	Moves to
  Names the config field	Gone. One flowId.
  Picks which flow runs	The entry name.
  Validates structure, constrains executors	Stays on the flow, three types instead of six.
  Changes executor behaviour at runtime	Mostly deleted, the rest becomes a node property.

• Why collapse the four user facing types into one:

  • The type doesn't separate capability. CredentialsAuthExecutor is required in both authentication and registration flows.
  • A call node already crosses types mid execution, so the type is not a property of an execution.
  • A flow doing sign in, sign up and recovery all has no type today, and that is a shape we want to allow.

• Each entry carries its own initiation policy:

  • Public, flow secret, attestation or redirect only.
  • ADMINISTRATION keeps its own gate.
  • Agents are unaffected; their execution already limited to direct or redirect based initiation.

Migration Impact

• Config migration, done for the author:
  • An application with several bound flows gets one generated AUTHENTICATION flow. Its START has one entry per old binding, each a CALL to the flow bound before.
  • Generated entries are named after the old flow type values, so AUTHENTICATION, REGISTRATION, RECOVERY, SIGNOUT.
  • An application with only an authentication flow keeps that flow, with onSuccess becoming the default entry.
  • Called flows become CUSTOM unless they already produce an assertion.
• Runtime, where the client sends flowType today:
  • A single entry flow is unaffected. The default entry runs whatever the client sends.
  • A multi entry flow needs the client to name the entry, which is a client change.
  • To avoid that change, /flow/execute accepts flowType as a deprecated alias for entry. Combined with the generated entry names above, existing clients keep working untouched.

Architecture Overview

Application binding

{
  "id": "<app-id>",
  "flow": "<customer-experience-flow>"   // flow handle
}

Entry points on the flow

{
  "handle": "customer-experience",
  "nodes": [
    {
      "id": "start",
      "type": "START",
      "entries": [
        { "name": "signin", "nextNode": "prompt_credentials", "default": true },
        { "name": "signin-partner", "nextNode": "partner_screen" },
        { "name": "signup", "nextNode": "signup_screen" },
        { "name": "recovery", "nextNode": "recovery_screen" }
      ]
    }
  ]
}

• Names are unique within the flow. Exactly one entry is the default.
• A CALL node takes an optional entry naming which entry of the callee to run. Absent means the callee's default.
• An existing flow migrates by turning onSuccess into a single default entry.

Shape 1: entries call other flows

Shape 2: everything in one flow

Flow execution

POST /flow/execute
{
  "applicationId": "<app-id>",
  "entry": "signup",
  "inputs": {}
}

• The application's flowId is read.
• The graph builder resolves entry to a start node, or the default entry.

The server default flow, used when an application has no binding, becomes a single AUTHENTICATION flow with sign in, sign up and recovery entries.

Configuration experience

• Drawing an edge from START adds a row to the entry list. The row starts unnamed and the flow stays invalid until it's named.
• Selecting START opens the node properties panel. A row is an entry name plus a target node, and a default chip marks the default, which can't be removed while it holds that role.

Correction: Above UI/ flow will not contain initiation policy. It will come from the attached application/ agent.

Flow onboarding experience

Flow creation changes too, since the composer asks for a type before a flow exists and templates are cut by type.

• The type picker offers AUTHENTICATION or CUSTOM.
• Today's per type templates become entry level starting points inside an AUTHENTICATION flow.
• New combined templates are needed, ex: sign in with sign up and recovery entries already wired.
• Maybe the UI templates can hold a supported category array (i.e. authentication, registration, recovery, etc) and provide filtering experience in the UI. For example, if someone wants to see registration flow templates, clicking on it will filter all templates that are registration or has registration embedded.

Executor behaviour

9 executors branch on ctx.FlowType. Most branches can be deleted rather than moved.

Deleted, because the condition is already expressed elsewhere;

• OAuthExecutor, OIDCAuthExecutor, OpenID4VPVerifyExecutor. Each arm is already gated on allowAuthenticationWithoutLocalUser or allowRegistrationWithExistingUser.
• AttributeCollector. It skips itself in a registration flow. It can determine this at runtime based on the user existence.
• AuthorizationExecutor. Dropping the type leaves the same behaviour.
• CredentialsAuthExecutor. Its registration arm checks the user doesn't exist then sets a credential, which IdentifyingExecutor and CredentialSetter already do.

Kept, as an explicit node property;

• ProvisioningExecutor, just in time behind a federated sign in against explicit provisioning.
• OTPExecutor and MagicLinkExecutor, recipient from an existing user's attribute against a value declared on the node.

Ideally these three can derive it from whether a user exists at runtime. If not possible, reusing allowAuthenticationWithoutLocalUser and allowRegistrationWithExistingUser is a possibility.

If the user detection can be centralized, interceptor is where to put it.

Validation

• An AUTHENTICATION flow must contain an AuthAssertExecutor, inline or through a CALL to another AUTHENTICATION flow.
• SupportedFlowTypes is executor metadata and keeps its shape, now restricted to the three remaining types. Its registration, recovery and sign out rules go.
• The reachable call target walk on application save is removed.

Storage

UNIQUE (HANDLE, FLOW_TYPE, DEPLOYMENT_ID) becomes UNIQUE (HANDLE, DEPLOYMENT_ID).

Security Considerations

• The guard is keyed on the flow type today, so registration, recovery and onboarding are not guarded at all. That gap looks accidental and is worth fixing regardless.
• A per entry policy also closes the call node hole, since the policy travels with the entry the client used.
• Administration flows stay off this surface, and entry names keep the same error behaviour as the flowId path.
• An unknown entry and an entry the caller may not start look the same in the response.

Impacted Areas

• Application and OU config, API, declarative resources and DB schema
• Flow definition, flow management API, flow composer and templates
• Flow execution API, where flowType becomes an entry name
• Graph builder, reachability and call node validation
• Executors that declare or branch on flow type
• Inbound client reference validation
• SDKs that send flowType
• Migration notes for existing applications, OUs and read only default flows

Alternatives Considered

1. A flow set resource

A new resource groups flows and holds the entry names. The application binds one set, and a call target has to be a member of the same set.

Payloads

// application
{
  "id": "<app-id>",
  "flowSetId": "<customer-experience-set>"
}

// flow set
{
  "handle": "customer-experience",
  "name": "Customer Experience",
  "entries": [
    { "name": "signin", "flowId": "<login-flow>", "default": true },
    { "name": "signup", "flowId": "<registration-flow>" },
    { "name": "recovery", "flowId": "<recovery-flow>" }
  ]
}

// execution, same as the proposal
POST /flow/execute
{
  "applicationId": "<app-id>",
  "entry": "signup",
  "inputs": {}
}

Flows stay small and a set is reusable across applications, which is also where the reusable token config from #5219 could live.

Against it: a new resource, console section and declarative kind, two hops to resolve a flow, and a set needed even for one login flow. A set is passive, so a landing screen that lets the user pick still needs a flow.

2. A pool of flows on the application

The application holds a list of flows with no names, and the client names the flow by handle.

Payloads

// application
{
  "id": "<app-id>",
  "flows": [
    "<login-flow>", "<registration-flow>", "<recovery-flow>"
  ]
}

// execution
POST /flow/execute
{
  "applicationId": "<app-id>",
  "flowHandle": "registration-flow",
  "inputs": {}
}

Simplest data model, but a handle is not unique on its own, clients would depend on admin side handles, and there is no default. Adding a default marker turns it into the flow set with fewer features.

3. Named entry points on the application

Replace the typed fields with a flows map keyed by entry name. This only addresses the schema growth. The application still binds several flows so call targets have to be reconciled, and a root flow still can't be expressed.

Questions for Community Input

1. Is AUTHENTICATION the right name for the one type an application or an agent binds? The flow it names now also covers sign up and recovery.

   • AUTHENTICATION (suggested): No new word and it already means "the flow an app binds". Understates the rest.
   • ACCESS: Covers sign in, sign up and recovery as ways to get access, but is a new term.
   • APPLICATION: An agent binds one too, so maybe need a AGENT type as well and with this apps and agents can't share the same flow.

2. Does an application need to disable individual entries on a shared flow? isRegistrationFlowEnabled does this today.

   Two paths if needed;

   • On the application, a list of enabled entry names. Keeps the flow reusable and is closest to today. The application then knows entry names, so renaming one breaks it.
   • On the flow, nothing to disable. An application needing a different set binds a different flow. Simplest, but pushes near duplicate flows.

   Suggested: on the application, since that is what the enabled flags already are.

3. Is sign out an entry next to sign in, or a separate binding? It's the one entry with no path from the rest of the graph.

[senthalan]

I like the overall idea, one concern is why we need to bring a new concept called entry here, can't that be normal action? So the flow won't differentiate the any type. Flow is a way of allowing the user/agent get into the application/agent. It can be through authentication, recovery or registration. We provide one flow to be linked to the application/agent. The first prompt node can have inputs for the primary option and other options can be call node from the link click.

[ThaminduDilshan]

Hi @senthalan,

Action is to pick a branch inside a prompt. Entry is about where the flow starts. With an action the client has to load the first screen and navigate from there, but we want to start registration directly.

I checked whether the action can be sent in the very first request so it auto selects. Inputs work that way, but the action doesn't (START node runs first and returns COMPLETE, and the engine clears the action on COMPLETE).

We can fix that, but there are few concerns.

• It works only when the first node is a prompt and all the options are in it. That's a limitation, we lose some flexibility in the flow design.
• There's a client migration impact as well, since the runtime contract changes.

[brionmario]

+1 to the idea.

Can't we use handle instead of name here? Also, why do we need the nextNode? Can't we infer that from the first node of the referenced flow right after the START.

{
  "handle": "customer-experience",
  "nodes": [
    {
      "id": "start",
      "type": "START",
      "entries": [
-        { "name": "signin", "nextNode": "prompt_credentials", "default": true },
+        { "handle": "signin", "nextNode": "prompt_credentials", "default": true },
        ...
      ]
    }
  ]
}

[ThaminduDilshan]

Hi @brionmario,

Currently handle is used for top level resources. I.e. flow, app, ou. Inside a graph we use ref for declared identifiers, like the action ref and the call node flow.ref. Entry is the same, declared in the graph and sent back by the client. So maybe ref is a better alternative than both.

{
  "handle": "customer-experience",
  "nodes": [
    {
      "id": "start",
      "type": "START",
      "entries": [
        { "ref": "signin", "nextNode": "prompt_credentials", "default": true },
        { "ref": "signin-partner", "nextNode": "partner_screen" },
        { "ref": "signup", "nextNode": "signup_screen" },
        { "ref": "recovery", "nextNode": "recovery_screen" }
      ]
    }
  ]
}

POST /flow/execute
{
  "applicationId": "<app-id>",
  "entry": "signup",
  "inputs": {}
}

On nextNode, entries are in the START node of the same flow, not in a referenced flow. Each entry points to a different node in the same graph. I.e. signin to the credentials prompt, signup to the registration branch, etc. So there's nothing to infer. Only the default entry is the node right after START, and that's covered by default: true.

[thiva-k]

Hi @ThaminduDilshan,

Two things that may need some consideration

• A session is currently grouped by whichever flow is running when it is established and the cookie is derived from that flow, but a call node switches the running flow, so Shape 1 and Shape 2 end up with different session scopes despite being presented as interchangeable. Concretely, a sign out entry in the root would not see a session established behind a call, and prompt=none would miss it too since the authorize endpoint resolves the session from the flow the app binds.

• For the /authorize call, the flow is started server side before the browser is redirected and nothing in the authorize request or the redirect can name an entry, so OAuth clients would always land on the default entry right?
  But there could be some use cases where we may need to drive certain flows based on the prompt parameter(e.g. prompt=create starts a registration flow)