Bridging Legacy Identity to Modern SSO: An OIDC Bridge Pattern for Headless Commerce

Update (Sep 1, 2026): A reader pointed out that an earlier version of this post misstated how OrderCloud's role-based pricing actually works, describing the xp block on a Buyer User as what directly feeds price differentiation. That's not accurate. OrderCloud's price differentiation comes from its Price Scheduling feature, which assigns a Price Schedule to a product per Buyer or UserGroup; xp is inert custom metadata the pricing engine never reads. The post below has been corrected accordingly.

The starting point

• A legacy User Repository: a SOAP web service backed by a relational database, exposing operations like ValidateUser, GetUser, GetRolesForUser. It's the system of record for every user, and it's staying. Replacing it wasn't in scope.
• A new headless storefront, built on Next.js, with no authentication of its own yet.
• Sitecore OrderCloud, a hosted commerce-as-a-service platform, with its own native SSO integration mechanism: an OpenID Connect-based "login federation" feature it ships out of the box.

The pattern: one bridge, standards on both sides

• On one side, it's the only client of the legacy User Repository's SOAP API. Nothing else in the new architecture is allowed to call it directly.
• On the other side, it's a fully standards-compliant OpenID Connect provider, built on OpenIddict rather than a hand-rolled implementation. The protocol details (PKCE verification, JWT signing and rotation, authorization-code replay protection) are exactly the kind of security-critical code a mature, actively maintained library gets right far more reliably than a bespoke one. It speaks the same protocol every modern auth library (Auth0, Okta, Better-Auth, NextAuth/Auth.js, OrderCloud's own SSO feature) already knows how to consume, and exposes the normal endpoints: /authorize, /token, /userinfo, /jwks, and /.well-known/openid-configuration.

┌─────────────┐        OIDC          ┌────────────────┐        SOAP        ┌───────────────────┐
│  Storefront │ ───────────────────▶ │ Identity Bridge │ ─────────────────▶ │  User Repository   │
│  (Next.js)  │ ◀─────────────────── │  (OpenID        │ ◀───────────────── │  (legacy SOAP +    │
└─────────────┘   authorize/token    │   Connect       │   ValidateUser,    │   relational DB)   │
       │                             │   provider)     │   GetUser, roles   └───────────────────┘
       │  chained, silent redirect          ▲
       ▼                                    │  same OIDC provider,
┌─────────────┐                             │  reused for a second,
│  Sitecore   │ ────────────────────────────┘  independent client
│ OrderCloud  │        OIDC (its own SSO feature)
└─────────────┘

Why OrderCloud needs its own copy of the user at all

Why two chained OIDC flows, not one

1. Drop the storefront's own login flow and rely only on OrderCloud's SSO redirect. Rejected because the storefront needs its own session immediately, independent of OrderCloud, and needs full control over the profile-mapping logic (custom claims like membership roles) that only runs when the storefront's own auth library performs the OIDC exchange itself.
2. Mint an OrderCloud token server-side, using an admin/impersonation credential, with no second redirect at all. Rejected because that path is gated behind OrderCloud's Impersonation feature, which carries different semantics (an admin acting as a user, not a native login), and still wouldn't satisfy the "fresh data on every login" requirement without extra machinery bolted on anyway.

1. The storefront signs the user in against the Identity Bridge, a normal Authorization Code + PKCE flow, public client, no secret.
2. The instant that completes, the browser is bounced once, silently, through OrderCloud's own OIDC login entry point, which redirects back to the same Identity Bridge, this time as a second, confidential client. Because the browser still carries the bridge's own session cookie from step 1, this completes with no second password prompt.
3. OrderCloud's webhook lands back on the bridge asking "who is this," calling a create endpoint if it has never seen this user before, or a sync endpoint if it already has a Buyer User record for them. Either way, the bridge answers with a live profile, and OrderCloud creates or updates its Buyer User record accordingly.

What the endpoints actually look like

