JWT single sign-on

Search…
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:
1
{
2
  "organization": {
3
    "id": "kXMejFmBXj"
4
  },
5
  "owner": {
6
    "id": "PegmYSGqEy",
7
    "type": "User"
8
  },
9
  "application": {
10
    "id": "lpvPXiLyGy",
11
    "kind": "webapp",
12
    "public": false
13
  },
14
  "market": {
15
    "allows_external_prices": false,
16
    "geocoder_id": null,
17
    "id": [
18
      "qgLdBhOQgA"
19
    ],
20
    "price_list_id": "elbwyCVQLP",
21
    "stock_location_ids": [
22
      "RDkgepuVng"
23
    ]
24
  },
25
  "exp": 1610458065,
26
  "rand": 0.4020178262833939,
27
  "test": true
28
}
Copied!
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 application authenticating 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.
Each application has a unique id, a kind and a public attribute. For more information about the types of supported 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 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)
it can optionally include the geocoder_id (which must be the same for all of the markets 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).
Refresh token
Roles and permissions
Last modified 1mo ago
Copy link
Contents
Generating the JWT