JSON web tokens (JWTs, pronounced “jots”) are an industry-standard format for securely representing claims across a network. Yodlee uses JWTs to authenticate you, the FinTech developer, to the Yodlee API servers. There is also a second authentication approach, widely used by large financial institutions, known as SAML is not described here. This note gives an overview of the JWT approach to Yodlee authentication.
Typical JWT Claims
There are two crucial claims that you can make with JWTs sent to the Yodlee servers:
- “I am the registered Yodlee developer with the Issuer ID X.”
- “I am the registered Yodlee developer with the issuer ID X, and I want to access the data for my end-user Y.”
X represents a valid issuer ID, and Y represents a valid end-user ID. In the sandbox, X looks like a variation on this string: “3d2d9393-b3fa-4054-bb50-46e3aeccbcf”, and Y looks like a variation on this string “sbMem5c758c82bb1d11”.
How is JWT Secure?
Security is assured by digitally signing the token. Note that signed tokens protect against tampering, but they do not hide data. Do not put personally identifiable information into a JWT unless you encrypt it.
JWTs are secure, as the Yodlee server will detect if the token is corrupted or changed. The token also guarantees that it is created by someone who has access to your developer's private RSA key. The security relies on developers keeping their RSA private key confidential.
In the Sandbox environment, Yodlee will issue you your private key. In the Development and Production environment, the developer will have to acquire their own RSA key pair and upload their public key to Yodlee, while keeping their private key confidential.
JWT has 3 Components
The three components of a JWT are:
- Header: Contains a small JSON structure that specifies the algorithm used to mint the token, i.e., “SHA512”. This part is base64-URL encoded.
- Payload: Contains the claims, and the issue time and duration of the token (30 minutes maximum). This part is base64-URL encoded.
- Digital Signature: This is formed by concatenating parts 1 and 2 with a “.” between them, then using the SHA512 cryptographic hash function to get the hash of that string. The result is the third part of the JWT string. The correct hash can only be calculated by someone who has the developer’s private RSA key.
When using JWT, every call you make to the Yodlee servers will include an HTTP header called “Authorization”. The value of the header is “Bearer” followed by an actual JWT, created by your code. The complete HTTP header will look similar to this:
Authorization: Bearer
eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.
SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
The two periods in the string separates the three components of a JWT.
For more information about JWTs, and some tools to help decode them, please visit page https://jwt.io. We recommend that you use the Yodlee SDK or one of the open-source libraries listed at jwt.io, to create your JWTs.