The bridge's own OIDC endpoints (ASP.NET Core + OpenIddict)

// The bridge is the *only* caller of the legacy repository's SOAP client.
public interface IUserRepositoryAuthService
{
    Task<AuthResult> ValidateCredentialsAsync(string username, string password);
    Task<UserProfile> GetProfileAsync(string userId);
    Task<IReadOnlyList<string>> GetRolesAsync(string userId);
}

// /authorize mints an authorization code if a session cookie already exists,
// otherwise redirects to a login page. Refreshes the profile from the User
// Repository on every hit (see "Freshness over caching" below) rather than
// trusting whatever was cached at the original login.
app.MapGet("/authorize", async (HttpContext ctx, IOpenIddictServerFeature oidc,
    IUserRepositoryAuthService repo) =>
{
    var principal = await ctx.AuthenticateAsync(CookieAuthenticationDefaults.AuthenticationScheme);
    if (!principal.Succeeded)
        return Results.Redirect("/login" + ctx.Request.QueryString);

    var username = principal.Principal.FindFirstValue("preferred_username");
    var freshProfile = await repo.GetProfileAsync(username);   // never trust the cookie alone
    var claims = ClaimsResolutionService.Map(freshProfile);

    return Results.SignIn(BuildPrincipal(claims), authenticationScheme: OpenIddictServerAspNetCoreDefaults.AuthenticationScheme);
});

// /token, /userinfo, /jwks, /.well-known/openid-configuration are all
// standard OpenIddict middleware; no custom code needed beyond
// declaring which claims land in the id_token vs. are userinfo-only.

The claims-mapping boundary

public record ResolvedIdentity(
    string Subject,        // stable legacy user ID, never username/email
    string Email,
    string GivenName,
    string FamilyName,
    IReadOnlyList<string> Roles);

public static class ClaimsResolutionService
{
    public static ResolvedIdentity Map(UserProfile profile) =>
        new(profile.Id, profile.Email, profile.FirstName, profile.LastName, profile.Roles);
}

OrderCloud's create/sync webhooks

// Every request from OrderCloud is HMAC-signed over the raw body; verify
// before trusting anything in it.
app.MapPost("/ordercloud/createuser", HandleCreateOrSyncAsync);
app.MapPost("/ordercloud/syncuser", HandleCreateOrSyncAsync);

async Task<IResult> HandleCreateOrSyncAsync(HttpRequest req, IUserRepositoryAuthService repo)
{
    var raw = await new StreamReader(req.Body).ReadToEndAsync();
    if (!VerifyHmac(req.Headers["x-oc-hash"], raw, hashKey))
        return Results.Ok(new { ErrorMessage = "Invalid signature" }); // see note below

    var payload = JsonSerializer.Deserialize<SyncUserRequest>(raw);
    var profile = await repo.GetProfileAsync(payload.Sub);

    // PUT is inherently create-or-replace against OrderCloud's Buyer Users
    // resource. Whether this becomes a new record or an update depends
    // entirely on which endpoint OrderCloud called, not on branching here.
    await orderCloud.UpsertBuyerUserAsync(payload.BuyerId, MapToBuyerUser(profile));

    return Results.Ok(new { Success = true });
}

What a synced Buyer User actually looks like

