[Design Discussion] Per-Step Challenge Tokens for Flow Execution Security

[ThaminduDilshan]

Related Feature Issue

#2008

Problem Summary

The flow execution engine currently uses flowId as the sole identifier for continuing multi-step flows (authentication, registration, user onboarding). To improve the security posture of the flow execution API, we want to introduce a per-step challenge-response mechanism that ensures each step in a flow can only be continued by the client that initiated it.

This design proposes per-step challenge token rotation — a mechanism where the server generates a new cryptographically random token with every flow response, and the client must present it in the next request to prove continuity.

High-Level Approach

Introduce per-step challenge token rotation on the flow execution API:

• Introduce a challenge token that is generated server-side and rotated on every flow step.
• The server includes the token in each FlowResponse; the client must echo it back in the next FlowRequest.
• Only the SHA-256 hash of the token is stored in the database — raw tokens only appear in HTTP responses.
• If the token is missing or invalid, the flow is immediately invalidated.
• Token format: 32 bytes of crypto/rand, hex-encoded (64 characters).

Architecture Overview

The server generates a new cryptographically random challenge token with every flow response and expects the client to send it back in the next request. The token is rotated on every step, so even if the flowId is exposed, someone cannot continue the flow without the current challenge token.

Flow with challenge tokens

sequenceDiagram
    participant C as Client
    participant S as Server
    participant DB as FLOW_CONTEXT DB

    Note over C,S: Step 1 — Flow Initialization
    C->>S: POST /flow/execute<br/>{applicationId, flowType}
    S->>S: Generate flowId + challengeToken₀
    S->>DB: Store flowId + SHA256(challengeToken₀)
    S-->>C: {flowId, challengeToken: token₀, data: {...}}

    Note over C,S: Step 2 — Continue Flow
    C->>S: POST /flow/execute<br/>{flowId, challengeToken: token₀, action, inputs}
    S->>DB: Load flow, get stored hash
    S->>S: Verify SHA256(token₀) == stored hash ✅
    S->>S: Generate challengeToken₁
    S->>DB: Replace hash with SHA256(challengeToken₁)
    S-->>C: {flowId, challengeToken: token₁, data: {...}}

    Note over C,S: Step 3 — Invalid token presented
    C->>S: POST /flow/execute<br/>{flowId, challengeToken: token₀ (stale)}
    S->>S: SHA256(token₀) ≠ stored hash ❌
    S->>DB: Invalidate flow
    S-->>C: 400 Bad Request

Loading

Challenge token lifecycle

stateDiagram-v2
    [*] --> Generated: Server generates token₀<br/>on flow creation
    Generated --> Stored: SHA256(token₀) stored in DB<br/>Raw token₀ sent to client
    Stored --> Validated: Client returns token₀<br/>in next request
    Validated --> Rotated: SHA256(token₀) verified ✅<br/>New token₁ generated
    Rotated --> Stored: SHA256(token₁) replaces old hash<br/>Raw token₁ sent to client

    Validated --> Invalidated: Verification failed ❌
    Invalidated --> [*]: Flow removed from DB

    Stored --> Expired: Flow TTL exceeded
    Expired --> [*]: Cleanup job removes flow

Loading

Design decisions

1. Hash storage — The DB stores SHA-256(challengeToken). Even if the database is compromised, tokens can't be reconstructed.
2. Rotate every step — Each response includes a new token; the previous one is invalidated. This ensures a narrow window for each token.
3. Mandatory for continuation — If flowId is present (i.e., not a new flow), challengeToken is required. Missing or invalid → flow is invalidated.
4. Token in JSON body — The challengeToken is included in the JSON request/response body alongside flowId, consistent with the existing API structure.
5. Invalidation on mismatch — A challenge mismatch immediately deletes the flow from the DB, preventing repeated guessing.
6. InitiateFlow path — For the OAuth authorization flow, the challenge token is generated on the first Execute call (not during InitiateFlow). The pre-created flow has no token until the client calls POST /flow/execute, at which point the server generates and returns the first token.
7. Breaking change — Clients must be updated to include challengeToken. This is a required security upgrade.

Security Considerations

• Token entropy: 256 bits (32 bytes from crypto/rand) — computationally infeasible to guess.
• Hash-only storage: Only SHA-256(token) is persisted. Raw tokens exist only in HTTP responses.
• Immediate invalidation: Token mismatch immediately removes the flow from the DB.
• Rate limiting: Repeated mismatches should trigger flow-level rate limiting — after 3 consecutive failures, the flow is invalidated.

