Shapes by Omneo

Implementation

Shapes provides the flexibility to either interact with the Omneo API directly, or to get creative with a separate backend or proxy.

Let's looks at a basic Shapes setup. We have a config below that will call the Omneo API directly, using a JWT to authenticate and a known user's profile_id to access their data:

omneoShapes({
    url: "https://api.{environment}.omneoapp.com/api",
    token: "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsImp0aSI6...",
    profileId: "8c5a9509-scg2-43sg-aec2-a90de8jj9sg4",
})

This is a great way to get up and running quickly, but poses a number of questions around security and transparency for the user.

  • Can an end user guess or find another customer's profile_id and then access their data?
  • Is the token a general token, allowing access to system-critical endpoints?
  • Should an end user have visibility over Omneo as a brand, through the API URL?

Using a proxy

With any implementation of Shapes, we'd recommend abstracting the front end access to Omneo, through the use of a proxy. The proxy can act as a gatekeeper and also allows each system to govern access appropriately for logged in users - Without needing to involved Omneo in the identification of valid users etc.

Shopify

Omneo's first party app for Shopify acts as a proxy for front end components, including Shapes. Shapes interacts with this plugin in the following way:

omneoShapes({
    url: "https://example-store.myshopify.com/apps/omneo-app/api",
    token: "{{shopify_customer.metafields.omneo_token}}",
    profileId: "{{shopify_customer.metafields.omneo_id}}"
})

When a customer logs in to Shopify, a front-end script checks to determine if the customer has an omneo_token metafield. If they don't, the plugin will inject a short-term access token into the customer metafields. This token is then used to authenticate requests from Shapes, to the plugin. Once a profile has a short-term access token, it then uses this to authenticate all requests to the proxy.

The proxy then validates all requests internally and will use its own access token to pass on requests to the Omneo API, if they are valid.

Salesforce Commerce Cloud

The Omneo / SFCC Cartridge will determine the logged in user internally, allowing this detail to be obfuscated to the front end. When a user is logged in and Shapes make a request, the cartridge will find the logged in user's Omneo profile_id, then use its own Omneo API Token to proxy the Shapes request.

If the Omneo ID isn't present, the cartridge should make its own request to the Omneo API and attempt to find the customer's profile by email, or demandware ID.

Since the Cartridge handles authentication and identification of the customer's Omneo profile_id on the backend, we recommend the following front-end Shapes configuration:

omneoShapes({
    url: "https://{{cartridge_url}}/api",
    token: false,
    profileId: "me"
})

The Cartridge can then proxy all requests, replacing the profile_id value of me with the customer's real Omneo profile_id. The Cartridge can also ensure that only allowed endpoints are accessed - mainly just /v3/profiles/{profile_id} and its children.

←