---
title: Handle remote authentication failure
summary: Classifies and logs an IdP failure, then redirects to login instead of showing an exception page.
status: draft
owner: SAIF Framework Platform Team
last_reviewed: 2026-10-02
library: SAIF.NetCore.OIDC
reference_type: package
operation_id: OP-04
trigger: OnRemoteFailure event
---

# 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](../business-rules.md#br-oidc-10-remote-auth-failures-are-classified%2C-logged%2C-then-redirected)).
2. `context.HandleResponse()` ([BR-OIDC-10](../business-rules.md#br-oidc-10-remote-auth-failures-are-classified%2C-logged%2C-then-redirected)).
   - On branch: suppresses the framework's default exception-page behavior.
3. `_redirectService.Redirect(context.HttpContext, { "x-idp-err": "se" })` ([BR-OIDC-10](../business-rules.md#br-oidc-10-remote-auth-failures-are-classified%2C-logged%2C-then-redirected), [BR-OIDC-16](../business-rules.md#br-oidc-16-login-redirects-always-use-https-on-the-current-host)) — see [Redirect to login](op-08-redirect-to-login.md).

## Process flow

```mermaid
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.

## Related documentation
- [Operations and processes](../operations-processes.md)
- [Business rules](../business-rules.md)

> **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`