SAP Commerce Cloud: CDC Authentication

Features

• Login and registration via Gigya (custom forms or hosted Screen-Sets)
• Guest cart merge on login — existing cart items carry over to the authenticated session
• Password change, password reset, and email update flows
• Customer profile sync between CDC and OCC
• Address sync — OCC addresses are mirrored to the CDC profile
• Session expiration detection with automatic logout
• ASM (Assisted Service Mode) compatibility
• Drop-in Screen-Set components for Gigya's hosted UI

How It Works

The module sits between your storefront and SAP Commerce Cloud. When a user logs in through Gigya, the flow is:

1. User authenticates with Gigya — either through a custom form or a hosted Screen-Set
2. Gigya returns a JWT (id_token) along with a signature
3. The middleware exchanges the JWT for an OCC OAuth token — using SAP's CDC-enabled OAuth endpoint
4. OCC session cookies are set — the user is now authenticated with SAP Commerce Cloud
5. Guest cart is merged — if the user had items in their cart before logging in

For profile updates, changes go to CDC first, then sync to OCC. For addresses, OCC is the source of truth — addresses are mirrored to CDC for profile completeness.

Installation

Prerequisites

• An SAP Commerce Cloud instance with CDC (Gigya) integration enabled
• A Gigya API key for your site
• The SAP Commerce Cloud OAuth endpoint must accept Gigya JWT tokens (requires CDC configuration in Backoffice)

Add the module files

From the root of your project, run:

npx @vsf-enterprise/storefront-cli add-module sap-cdc -e sapcc

Follow the instructions in the command line to complete the installation. To verify, check that the apps/storefront-middleware/sf-modules folder contains a sap-cdc directory.

Set the API key

The module needs your Gigya API key to load the SDK. Add it to your environment variables:

Add to your .env file:

NEXT_PUBLIC_CDC_API_KEY=your-gigya-api-key

The module installer creates a cdc.config.ts file in your storefront where you can customise additional settings:

import { env } from '@vue-storefront/next';
import type { CdcConfig } from './utils/gigya-loader';

export function getCdcConfig(): CdcConfig | undefined {
  const apiKey = env('NEXT_PUBLIC_CDC_API_KEY');
  if (!apiKey) return undefined;

  return {
    apiKey,
    // javascriptUrl: env('NEXT_PUBLIC_CDC_SDK_URL'),
    // lang: 'en',
    // sessionExpiration: -2,
  };
}

Configuration options

Authentication Flows

Login

Registration

Password Change

Email Update

Changing the email is the most complex flow because the email is the login identity for both CDC and OCC.

Password Reset

The user enters their email, and the module calls Gigya's accounts.resetPassword. Gigya sends a password reset email with a link to the Gigya-hosted reset page. No OCC interaction is needed.

Address Sync

When a customer creates, updates, or deletes an address in OCC, the module syncs the primary address to CDC. This follows the Spartacus pattern — OCC is the source of truth for addresses, CDC gets a flattened copy for profile completeness. The sync is fire-and-forget; if it fails, the OCC address is still saved correctly.

Screen-Sets

Screen-Sets are Gigya's hosted UI forms for login, registration, and profile management. They're fully managed in the Gigya console — you don't need to build form UI yourself.

What gets installed

The module installer copies a Screen-Set login page alongside your existing custom login form:

app/[locale]/(auth)/
├── layout.tsx              # Auth layout (overwritten by the module)
└── login/
    ├── page.tsx            # Default custom login form (unchanged)
    └── page.screenset.tsx  # Screen-Set login page (new)

By default, the module uses custom forms — your existing login and registration pages are modified to use CDC hooks (useCdcLogin, useCdcRegister) instead of the default OCC hooks. This gives you full control over the form UI.

The Screen-Set login page is installed as page.screenset.tsx alongside your existing page.tsx as an optional alternative.

Switching to Screen-Sets

To use the Gigya-hosted login instead of the custom form, replace the contents of page.tsx in app/[locale]/(auth)/login/ with the Screen-Set version from page.screenset.tsx. The Screen-Set page renders the CdcLoginForm component, which loads the Default-RegistrationLogin Screen-Set from Gigya. You can customize the Screen-Set appearance and fields in the Gigya console.

Customising the Screen-Set ID

If you use a custom Screen-Set in Gigya, pass its ID via the screenSet prop:

<CdcLoginForm screenSet="My-Custom-RegistrationLogin" />

Hooks & Composables Reference

The module installs hooks (Next.js) and composables (Nuxt) that replace the default authentication functions:

During installation, the module automatically swaps the default hooks/composables for the CDC versions in your login, registration, personal data, and shipping details pages.

Middleware API

The module adds two namespaced middleware endpoints under api.cdc:

loginCustomer

Exchanges a Gigya JWT for an OCC OAuth token. Accepts:

• id_token — Gigya JWT
• UID — Gigya user ID
• UIDSignature — Gigya signature
• signatureTimestamp — Signature timestamp
• oldCartId — (optional) Guest cart ID for cart merge

logoutCustomer

Clears OCC session cookies, revokes the customer token (best-effort), and cleans up the cart cookie. Handles ASM sessions by resetting to anonymous without revoking the agent token.

Troubleshooting

Screen-Set shows a spinner indefinitely

The module waits up to 10 seconds for Gigya to initialize. If the spinner doesn't go away:

• Verify your API key is correct
• Check that the Gigya CDN isn't blocked by ad blockers or CSP headers
• Open the browser console for [SAP CDC] error messages

"API key is not configured" error

The NEXT_PUBLIC_CDC_API_KEY (or NUXT_PUBLIC_CDC_API_KEY) environment variable is missing or empty. Make sure it's set in your .env file and the app is restarted.

Cart items are lost after login

Make sure the login flow passes oldCartId. The custom form hooks (useCdcLogin, useCdcRegister) handle this automatically. If you're using Screen-Sets, the CdcLoginForm component also handles cart merge.

Session expired errors on profile update

CDC sessions can expire independently of OCC sessions. When this happens, the module automatically forces a logout and redirects to the login page. The user needs to re-authenticate.