Getting started
Search
K
Links

JWT single sign-on

How to generate a JSON Web Token that can be used to authenticate to Commerce Layer APIs.
Single Sign-On (SSO) is a process that enables a user to access multiple applications (the service providers) by logging in once on an authentication server (the identity provider). To be authenticated through SSO on a service provider, you need to be logged in on the identity provider, which provides password-based authentication.
Single sign-on needs the service providers to communicate with the identity provider. One way of safely exchanging user information between the two parties is through JSON Web Tokens (JWT). Using JWT a service provider can receive trustworthy information from the authentication server. By sharing a secret key with the identity provider, the service provider can hash a part of a token it receives and compare it to the signature of the token. If the result matches the signature, the service provider knows that the information does come from the other entity possessing the key.
Commerce Layer lets you authenticate users in your systems and use SSO with JWT, so that a user is automatically verified with an identity provider of your choice (such as Auth0, Okta, or even a custom one) when they sign in. This feature is reserved for enterprise customers only.

Generating the JWT

The JSON Web Token you need to generate contains information to authenticate a resource owner or an application to the Commerce Layer APIs.

Authorization

The authorization flow on the API resources depends on the kind of owner and application, which can also have specific permissions configuration.

Scope

Together with the involved organization, owner, and application data, the JWT incorporates some additional information that can be used to refine the APIs usage, such as available markets with the related price list and stock locations.

Payload

The JWT consists of a JSON payload with the following structure:
{
"organization": {
"id": "kXMejFmBXj",
"slug": "my-org",
"enterprise": true
},
"owner": {
"id": "PegmYSGqEy",
"type": "Customer"
},
"application": {
"id": "lpvPXiLyGy",
"kind": "sales_channel",
"public": false
},
"market": {
"allows_external_prices": false,
"geocoder_id": null,
"id": [
"qgLdBhOQgA"
],
"price_list_id": "elbwyCVQLP",
"stock_location_ids": [
"RDkgepuVng"
]
},
"exp": 1610458065,
"rand": 0.4020178262833939,
"test": true
}
Where:
Key
Type
Required
Description
organization
object
The organization's unique ID.
owner
object
The owner (if any) authenticating to the APIs.
application
object
The type of credentials you're using to authenticate to the APIs.
market
object
The market(s) in scope.
exp
integer
The token expiration time, expressed as an epoch.
rand
float
A randomly generated number, less than one.
test
boolean
The environment type (true for test mode, false for live mode).
  • Owners can be of type User (the user that has access to the Commerce Layer admin dashboard) or Customer (the customer that is buying from your ecommerce) and have their own authorizations flow, which overloads the application one.
In order to use a customer token generated via SSO to manage registered customers, make sure that you defined a password for the customer in Commerce Layer. Otherwise, some customer account functionalities may be unavailable (e.g. payment methods won't be saved in the customer wallet and cannot be reused). For security reasons, we strongly recommend choosing strong/random passwords.
  • Each application has a unique id, a kind and a public attribute. For more information about the types of applications and their permissions based on the supported authorization flows, please refer to our documentation and API reference.
  • When the market is present:
    • It must include the id array, containing one or more unique IDs, associated with the market(s) you want to put in scope.
    • It must include the associated price_list_id (which must be the same for all of the markets in scope).
    • It must include the boolean flag allows_external_prices (if true external prices must be enabled for all the markets in scope, meaning that all of them must have the external_prices_url defined).
    • It can optionally include the geocoder_id (which must be the same for all of the markets in scope).
    • It can optionally include the stock_location_ids array, containing one or more unique IDs, associated with the stock location(s) you want to put in scope (which must be valid for the markets in scope i.e. the stock locations involved must belong to the related inventory model).
If you're building a JWT token to be used with a sales channel application to retrieve SKU data you must include the stock_location_ids array (containing at least one of the stock locations associated with the market's inventory model). This way all the SKUs that have at least a stock item in the included stock location(s) will be put in scope.

Signature

The JWT must be signed with a secret specific to each organization, which will be shared with the organization owner (if subscribed to an enterprise plan).

Encoding

The encoding (and decoding) of the JWT is performed by the HS512 algorithm (HMAC using SHA-512).