# Integrate OIDC behind a BFF

Bind public callbacks, trusted proxy transport, native SDK challenges and local completion.

Connect a browser or Capacitor client through a BFF while keeping the provider
validation, account resolution and local session boundaries explicit. This guide
uses Foundation 0.19.0; the exact API contract is in [external login](/foundation/0.19.0/guides/oidc-login/).

## Establish the topology first

For example, the browser reaches `https://app.example.test` and the BFF proxies
`/api/*` to a private API. Configure that public origin and `/api` prefix on both
`OidcProvider` and `OidcBffOptions`. The private handler still matches
`/auth/oidc/callback/{providerId}` after the BFF strips `/api`.

Register the exact public URL with the provider:
`https://app.example.test/api/auth/oidc/callback/google`. The Microsoft and Apple
profiles use their own final provider ID. Register Google's/Apple's client IDs and
Microsoft's exact tenant deliberately; Foundation does not configure consoles or
accept arbitrary Microsoft directories.

## Authenticate the BFF-to-API transport

Install `UseFoundationOidcBff` before authentication on the protected proxy branch.
Its mandatory delegate verifies actual server-to-server provenance, such as mTLS
or a checked service credential. It then applies only the fixed public origin and
prefix. A browser cookie, Origin or X-Forwarded-Host does not authenticate a proxy.

The delegate is a required application integration point. Do not copy a
`return true` implementation into a host. With conventional ASP.NET forwarding,
configure exact trusted proxies/networks instead of accepting all forwarded hosts.
See [request security](/foundation/0.19.0/guides/request-security/) for the rest of the private transport.

## Implement the product ports

| Port/state | Responsibility |
| --- | --- |
| `IOidcLoginIntentStore` | Durable, expiring, provider/client-bound intent and atomic one-use consumption across replicas |
| `IOidcLoginCompletion` | Current user/linking admission, stable external key, audit and local MFA/session handoff |
| `IOidcClientSecretSource` | Runtime confidential-client secret; Apple uses its signed client-secret JWT |
| BFF pending state | Original client/session binding and safe return context, not an anonymous UserId from JSON |
| Shared Data Protection | Correlation/state readability across API instances |

Persist/protect keys before relying on cross-instance callbacks. Follow
[secret protection](/foundation/0.19.0/guides/secret-protection/) and own the migrations for the product
stores. A valid provider identity is not an application session or tenant grant.

## Complete browser login

From a CSRF-protected product POST, create the trusted `OidcLoginContext` and call
`BeginAsync`. Relay the redirect, preserve Origin and the individual Set-Cookie
headers. Correlation, nonce and intent cookies belong to the BFF's public host.
Apple's form POST needs its cross-site SameSite behavior preserved.

The callback validates the full code flow, consumes the original intent and calls
the product completion port. Record a local client-bound result; the BFF redeems
that result and sets its own session cookies. Never put a provider token or unbound
ContextId into a redirect as a completion credential. Do not sign the upstream
provider principal directly into the application's session.

## Add native SDK sign-in

Configure a named `NativeClients` profile with exact `ValidAudiences` and approved
`ValidAuthorizedParties`. Start a server-issued challenge with `BeginNativeAsync`;
keep the original client binding in trusted BFF state. Give the SDK the raw nonce
or its lowercase SHA-256 hex according to the configured convention and the SDK's
actual behavior. Avoid double hashing.

Return the original challenge ID/raw nonce and the SDK ID token through the BFF
to `CompleteNativeAsync`. The bridge reuses current product completion, without
setting an API-host cookie or redirect. The existing web callback remains code-only.
A client-supplied nonce with no server-bound intent is not the same protection.

## Test before switching traffic

Exercise wrong Origin, forged forwarded headers, missing correlation, wrong
issuer/audience/nonce, another client's binding, concurrent redemption, expired
intent and changed product admission. Verify the complete local refresh/revoke
path separately. For a public production host, also verify real provider behavior,
proxy cookie preservation, key sharing and native app/domain associations.

Next: [local sessions](/foundation/0.19.0/guides/mobile-authentication/),
[fresh OIDC reauthentication](/foundation/0.19.0/guides/action-confirmation/#oidc-only-users-dedicated-reauthentication)
and [request presentation](/foundation/0.19.0/guides/presentation-localization/).
