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.
The JSON Web Token you need to generate contains information to authenticate a resource owner or an application to the Commerce Layer APIs.
The authorization flow on the API resources depends on the kind of owner and application, which can also have specific permissions configuration.
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.
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 | ||
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) orCustomer(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, akindand apublicattribute. 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
idarray, 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(iftrueexternal prices must be enabled for all the markets in scope, meaning that all of them must have theexternal_prices_urldefined). - 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_idsarray, 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.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).
Last modified 1mo ago