Impacted Areas

Backend

File	Change
flowexec/model.go	Add ChallengeToken to FlowRequest, FlowResponse, FlowContextWithUserDataDB, EngineContext
flowexec/handler.go	Extract and sanitize challengeToken from request; include new token in response
flowexec/service.go	Generate token on new flow; validate + rotate on continuation
flowexec/store.go	Store/update/read challenge_token_hash column
flowexec/queries.go	Update SQL queries for the new column
dbscripts/runtimedb/postgres.sql	Add CHALLENGE_TOKEN_HASH VARCHAR(64) to FLOW_CONTEXT
dbscripts/runtimedb/sqlite.sql	Same as above
system/utils/ or system/crypto/	Add GenerateSecureToken() and HashToken() utilities

Client SDKs

Package	Change
@asgardeo/javascript	Store received challengeToken and include it in subsequent requests
@asgardeo/react	Thread challengeToken through FlowContext / AsgardeoProvider
@asgardeo/nextjs	Same as React SDK

Alternatives Considered

Alternative 1: Single Secret Per Flow (Static Token)

Generate one secret when the flow starts and require it in every subsequent request.

Aspect	Assessment
Pros	Simpler implementation; one token for the entire flow
Cons	No rotation means a single exposure compromises the entire flow for its full TTL
Decision	❌ Rejected — rotating tokens provide strictly better security at minimal additional complexity

Alternative 2: HMAC-Signed Flow Responses

The server signs each response using HMAC with a server-side secret. The client returns the signature with the next request, proving receipt of the genuine response.

How HMAC works here

HMAC takes a secret key + message data and produces a fixed-size signature. The server computes HMAC(serverSecret, flowId + stepNumber + nodeId + timestamp) and includes the signature in the response. The client echoes it back, and the server recomputes to verify.

sequenceDiagram
    participant C as Client
    participant S as Server

    Note over S: Server holds secret key K<br/>(never shared with client)

    C->>S: POST /flow/execute {applicationId, flowType}
    S->>S: sig₀ = HMAC(K, flowId + step=1 + nodeId + ts)
    S-->>C: {flowId, signature: sig₀, data: {...}}

    C->>S: POST /flow/execute {flowId, signature: sig₀, action, inputs}
    S->>S: Recompute expected = HMAC(K, flowId + step=1 + nodeId + ts)
    S->>S: Compare sig₀ == expected ✅
    S->>S: sig₁ = HMAC(K, flowId + step=2 + nodeId + ts)
    S-->>C: {flowId, signature: sig₁, data: {...}}

    Note over C,S: ✅ No DB read needed to validate!<br/>Server just recomputes the HMAC

Loading

Why per-step challenge tokens are preferred

• Replay prevention complexity: The signed payload must include enough context to prevent replay across steps. Getting the recipe wrong opens gaps.
• Key management: The HMAC key must be shared across server nodes and securely rotated. A compromise affects all flows system-wide.
• Marginal benefit: The DB is accessed anyway to load the flow context for execution, so stateless validation doesn't save a round-trip.

Aspect	Assessment
Pros	Stateless verification; no additional DB column needed
Cons	Complex signed payload construction; key compromise affects all flows; DB accessed anyway
Decision	⚠️ Viable but complexity doesn't justify marginal benefit. Could revisit at scale.

Alternative 3: Traditional CSRF Tokens (Double-Submit Cookie)

Set a CSRF token in a cookie and require it in the request body.

Aspect	Assessment
Pros	Well-understood pattern
Cons	Cookie-based approach conflicts with the API-first design. The flow API uses XHR/fetch, not form submissions.
Decision	❌ Rejected — doesn't fit the architecture

Alternative 4: Client Fingerprint Binding

Bind the flow to client characteristics (IP address, User-Agent, TLS session).

Aspect	Assessment
Pros	Adds an additional signal for verifying client continuity
Cons	IP addresses change (mobile networks, VPNs). User-Agent can be spoofed. Creates false rejections for legitimate users.
Decision	⚠️ Could supplement other approaches but not reliable as a primary mechanism

Alternative 5: Short-Lived Flows + Aggressive Expiry

Reduce flow TTL significantly (e.g., 5 minutes for auth).

Aspect	Assessment
Pros	Reduces the token validity window
Cons	Poor UX — users may time out. Doesn't address the root cause.
Decision	❌ Rejected as standalone approach — may complement other mechanisms

