Skip to content

Step-Up Challenges

Step-up is Caracal’s way to pause a token exchange and require fresh proof before issuing a mandate for a sensitive resource.

Policy triggers step-up by returning a diagnostic such as {"step_up_required": "mfa"}. The STS converts that diagnostic into an interaction_required error with a challenge ID.

Step-Up Flow

sequenceDiagram
  participant App as App or agent
  participant STS as STS
  participant Policy as Active policy set
  participant Control as Console or Admin API

  App->>STS: Exchange for sensitive resource
  STS->>Policy: Evaluate request
  Policy-->>STS: deny with step_up_required diagnostic
  STS-->>App: interaction_required with challenge_id
  Control->>Control: Complete external proof
  Control->>STS: Mark challenge satisfied
  App->>STS: Retry exchange with challenge proof
  STS-->>App: Mandate

Components

Component	Responsibility
Policy	Decides when step-up is required.
STS	Creates the challenge, throttles failed attempts, and verifies challenge proof during retry.
Console or Admin API	Lists, inspects, and satisfies challenges after an external proof step.
SDK or OAuth client	Surfaces `interaction_required` so the application can guide the user or operator.

Challenge Lifecycle

State	Meaning
Created	STS issued a challenge for a specific zone, session, resource set, and challenge type.
Satisfied	A different approver or external proof completed the requirement.
Consumed	STS accepted the proof during retry and issued the mandate.
Expired or invalid	The challenge can no longer be used.

Design Guidance

Use step-up for high-risk resources, sensitive scopes, or unusual context.
Keep the proof step outside policy; policy should decide that proof is needed, not perform the proof.
Prevent self-approval for sensitive challenges.
Include enough diagnostics for the Console and audit views to explain the requirement.
Retry token exchange only after the challenge is satisfied.

Next Step

Read Mandates to understand what the STS issues after an exchange is allowed or satisfied.