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.
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:
- 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.
- 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 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_idsarray (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).