imiconnect supports the use of JWT within the Core SDK and Thread, Topic and Segment APIs. JWT provides additional security by providing a mechanism to restrict resource access to authorized users.
For detailed information on JWT please jwt.io where you will find a very good introduction.
Note that imiconnect only currently supports the SHA256 algorithm which uses a pre-shared secret key. The key is configured during creation of a mobile/web app asset within the imiconnect platform.
Enabling JWT Authentication for Thread, Topic, and Segment APIs
As a security best practice, we recommend that you enable JWT authentication. It is an optional feature and is not enabled by default. Please send an email to [email protected] to enable JWT authentication for Thread, Topic, and Segment APIs for your tenant if you'd like to use it. Once it's been enabled by the Operations team, you will need to enable the JWT authentication option on the mobile/web app asset configuration page.
- SDK will provide the method to set the JWT from APP.
- SDK should send the JWT token for each API request if JWT is enabled.
- Gateway accepts the request and validates the JWT token against JWT secret Key. If it is valid then forward the request to process, else the request is rejected with an error code
JWT payload should contain the expiration (optional) and either 'appUserId or 'customerId.' In JWT payload client can add any other public or private claims. JWT signature should be generated using the SHA256 algorithm only. Examples of Header and Payload are provided below.
Token Format.
JWT Token Header
The following table lists the supported header attributes:
alg
HS256
Specifies the signing algorithm used, imiconnect currently only supports HS256.
typ
JWT
The token type, always JWT.
{
"alg": "HS256",
"typ": "JWT"
}JWT Payload
Claims
The following table lists the JWT claims which are supported within the token payload:
exp
1584525821
The exp claim determines expiration time of the token expressed as seconds since the epoch. Although imiconnect does not enforce a maximum duration it is best practice to keep this as short a duration as possible for your use case.
appId
TR21063826
The AppId of your app asset configured within the imiconnect tenant portal. This claim is mandatory and will be validated before requests are serviced.
userId
67deb017-5038-4832-a6b9-aa7e00987b6f
The id of a user within imiconnect. User ids are an arbitrary string value assigned to an app / device profile during SDK registration. When this claim is specified, if the resource being accessed is user centric the value will be validated before requests are serviced.
{
"exp": 1584525821,
"appId": "TR21063826",
"userId": "67deb017-5038-4832-a6b9-aa7e00987b6f"
}HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
secret)Sample JWT token
NOTE
- The secret key must be base64 encoded before entering in the app asset configuration page.
- The length of the secret key before encoding must be at least 256 bits (32 bytes).
If an SDK method call fails because of a JWT validation error then an exception is generated with one of the following error codes:
TokenInvalid
38
The provided token is invalid, check that the token has been generated using the correct format and contains valid data.
TokenRequired
39
A token is expected but is missing.
TokenExpired
40
The token has expired.
Updated about 2 hours ago