On this page
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.
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 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 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, fresh OIDC reauthentication and request presentation.