External Integrator with Eclipse Webhooks Security(GLOBAL_INTEGRATOR)

In certain scenarios, external systems need to call Eclipse APIs without generating a JWT token. Common examples include:

• Third-party payment gateways posting status callbacks back to Eclipse
• 3D Secure (3DS) notification endpoints
• PnP cash confirmation callbacks

Generating a short-lived JWT token is impractical in these cases because the caller is an external system operating outside the tenant's authentication flow. Eclipse solves this with the GLOBAL_INTEGRATOR mechanism: a static API key is mapped to a specific Eclipse user identity. The external system authenticates by including the API key as an Authorization header.

Setup Steps

1. Generate a Random API Key

Create a random, high-entropy string of at least 36 characters. This will be the API key used by the external caller.

Example: 39EGvKwrpD99g2C9gDXhUhnrdnFyYTgrxuYh

2. Create a Global Integrator User

Create a user in Eclipse with the GLOBAL_INTEGRATOR role and an email address that identifies the integration purpose.

Example identity: [email protected]

3. Map the API Key to the User Identity

Add an entry to the global property apikey.to.user.mappings. The format is <api-key>=<user-identity>, with multiple mappings separated by commas.

apikey.to.user.mappings=39EGvKwrpD99g2C9gDXhUhnrdnFyYTgrxuYh=pnp-integration@mybank.co.za

Multiple integrations can be registered by adding additional comma-separated pairs:

apikey.to.user.mappings=39EGvKwrpD99g2C9gDXhUhnrdnFyYTgrxuYh=pnp-integration@mybank.co.za,[email protected]

4. Configure the Gateway to Use the Integrator Identity

For each gateway or integration that uses this mechanism, set the corresponding tenant config property to identityMatch with the integrator user's email address so Eclipse knows which Eclipse user to act as when that API key is presented.

5. Instruct the External Caller to Use the API Key

The external system must include the API key as the value of the Authorization header on every request to Eclipse:

POST /eclipse-conductor/rest/v1/tenants/{tenantId}/payments/callback
Authorization: 39EGvKwrpD99g2C9gDXhUhnrdnFyYTgrxuYh
Content-Type: application/json

{
  "status": "SUCCESSFUL",
  "gatewayTransactionId": "PNP-20240315-88291"
}

Eclipse will resolve the API key to the mapped user identity, apply that user's roles and permissions, and process the request accordingly.

Security Considerations

• API keys should be treated as secrets and rotated periodically.
• Each integration should use a separate API key and user identity to maintain audit trail separation.
• The GLOBAL_INTEGRATOR user must only have the minimum permissions required for the specific callback endpoint it is used for.