{
  "Meta": {
    "Page": 1,
    "PageSize": 20,
    "TotalCount": 2,
    "TotalPages": 1,
    "ItemRange": [1, 2],
    "NextPageKey": null
  },
  "Items": [
    {
      "FailedLoginAttempts": 0,
      "ID": "1000001",
      "CompanyID": "storefront-buyer",
      "Username": "test.account1@example.com",
      "Password": null,
      "FirstName": "Test",
      "LastName": "Account",
      "Email": "test.account1@example.com",
      "Phone": null,
      "TermsAccepted": null,
      "Active": true,
      "xp": {
        "LegacyUserID": "1000001",
        "Roles": [],
        "PriceRoles": []
      },
      "AvailableRoles": ["Shopper"],
      "Locale": null,
      "DateCreated": "2026-08-21T16:15:21.14+00:00",
      "LastActive": "2026-08-21T17:03:42.81+00:00",
      "PasswordLastSetDate": null
    },
    {
      "FailedLoginAttempts": 0,
      "ID": "1000002",
      "CompanyID": "storefront-buyer",
      "Username": "jordan.riley@example.com",
      "Password": null,
      "FirstName": "Jordan",
      "LastName": "Riley",
      "Email": "jordan.riley@example.com",
      "Phone": null,
      "TermsAccepted": null,
      "Active": true,
      "xp": {
        "LegacyUserID": "1000002",
        "Roles": ["Member"],
        "PriceRoles": ["Member"]
      },
      "AvailableRoles": ["Shopper"],
      "Locale": null,
      "DateCreated": "2026-08-20T21:57:56.793+00:00",
      "LastActive": "2026-09-01T12:57:04.177+00:00",
      "PasswordLastSetDate": null
    }
  ]
}

Prerequisites: OrderCloud objects that need to exist first

• A Buyer: the company or organization every synced Buyer User belongs to. Its ID is what the webhook handler's UpsertBuyerUserAsync call targets (/buyers/{BuyerId}/users/{id}).
• A Security Profile assignment on that Buyer: grants the baseline OrderCloud permissions every synced user gets. Nothing from the legacy repository's roles feeds into this directly; it's a flat, buyer-level grant, separate from whatever role or price data rides along as extra properties on the user record.
• At least one API Client with AllowSeller: true somewhere in the marketplace. It isn't referenced by ID anywhere else, but its mere existence is a prerequisite for Integration Events to mint the elevated-role webhook tokens described below. Easy to miss, and the error message you get without it doesn't point at the real cause.
• A buyer-facing API Client: either flagged AllowAnyBuyer: true or explicitly assigned to the Buyer above. Its ID is the cid query parameter on /ocrplogin in the sequence below.

Wiring OrderCloud up to actually call them

POST /v1/integrationEvents
{
  "ID": "identity-bridge-sync",
  "EventType": "OpenIDConnect",
  "CustomImplementationUrl": "https://<bridge-host>/ordercloud",
  "HashKey": "<shared secret, must match the bridge's own HMAC key exactly>",
  "ElevatedRoles": ["BuyerUserAdmin"]
}

• CustomImplementationUrl is a base path. OrderCloud appends /createuser or /syncuser itself when it actually calls out, so the bridge's two routes above just need to live under that same base.
• ElevatedRoles is what makes the webhook payload's OrderCloudAccessToken actually usable for the write: OrderCloud hands the webhook a token pre-scoped with these roles, and the handler's UpsertBuyerUserAsync call uses that token, not a separately held service credential, to write back to OrderCloud. Without BuyerUserAdmin here, that call would 403.
• HashKey is the shared secret both sides sign with. It's what VerifyHmac checks the incoming x-oc-hash header against in the handler above.

POST /v1/openidconnects
{
  "ID": "identity-bridge-sso",
  "OrderCloudApiClientID": "<the buyer-facing API client's ID>",
  "ConnectClientID": "ordercloud",
  "ConnectClientSecret": "<must match the bridge's own confidential-client secret>",
  "AuthorizationEndpoint": "https://<bridge-host>/authorize",
  "TokenEndpoint": "https://<bridge-host>/token",
  "AppStartUrl": "https://<storefront-host>/api/auth/ordercloud-callback?token={0}&ocRefreshToken={3}",
  "IntegrationEventID": "identity-bridge-sync"
}

