Skip to content
fabricators docs
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.

↑ ↓ to move↵ to openSearching fabricators .NET foundation v0.19.0