JWT Generation - Authorization - Infosys Equinox Developer Portal

This page describes authorization tokens and their generation and use in Infosys Equinox.

Overview

A JSON Web Token (“JWT”) is used as an authorization token (“Auth Token”) because of its compact and self-contained way of transmitting secured information.

To implement or generate JWT in the code, the www.jwt.io site provides libraries for all languages. Infosys Equinox uses the following library for generating and validating tokens: https://mvnrepository.com/artifact/io.jsonwebtoken/jjwt

If you have credentials of a valid user, the create session call (POST /sessions) in the Authorization microservice will provide the auth token.

To try out the Infosys Equinox application programming interfaces (APIs) without the Authorization microservice, you need to generate a token in one (1) of two (2) ways:

Using the JWT Site – see Generating Auth Using Business Secret below.
Using a Jar File– see Generating a Token Using a Jar File below.

Auth Token Structure

The Auth token has the following three sections, separated by dots (.):

Header – contains the algorithm used for encoding of the token.
Payload – contains the data, such as user information and authorities.
Signature – verifies the token. This signature is made up of a hash of the following components: the header, the payload, and the secret (For more information, see Business Secret Keys in the Foundation Admin Guide.

Syntax:

Token = encodeBase64(header) + '.' + encodeBase64(payload) + '.' + encodeBase64(signature)

Example:

eyJhbGciOiJIUzUxMiJ9.eyJjcmVhdGVkIjoxNTUzMDYzNTA5MTAwLCJleHAiOjE1NTMwNjUzMDks Imhhc2giOiJhZWI3YjY4NmZiMjI4MmJjMGM4NmIwMzA0NjNiMzYxNCIsImF1dGhvcml0aWVzIjoiW 3tcInJvbGVzXCI6e1wiUk9MRV9TVVBFUl9BRE1JTlwiOnt9fX1dIiwidXNlcm5hbWUiOiIxIn0.ZsMcQ WWkwoXSMjKOHKK4nH2llUrEtd6oPJc6v8_UVejPerCCv8NLLfeZnZGH3mSJUm2HQuX3nqbY4d 7kbRQRhw

Generating an Auth Token Using the Business Secret

1. To get the secret for your business, go to the Business Overview page > Keys & Credentials tab in the Foundation Admin console. For more information, see Business Secret Keys in the Foundation Admin User Guide.

2. In the Business Secret Keys section, click the Show button and copy the secret key.

3. Go to https://www.browserling.com/tools/sha512-hash and get the hash string for your secret key.

4. Go to the https://jwt.io/ site. Click on the Debugger option in the menu and navigate to the console.

5. Choose HS512 from the Algorithm drop down. Note: The header claim “bid” (Business Identifier) is used to parse the token using signingkeyresolver in the “SKAVA” authorization type. This impacts the users who are generating the token on their own and when they need to add this header in their token generation with the valid business ID.

6. Create payload in the format given below. (OR) Use the sample payload below with a Business Admin (a user who has all access within a business) role.

7. Go to the VERIFY SIGNATURE section and enable secret base64 encoded by clicking its checkbox.

8. Paste the obtained secret hash from Browserling.com into the your-512-bit-secret box under the VERIFY SIGNATURE section.

9. Click the SHARE JWT button to generate the token and copy it to your clipboard.

10. Paste the token from your clipboard as the x-auth-token header for all APIs.

Sample Payload Format

{
  "created": 1544006652457,
  "exp": 1654008452,
  "hash": "2210b60d08481f0f1253fecd53b89f25",
  "authorities": "[{\"roles\":{\"ROLE_BUSINESS_ADMIN\":{\"business\": {\"1\":{}},\"type\":\"STANDARD\"}}}]",
  "username": "1"
}

Sample Payload Format Legend

Attribute	Description	Format	Required Value
`created`	Indicates the creation time of the token.	Epoch timestamp in milliseconds (use human to epoch time converter).	true
`ext`	Indicates the expiration time of the token.	Epoch timestamp in milliseconds (use human to epoch time converter).	true
`hash`	Indicates the expiration time of the token.	Random string with a length less than 40.	true
`authorities`	Indicates the business-specific authorities. Syntax: `[ { "roles": { "<role_name>": { "business": { "<business_id>": { "privileges": [ { "privilege": "<privilege>" } ] } }, "type": "<STANDARD/CUSTOM>" } } } ]` where, `role_name` – Indicates the role name. This group contains business-specific privileges belonging to this role. This section can be repeated for multiple roles. `business_id` – Holds the business identifier and privileges. `privilege` – Indicates the privilege in service, action, or entity format. The privilege section can be repeated for multiple privileges. `type` – Indicates the type of role. The value can be STANDARD or CUSTOM.	Provide the JSON in a string format; for example, `[ { "roles": { "ROLE_CATALOG_EDITOR": { "business": { "1": { "privileges": [ { "privilege": "catalog/editor/all" } ] } }, "type": "STANDARD" } } } ]`	true
`username`	Indicates the unique identifier for the user.	Hexadecimal of length less than 50.	true

Generating an Auth Token Using a Jar File

2. In the Business Secret Keys section, click the Show button and copy the secret key.

3. Download the AuthJWTManager.jar.

4. Launch a Terminal (Mac and Linux) or Command Prompt (Windows).

5. Run the Jar using the java -jar authjwtmanager.jar command.

6. Enter the user ID.

7. Enter the Expiry Time in minutes.

8. At the command prompt, enter the Secret Key for token signing.

9. Enter the authority data (JSON string format) of the payload.
Note: In the JSON data, format the JSON value and remove white spaces.

10. Copy and use the token as the x-auth-token header in all APIs.

JWT Generation – Authorization

Overview

Auth Token Structure

Generating an Auth Token Using the Business Secret

Generating an Auth Token Using a Jar File