JWKS Authentication Integration

The ESW SFCC Cartridge provides the capability to validate incoming webhooks using ESW’s public keys via JWKS (JSON Web Key Sets).

While the cartridge supports basic authentication, JWKS removes the need to manage static credentials and simplifies webhook security configuration.

JWKS Configuration

To configure JWKS authentication, ensure the following components are correctly set up in Business Manager (BM).

Custom Objects

Import Metadata

Import the custom object definitions:

\link_eshopworld\Metadata\meta\customobjects.xml

After import, the following custom object is created:

ESW_JWKS

This object stores the public keys retrieved from ESW and is used during webhook validation.

Jobs

Import Metadata

Import the jobs configuration:

\link_eshopworld\Metadata\jobs.xml

After import, the following job is available:

eswGetJwksJob

This job is responsible for fetching the latest JWKS keys from ESW.

Services

Import Metadata

Import the services configuration:

\link_eshopworld\Metadata\services.xml

After import, the following service is available:

EswGetJwksService

This service connects to ESW to retrieve the public keys used for webhook authentication.

Workflow Overview

Key Fetching

• The eswGetJwksJob calls the EswGetJwksService
• The service retrieves the latest ESW public keys
• Keys are stored in the ESW_JWKS custom object in SFCC
• These keys are reused during webhook validation

Screenshot Code Snippet – Stored JWKS Key (Custom Object)

The following represents the JWT Validation Key stored in the ESW_JWKS custom object, as shown in Business Manager.

JWT Validation Key:
{
  "kty": "RSA",
  "use": "sig",
  "kid": "ESW-KEY-001",
  "alg": "RS256",
  "n": "oahUI8z...",
  "e": "AQAB"
}

This key material is periodically refreshed via the eswGetJwksJob.

Webhook Validation Flow

When a webhook is received, the cartridge performs the following validation steps:

1. Checks the HTTP header:
   esw-authorization
   

2. Attempts to validate the webhook signature using the stored JWKS key
3. If validation fails:
   • Re-fetches the JWKS keys
   • Attempts validation again
4. If validation still fails:
   • Falls back to basic authentication (if enabled)
5. If authentication fails entirely:
   • An error response is returned to the webhook caller

Screenshot Code Snippet – Webhook Header

POST /onWebhook HTTP/1.1
Host: your-storefront.com
Content-Type: application/json
esw-authorization: Bearer eyJhbGciOiJSUzI1NiIsImtpZCI6IkVTVC1LRVktMDAxIn0...

Authentication Failure Behaviour

• Invalid or expired keys result in validation failure
• Missing or invalid esw-authorization headers result in rejection
• If basic authentication is disabled, webhook calls fail immediately

Supported Webhooks

JWKS authentication is supported for the following ESW webhook events:

• Order Confirmation
• Inventory Updates
• Order Returns
• Appeasements
• Cancellations

Key Benefits of JWKS Authentication

• No static credentials to rotate
• Secure public key validation
• Automatic key refresh
• Fallback compatibility with basic authentication
• Reduced configuration overhead