Introduction

Social Login lets a shopper authenticate with an external identity provider — Google, Apple, Facebook, or any OpenID Connect (OIDC) provider — instead of an email and password. The provider issues a signed ID token to your application; Storefront API verifies that token and either logs the shopper in or creates a new customer.

When to use it

• You want to offer "Sign in with Google / Apple / Facebook" alongside the existing login and registerCustomer mutations.
• You already run an identity broker and want shoppers to reuse those credentials.
• You want to reduce password-reset volume for returning shoppers.

Social Login does not replace the existing login flow. Customers created through Social Login can still be migrated to email/password, and existing password customers can later be linked to a social provider. See Account linking and confirmation.

High-level flow

Three Storefront API operations are involved, called in order from your application:

1. socialLoginList lists the active providers configured in Centra, so you know which buttons to render.
2. socialLoginVerify validates the provider's ID token and return a short-lived, single-use nonce.
3. socialLogin returns the same LoginPayload as login after redeeming the nonce.

The split between socialLoginVerify and socialLogin exists so the application can prompt the shopper for confirmation (if required) after the ID token has been validated, but before any account changes are made.

Provider configuration

Providers are configured per store in the Centra back office. Each provider needs two values from the provider's own console:

• The issuer URL (the OIDC discovery root).
• The client ID registered with the provider.

See Providers for where to obtain these values for Google, Apple, Facebook, and Generic OIDC.

Providers can be toggled active/inactive in the back office; socialLoginList only returns active ones, so hiding a login button is a configuration change, not a release.

ID token requirements

The ID token your application receives from the provider must satisfy the following, otherwise socialLoginVerify will reject it with a generic login error:

• Signed with RS256 or ES256. Other algorithms are refused.
• Fresh. The token's iat must be within a ±30 second window of the server clock. Clients should request a new token rather than cache one.
• Single-use. Each ID token can only be presented once. A second attempt with the same token is rejected. The replay check is anchored to the token's own claims, so re-requesting a new token from the provider is always safe.
• aud matches the configured client ID for the provider.

Required claims

The ID token must contain:

Claim	Required	Notes
sub	yes	The provider's stable, unique user identifier.
email	yes	See the Apple and Facebook notes below.
email_verified	yes	Must be true.
given_name	optional	Mapped to the customer's first name on register.
family_name	optional	Mapped to the customer's last name on register.

email

email is required. Storefront API will reject the login if the claim is absent or empty.

• Apple may omit email for company or school managed Apple IDs.
• Facebook may omit email when the user signed up to Facebook with a phone number instead of an email address, or has no verified email on their Facebook account.

In both cases, the shopper will not be able to use that provider for Social Login until the provider has an email on file. Surface a clear error in your UI and offer the regular email/password flow as a fallback.

email_verified

email_verified is required and must be true.

Apple issues email_verified as false for company and school managed Apple IDs. These accounts cannot use Social Login.

For other providers the claim must be present and true.

Names on first authorization

Some providers, notably Apple, only return given_name and family_name on the shopper's first authorization and never again. If your application has those values from the OAuth response but they are not inside the ID token, pass them explicitly via SocialLoginVerifyInput.overrides:

mutation {
  socialLoginVerify(input: {
    providerId: "google-prod"
    idToken: "eyJhbGciOi..."
    overrides: { firstName: "Alan", lastName: "Turing" }
  }) {
    nonce
    confirmationRequired
  }
}

Overrides are only applied when the corresponding field is missing from the ID token, they will not overwrite a name the provider already supplied.

Provider timeouts

Storefront API will spend at most one second per outbound HTTP call to a provider for discovery, JWKS fetch, or any other verification step. A provider that routinely answers slower than that will cause socialLoginVerify to fail.

Account linking and confirmation

A shopper may already have a Centra customer at the email address returned by the provider. Three cases are handled automatically:

Pre-existing state	confirmationRequired	What happens
No customer at this email	false	A new customer is created and logged in.
Customer already linked to this provider + subject	false	The shopper is logged in to the existing customer.
Customer already linked to a different provider	false	The new provider is linked to the existing customer.
Customer exists but no social link yet	true	The shopper must confirm before anything is linked.

When confirmationRequired is true, show a confirmation explaining that the shopper's existing account will be linked to this social provider, and that their existing password may be invalidated — they will have to reset their password on next email/password login if they want to use it again.

Nonce lifecycle

The nonce returned by socialLoginVerify is:

• Bound to the current session.
• Single-use, and consumed if the login fails or succeeds. On failure, start again with a fresh ID token.
• Short-lived.

Error handling

All three operations return a generic error on failure ("list error" / "login verify error" / "login error").

Treat any error from socialLoginVerify or socialLogin as "the shopper could not be authenticated" and offer them the standard email/password flow or a retry.

Next steps

• Providers — where to obtain the issuer URL and client ID for Google, Apple, Facebook, and Generic OIDC.
• Implementation — the GraphQL calls in order, and a reference Auth.js integration.