Questions for Community Input

No response

[ThaminduDilshan]

Note:

Need to consider how this will work with link sharing flows. I.e. invite user registration, magic link, etc. One option is to include this token also in the invite url. This raises the following concerns.

1. Challenge token will be included as a query parameter
2. Will not be able to use the same invite link multiple times. Once clicked on it, that's done. If the user didn't complete the registration/ login, he will not be able to continue later

Alternatively we can avoid using challenge token for this exact step. I.e. challenge token will not be validated for the step just after generating the invitation/ url. But will be required for the steps before and after that.

But still we'll not be able to retry the same scenario (by clicking on the same url) once the challenge token is generated for the flow. For example, after clicking on the invite link, flow execution goes through the invite executor verification path. Step will be successful and goes to the next node. If the flow require additional inputs before completing, this will return a challenge token. If the user doesn't complete the registration and clicks on the invite link again after some time, flow execution will fail as a challenge token is generated for the flow.

Currently this works as the engine silently handles this. I.e. when the user clicks on the invite link, flow execution goes through the invite executor verification path. Step will be successful and goes to the next node. If the flow require additional inputs, engine will prompt for them. However flow execution will already be moved to the prompt step. If the user doesn't complete the registration and clicks on the invite link again after some time, engine will return the same prompt response as the inputs for the node are not satisified. However the engine has already been moved to this step and will not go through the invite verification path again even though the invite token is sent in the request.

However this is not a blocker for flows with one time links. I.e. magic link. If the user doesn't continue, it is a valid scenario to ask the user to reinitiate the flow again.

cc: @thiva-k @darshanasbg

[thiva-k]

Hi @ThaminduDilshan ,

+1 for the considered high-level approach.

For the invite flow, can't we skip the challenge token validation if the invite token is present in the request and it matches with the invite token in the runtime context for the flow. This way I believe concern 2 can be solved.

But this would require special-handling and validating of the invite token outside the executors, but can be considered as an option. We may need to improve the invite token logic if we are going with such approach(e.g. store the hash, generate random string instead of UUID, etc.)

[senthalan]

For the invitation flow, can't we consider them as two separate user flow.

1. Admin flow
2. User flow

In the first nodes of each of these flows, we can generate challengeToken. This will need engine level improvements. But rather than special casing this validation for a executor type or request parameters, I think this would be a better option.

[ThaminduDilshan]

Handling link-sharing flows (Invite, email verification, magic link)

Here's a suggestion to handle link sharing flows (admin invite, email-link self-registration, magic link, etc.).

Approach: Link token as persistent challenge substitute

Executors that generate shareable links already produce a cryptographic token embedded in the URL. We can extend the challenge mechanism to accept this link token as a challenge substitute at the step where the flow resumes from the link.

How it works:

1. When an executor generates a link, it stores SHA-256(linkToken) in the flow's runtime data alongside a flag indicating the next step accepts a link token as a challenge substitute.
2. When a request arrives with a valid linkToken (instead of challengeToken), the engine:
   • Verifies SHA-256(linkToken) against the stored hash
   • Discards any existing challenge token
   • Generates a new challenge token for subsequent steps
   • Returns the new challenge token in the response
3. The link token is not consumed on use — it remains valid as a re-entry key. This allows users to re-click the link (e.g., if they closed the tab, switched devices, etc.). Each re-click invalidates the previous challenge token and generates a fresh one (last-click-wins).
4. Once the flow progresses past the link-verified step, presenting the link token still works — the engine discards the current challenge token, generates a new one, and returns the current step's prompt. This preserves the re-click UX users expect from invite/verification links.
5. Standard challenge token validation continues for all subsequent interactive steps after re-entry.

This means:

• No special-casing per executor type — any executor can opt into this by setting the link token hash in its response
• Invite links remain re-clickable until the flow completes or expires
• Challenge token protection is enforced for all interactive steps (form fills, credential entry) after the link click
• Same-browser continuation with challengeToken still works as normal

[senthalan]

Rather than this, what if we can improve the engine to skip the challenge validation for some of executors ? we can identify which executor is going to be engaged and skip this. So we are not skipping the challenge validation based on the inputs rather the engaged executor.

[ThaminduDilshan]

Proposed approach is implemented with;

• Support mandatory per step challenge token for flow execution #2369
• Introduce runtime flow segmentation #2431