Skip to content

Handle remote authentication failure

Field Value
Operation ID OP-04
Trigger OnRemoteFailure event
Inputs context.Failure
Outputs Logged entry; 302 redirect with x-idp-err=se
Primary components ConfigureOpenIdConnectOptions.OnRemoteFailureAsync
Entry point src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Options/ConfigureOpenIdConnectOptions.cs L151–171

Steps

  1. Walk context.Failure and its inner exceptions. If any message contains "correlation" → log Warning. Else if any contains "message.state" → log Warning. Otherwise → log Error (BR-OIDC-10).
  2. context.HandleResponse() (BR-OIDC-10).
  3. On branch: suppresses the framework's default exception-page behavior.
  4. _redirectService.Redirect(context.HttpContext, { "x-idp-err": "se" }) (BR-OIDC-10, BR-OIDC-16) — see Redirect to login.

Process flow

flowchart TD
    Start([OnRemoteFailure fires]) --> Walk[Walk context.Failure and inner exceptions]
    Walk --> Correlation{Message contains 'correlation'?}
    Correlation -->|Yes| Warn[Log Warning]
    Correlation -->|No| State{Message contains 'message.state'?}
    State -->|Yes| Warn
    State -->|No| Err[Log Error]
    Warn --> Handle[context.HandleResponse]
    Err --> Handle
    Handle --> Redirect["Redirect to login with x-idp-err=se"]
    Redirect --> Done([302 to login app])

Failure and edge-case behavior

  • Correlation and message.state failures (typically caused by expired or replayed OIDC state, or a stale browser tab) are logged at Warning, not Error, because they are considered expected/benign*.
  • Every other failure is logged at Error and still results only in a friendly redirect — there is no distinct "fatal" failure path that surfaces to the end user as an error page.

Note: Statements marked with * were inferred from code structure, naming conventions, or contextual evidence where direct confirmation was not available in source artifacts. Statements marked with ** could not be confirmed; treat as unknown until verified.

Sources

  • src/SAIF.NetCore.OIDC/src/SAIF.NetCore.OIDC/Options/ConfigureOpenIdConnectOptions.cs