If you are using Identity Linking as your user management system in Piano, you will need to pass a JWT Token.
You can create and decrypt or encrypt the JWT Token by using one of the available online tools: https://jwt.io
The JWT signed with an HS256 algorithm is composed of 3 parts: the Header, Payload, and Verify Signature.
Header
{
"alg": "HS256",
"typ": "JWT"
}
Payload
{
"aud": "XXXX",
"iss": "https://yourwebsite.com/",
"email": "email@test.com",
"first_name": "John",
"last_name": "Doe",
"sub": "PNIHB1l6kqaq1kl",
"exp": 1589687101,
"jti": "aosajda2123-12312asd"
}
aud is the External identity provider ClientID.
iss is the URL of your website.
email is the user's email address and is a required parameter.**
sub is the UID. This can be a random string and is also a required parameter.
first_name is the first name of the user. This is not a required parameter.
last_name is the surname of the user. This is not a required parameter.
exp is not a required parameter and should contain the Unix timestamp of the token expiration. It should be passed as an integer value.
jti is a required and can be any random string. The JTI claim is required, but not ingested into Piano, so a nonce value can be passed.*
*Identity Management checks whether the jti changed from the last authentication or not; if not - a user is just authenticated, if yes - a user is authenticated and the user record is updated. So to update a user account (for example with a changed Custom field value) you would need to send a new random unique jti claim.
**The "email" parameter is required and can not be skipped. The only way to not update user information on Piano's side is by using consistent JTI values and the feature JTI lookup.
If the JWT is incorrect or some of the parameters are missing, one of the problems that you can experience is an Internal exception error in the My Account section.
Please note, that when passing the JWT token via the anon/user/get endpoint, the exp parameter needs to be included in the JWT token. If this is not done, the user will be created, but any custom fields passed back within the token will fail to be recorded.
Verify Signature
HMACSHA256(
base64UrlEncode(header) + "." +
base64UrlEncode(payload),
XXXXX2VmY3NIRUasdokjaiosjuhui43ojsdoifjksdfksiodjfojhadaEx0Tg==
) secret base64 encoded
You can check whether the secret is correct by looking at the end of the string for 2 == signs. The minimum length of the secret is 32 characters.
Once the JWT is generated, it needs to be pushed to the website before the initialization of the Piano script.
An example of a correct implementation can be found below:
tp.push(["setAid", 'AID']);
tp.push(["setEndpoint", '<https://api.piano.io/api/v3']);>
tp.push(["setUseTinypassAccounts", false ]);
// tp.push(["setUsePianoIdUserProvider", true ]);
tp.push(["setUsePianoIdUserProvider", false ]); // Custom addon: Piano Lite
tp.push(["setUsePianoIdLiteUserProvider", true ]); // Custom addon: Piano Lite
tp.push(["setExternalJWT","eyJhbGciOiJIUzkpXVCJ9.eyJhdWQiOiN1IiwiaXNzIjoiaHR0cHM6Ly93d3cudG5sLmRldi50aGVuZXdzbGVucy5jb20vIiwiZW1haWwiOiJhZGFtLnNtZWxjZXIrdGVzdDNAcGlhbm8uaW8iLCJWRhbTIiLCJsYXN0X25hbWUiOiJUZXN0aWd"]);
The Client ID from your Piano Identity Linking configuration would appear as the aud claim in the JWT. The shared secret is not a part of the JWT. The shared secret is only used to generate the token and validate it.
To see what’s in it and validate it, go to jwt.io and paste the token into the Encoded input box, enter the base64 encoded secret into the Verify signature box and click the secret base 64 encoded checkbox. If you see Signature Validated, then all is well!
After that, you can use this API endpoint. All the Production base URLs are listed here.
If you receive a successful response, everything is set up properly.
Frequently Asked Questions
-
What is the JWT used for, is it just user data, or is it used to verify the user’s authentication?
It's for both. -
Does the expiry of the JWT matter and if so how is it handled?
Yes, it does. The expiration value should be more than now for the JWT to be valid. -
Is the email address required in the JWT or can we keep users in sync via the UID alone?
Yes, the email address is required. -
If the email address is in the JWT, will it be ignored unless we explicitly ask Piano to sync it?
It's being synced by default all the time.