1. After the storefront's own sign-in completes, the browser is redirected to {OrderCloud host}/ocrplogin?id=identity-bridge-sso&cid=<buyer-facing client ID>&roles=Shopper. This is OrderCloud's own fixed entry point; it isn't something the bridge or storefront implements.
2. OrderCloud redirects the browser to the AuthorizationEndpoint from the config above (the bridge's own /authorize) as the ConnectClientID client. The browser still carries the bridge's session cookie from the storefront's earlier sign-in, so this completes with no second login screen.
3. OrderCloud exchanges the resulting code at TokenEndpoint, server-to-server, using ConnectClientSecret (not PKCE; this is a confidential client, not a public one like the storefront's).
4. OrderCloud looks up the Integration Event referenced by IntegrationEventID, and, server-to-server with no browser involved, POSTs to CustomImplementationUrl plus /createuser or /syncuser, HMAC-signed with HashKey, carrying an access token scoped by ElevatedRoles. This is the call the two routes above actually receive.
5. Once that webhook call returns 200, OrderCloud finally redirects the browser to AppStartUrl, with its own access/refresh tokens filled into the {0}/{3} placeholders, landing the user back on the storefront already commerce-authenticated.

The storefront side (Next.js + a generic-OAuth-capable auth library)

export const auth = betterAuth({
  // No database. The bridge is the only identity store this app trusts.
  // Session state is a signed, stateless cookie instead.
  session: {
    cookieCache: { enabled: true, strategy: "jwt", refreshCache: true },
  },
  plugins: [
    genericOAuth({
      config: [
        {
          providerId: "identity-bridge",
          discoveryUrl: `${process.env.BRIDGE_ISSUER}/.well-known/openid-configuration`,
          pkce: true,
          // Re-fetch the profile on every login instead of caching the first one.
          overrideUserInfo: true,
          getUserInfo: async (tokens) => {
            const res = await fetch(`${process.env.BRIDGE_ISSUER}/userinfo`, {
              headers: { Authorization: `Bearer ${tokens.accessToken}` },
            });
            return res.ok ? res.json() : null;
          },
        },
      ],
    }),
  ],
});

Design decision: freshness over caching

Sign-out has to end the SSO session too

// idp-session.ts — a dedicated cookie for the one value RP-initiated logout
// needs, kept independent of whatever the auth library tracks internally.
import { cookies } from "next/headers";

const ID_TOKEN_COOKIE = "bridge_id_token";

export async function setBridgeIdToken(idToken: string) {
  const store = await cookies();
  store.set(ID_TOKEN_COOKIE, idToken, {
    httpOnly: true,
    sameSite: "lax",
    maxAge: 14 * 24 * 60 * 60, // matches the bridge's own session lifetime
  });
}

export async function getBridgeIdToken() {
  const store = await cookies();
  return store.get(ID_TOKEN_COOKIE)?.value ?? null;
}

export async function clearBridgeIdToken() {
  const store = await cookies();
  store.delete(ID_TOKEN_COOKIE);
}

getUserInfo: async (tokens) => {
  if (tokens.idToken) await setBridgeIdToken(tokens.idToken);

  const res = await fetch(`${process.env.BRIDGE_ISSUER}/userinfo`, {
    headers: { Authorization: `Bearer ${tokens.accessToken}` },
  });
  return res.ok ? res.json() : null;
},

// app/api/auth/bridge-logout/route.ts
export async function POST() {
  const idToken = await getBridgeIdToken();
  await clearBridgeIdToken();
  if (!idToken) return Response.json({ url: null });

  const url = new URL("/logout", process.env.BRIDGE_ISSUER);
  url.searchParams.set("id_token_hint", idToken);
  url.searchParams.set(
    "post_logout_redirect_uri",
    process.env.POST_LOGOUT_REDIRECT!,
  );
  url.searchParams.set("client_id", process.env.BRIDGE_CLIENT_ID!);

  return Response.json({ url: url.toString() });
}

export async function signOut() {
  await fetch("/api/auth/ordercloud-signout", { method: "POST" }); // end the commerce session
  const res = await fetch("/api/auth/bridge-logout", { method: "POST" });
  const { url } = await res.json();

  await authClient.signOut(); // still reliably clears the local storefront session

  if (url) window.location.href = url; // end the bridge's own session
}

Summary