Step-Up Contract Reference

This page is a lookup, not a guess. Types, paths, defaults, and constraints are verified against the BitzOrcasVNext mainline sources (contracts in src/Platform/Identity/BitzOrcas.Identity.Contracts/Identity/StepUp/, endpoint declarations under .../Identity.Application/Commands|Queries/, enforcement in src/Hosts/BitzOrcas.Api/StepUp/). Factor wire names are camelCase everywhere (totp, emailOtp), matching the StepUpFactorWire conversion contract.

Endpoint list

The three challenge-loop endpoints carry a skip-interception marker so they never recurse. The management commands and queries additionally implement delegation-sensitive semantics: impersonation sessions cannot edit policy on behalf of the impersonated user.

Challenge and verification contracts

Start a challenge (StepUpChallengeResponse):

// Request body: the purpose must hit the frozen catalog (permission code or declared purpose).
{ "purpose": "identity.user.remove" }

// 200 response: factor set = policy-allowed set intersected with the user's current capabilities.
{
  "challengeId": "9fJ2vQ8rT3wL5nX1cZ7bA0dK4mH6pS2yE8uG1iO5aB3",
  "expiresInSeconds": 120,
  "windowSeconds": 300,
  "factors": [
    { "type": "totp" },
    { "type": "emailOtp", "target": "l***@example.com" }
  ]
}

OTP delivery (StepUpOtpSendResponse): request { "challengeId": "…", "factorType": "emailOtp" }, response { "resendAllowInSeconds": 60 } — re-sending inside the window returns 429.

Verification (StepUpVerifyResponse): request { "challengeId": "…", "factorType": "totp", "code": "482913" }, response:

// stepUpToken is the re-authentication credential: 32-byte CSPRNG base64url,
// returned exactly once. Failed verifications consume attempts (5 per
// challenge at factory settings); exhaustion voids the challenge.
{
  "stepUpToken": "Ak7Qx2Wm9Rf4Tt1Lz8Nb0Vc5Yh3Jd6Pg2Se9Ua1Wr4X=",
  "purpose": "identity.user.remove",
  "windowSeconds": 300,
  "expiresAt": "2026-09-02T08:15:00Z"
}

Credentials replay on business requests via a dedicated header, named by the StepUp:TokenHeader setting (factory X-Step-Up-Token).

The three 403 ProblemDetails shapes

Every 403 is an RFC 9457 ProblemDetails with extension fields flattened onto the root. Why this deviates from the RFC 9470 §3 401 + WWW-Authenticate track: see concept, industry landscape.

// Shape one: guidance (type suffix step-up-required) — the frontend opens the dialog.
// Triggers: missing credential (GrantRequired) or expired window credential (GrantExpired).
{
  "type": "https://docs.bitzsoft.com/problems/step-up-required",
  "title": "Step-Up Required",
  "status": 403,
  "detail": "该操作需要二次验证。",
  "errorCode": "Identity.StepUp.GrantRequired",
  "errorType": "Forbidden",
  "purpose": "identity.user.remove",
  "factors": [{ "type": "totp" }, { "type": "emailOtp", "target": "l***@example.com" }],
  "windowSeconds": 300
}

// Shape two: rejection (type suffix step-up-invalid) — no factors, preventing probing.
// errorCode is GrantInvalid or GrantPurposeMismatch.
{
  "type": "https://docs.bitzsoft.com/problems/step-up-invalid",
  "title": "Step-Up Invalid",
  "status": 403,
  "detail": "二次验证凭据与当前操作不匹配。",
  "errorCode": "Identity.StepUp.GrantPurposeMismatch",
  "errorType": "Forbidden"
}

// Shape three: policy unavailable (fail-closed, never a pass).
{
  "type": "https://docs.bitzsoft.com/problems/step-up-policy-unavailable",
  "title": "Step-Up Unavailable",
  "status": 403,
  "detail": "安全策略暂不可用，操作已被拒绝。",
  "errorCode": "Identity.StepUp.PolicyUnavailable",
  "errorType": "Forbidden"
}

Full error table

Configuration keys (StepUp section)

Type StepUpOptions (StepUpOptions.cs), bound to the StepUp section and validated at host startup. Factory defaults are engineering suggestions, not external-standard clauses — tune them against observation data:

appsettings.json sample (equivalent to factory defaults):

{
  "StepUp": {
    "WindowDefaultSeconds": 300,
    "WindowCeilingSeconds": 900,
    "WindowTechnicalMaxSeconds": 86400,
    "ChallengeTtlSeconds": 120,
    "MaxAttemptsPerChallenge": 5,
    "OtpResendAllowSeconds": 60,
    "VersionKeySafetyPaddingSeconds": 60,
    "TokenHeader": "X-Step-Up-Token",
    "PolicySnapshotTtlSeconds": 60,
    "RoleMembershipTtlSeconds": 300
  }
}

Rate limits and storage keys

The four challenge-loop endpoints use dedicated sliding-window limits (section RateLimiting:StepUp; partition = tenant + subject + endpoint scope):

Redis keys are built by the unified cache-key builder as {app}:{env}:v1:stepup:…:

Known limitations

• The fido2 factor is a contract placeholder: enum and wire name reserved, admin UI and dialog do not render it, challenges never offer it — until the WebAuthn assertion path lands (planned).
• Factory baselines ship in two layers: the composition-root code declaration list carries one pilot purpose (operations.sql-masking.manage, mandatory + one-shot tickets), and every declared purpose passes a wiring check requiring a real endpoint behind the same permission code — a drift fails host startup. Demonstration-scope deployments additionally seed two policy-row-only purposes with audit-only rows as the rollout starting point (idempotent, never reverts progressed rows). Other purposes without a host row fall back to the declared baseline; baseline rows can be configured on the host “security baseline” page.
• When verification outlives the access token’s remaining lifetime, the frontend abandons the replay (retrying self-heals via the memory cache); tabs do not share credentials.