Reference - Usage of JSON Web Token (JWT)

1 Introduction

Info

This document is valid from ICM 7.10.22.0. 

This reference describes the several token types used within or accepted by Intershop Commerce Management (ICM).

1.1 Glossary

TermDescription
JWTJSON web token

1.2 External References

2 Definition

2.1 Types of Token

Token TypeDescription
ID TokenA token containing information about a user's identity

Access Token

A token granting access to a certain resource
Refresh TokenA token granting access to a resource that allows to request new ID and access tokens

2.2 Claims

2.2.1 General Claims

All ID tokens support the following required (payload) claims:

ClaimDescriptionExample
issIssuer of this tokenhttps://server.example.com
subSubject of this token (e.g. user id)24400320
audAudience (mostly the client id)s6BhdRkqt3
expExpiration date (syntax defined by RFC3339)1311281970
iat"issued at"-date (syntax defined by RFC3339)1311280970

2.2.2 Profile Claims

The ICM server maps ID token claims to the user's profile data:

ClaimProfile Attribute
given_namefirstName
family_namelastName
nicknamenickname
emailemail
gendergender
birthdatebirthdate
phone_numberphoneNumber

3 Mapping Between JWT Token and ICM Account

3.1 External JWT Token to ICM Profile

The ICM server maps ID token claims to the user's profile data:

ClaimProfile Attribute
given_namefirstName
family_namelastName
nicknamenickname
emailemail
gendergender
birthdatebirthdate
phone_numberphoneNumber
login

Built using the pattern:

externalUserName + "#" + externalUserId + "@" + identityProviderId

with:

  • externalUserName: claim preferred_username fallback to unique_name fallback to name fallback to sub
  • externalUserId: claim sub or claim oid (in case of Microsoft Azure AD
  • identityProviderId: ID of the identity provider (see Concept - Single Sign-On (SSO))

3.2 ICM Profile to JWT Token

The ICM supports JWT Token creation ("token" resource). These JWT are filled using the following data:

Profile AttributeClaim
profileIDuser_id
firstName + <space> + lastNamename
firstNamegiven_name
lastNamefamily_name
emailemail
loginpreferred_username

Other required claims are set with the following values or data:

ClaimResolved
sub (subject)user_id
iss (issuer)web-server-secure-URL
aud (audience)
"ICMClient"
exp (expires)creation date + life time
iat (issued at)current date
nonceA uuid

Disclaimer

The information provided in the Knowledge Base may not be applicable to all systems and situations. Intershop Communications will not be liable to any party for any direct or indirect damages resulting from the use of the Customer Support section of the Intershop Corporate Web site, including, without limitation, any lost profits, business interruption, loss of programs or other data on your information handling system.

Customer Support
Knowledge Base
Product Resources
Support Tickets