Extend provider profile

Learn how to customize profile data from OAuth providers and customer payloads during external login.

Introduction

When users authenticate via external providers (Google, Facebook, or a custom SSO), Front-Commerce extracts a standard profile containing email, firstname, and lastname. However, you may need to:

• Extract additional fields from the OAuth provider's raw response (e.g., company, phone number, profile picture)
• Customize the customer creation payload sent to your e-commerce backend (e.g., add Magento2 custom attributes)

Front-Commerce provides two extension points for these use cases: Profile Transformers and Payload Transformers.

Profile Transformers

Profile transformers allow you to enrich the standard profile with custom fields extracted from the raw OAuth response.

Register a Profile Transformer

Use the registerProfileTransformer() method in your extension's onServerServicesInit hook:

extensions/my-extension/index.ts

import { defineExtension } from "@front-commerce/core";

export default defineExtension({
  name: "my-extension",
  unstable_lifecycleHooks: {
    onServerServicesInit(services) {
      services.ExternalLogin.registerProfileTransformer({
        name: "add-company-field",
        transform: (profile, { rawProfile }) => ({
          ...profile,
          company: rawProfile.raw._json?.organization,
        }),
      });
    },
  },
});

Profile Transformer API

The registerProfileTransformer method accepts an object with:

Property	Type	Description
name	string	Unique identifier for the transformer
transform	(profile, context) => EnrichedProfile | Promise<EnrichedProfile>	Function that receives and returns the profile

The transform function receives:

• profile: The current profile object (with email, firstname, lastname and any fields added by previous transformers)
• context: An object containing:
  • provider: The provider name (e.g., "google", "facebook")
  • rawProfile: The raw OAuth response with { provider, raw } structure

tip

Transformers are applied in registration order. Each transformer receives the profile enriched by previous transformers.

Payload Transformers

Payload transformers allow you to customize the customer creation payload sent to your e-commerce backend. This is particularly useful for Magento2 to add custom_attributes or extension_attributes.

Magento2 Only

This feature is currently only available for Magento2. Support for other e-commerce backends may be added in future releases.

Register a Payload Transformer

Use the registerPayloadTransformer() method in your extension's onServerServicesInit hook:

extensions/my-extension/index.ts

import { defineExtension } from "@front-commerce/core";

export default defineExtension({
  name: "my-extension",
  unstable_lifecycleHooks: {
    onServerServicesInit(services) {
      services.ExternalLogin.registerPayloadTransformer({
        name: "add-custom-attributes",
        transform: (payload, { profile }) => ({
          ...payload,
          customer: {
            ...payload.customer,
            custom_attributes: [
              ...(payload.customer?.custom_attributes ?? []),
              { attribute_code: "company", value: profile.company },
            ],
          },
        }),
      });
    },
  },
});

Payload Transformer API

The registerPayloadTransformer method accepts an object with:

Property	Type	Description
name	string	Unique identifier for the transformer
transform	(payload, context) => Record<string, unknown> | Promise<Record<string,unknown>	Function that receives and returns the payload

The transform function receives:

• payload: The current customer creation payload
• context: An object containing:
  • profile: The enriched profile (with all custom fields from profile transformers)
  • storeLoginContext: Store context with storeId, cartId, guestToken, orderId
  • user: The current Front-Commerce user object

Complete Example

Here's a complete example that extracts a company field from Google's OAuth response and adds it as a Magento2 custom attribute:

extensions/company-from-oauth/index.ts

import { defineExtension } from "@front-commerce/core";

export default defineExtension({
  name: "company-from-oauth",
  unstable_lifecycleHooks: {
    onServerServicesInit(services) {
      // Step 1: Extract company from the raw OAuth profile
      services.ExternalLogin.registerProfileTransformer({
        name: "extract-company",
        transform: (profile, { rawProfile, provider }) => {
          // Google stores organization in _json.hd (hosted domain)
          if (provider === "google") {
            return {
              ...profile,
              company: rawProfile.raw?._json?.hd,
            };
          }
          // Facebook might have it in a different location
          if (provider === "facebook") {
            return {
              ...profile,
              company: rawProfile.raw?._json?.company?.name,
            };
          }
          return profile;
        },
      });

      // Step 2: Add company to Magento2 custom_attributes
      services.ExternalLogin.registerPayloadTransformer({
        name: "add-company-attribute",
        transform: (payload, { profile }) => {
          if (!profile.company) {
            return payload;
          }
          return {
            ...payload,
            customer: {
              ...payload.customer,
              custom_attributes: [
                ...(payload.customer?.custom_attributes ?? []),
                { attribute_code: "company", value: profile.company },
              ],
            },
          };
        },
      });
    },
  },
});

TypeScript Support

Front-Commerce exports all the types you need for type-safe transformers:

import type {
  Profile,
  EnrichedProfile,
  RawOAuthProfile,
  ProfileTransformer,
  ProfileTransformerContext,
  PayloadTransformer,
  PayloadTransformerContext,
  StoreLoginContext,
} from "@front-commerce/core/external-login";