mCards JWT SSO Token

Token Delivery

The mCards platform provides a JWT SSO token in the “Authorization” header when calling the Partner Feature web application URL. This token is provided in the following format:

"Authorization": Bearer <jwt_sso_token>

mCards will digitally sign the JWT token. Through the token’s digital signature, the Partner Feature’s web application can verify the token was sent from mCards and has not been modified in transit.

Token Format

The mCards JWT SSO token format is shown below.

{
   "header":{
      "kid":"a485b27f-96ed-45ec-ac4e-074d29e478eb",
      "alg":"RS256"
   },
   "payload":{
      "customer_id":"3d0c887a-b78a-427e-aa96-71dcd31bfc41",
      "full_name":"Susan Cardholder",
      "email":"[email protected]",
      "phone_number":"12125551212",
      "exp":1715112695,
      "iss":"https://fm.mcards.com/api/features_marketplace/",
      "iat":1715112395,
      "aud":"574ea118-58b0-45c3-b870-04b39dee3cbd"
   }
}

Header

The header consists of two claims:

• "kid" - This field identifies the public key that should be used to decrypt the JWT signature.
• "alg" - This field indicates the digital signature uses the RSA RS256 algorithm.

Payload

The claims that are important in the payload for identifying the mCards user are:

• "phone_number" - This phone number is the unique identifier associated with the mCards user. The mCards platform verifies this number
• "customer_id" - This field is the unique user identifier for the user in the mCards platform. It is provided in the JWT SSO Token in the event your Partner Feature web application would like to associate this identifier with the user’s record in your application.

Token Signature

The mCards JWT SSO token is digitally signed using RSA with the RS256 algorithm. The mCards public keys can be found at the following URLs and can be retrieved using a GET request.

The mCards platform may periodically rotate keys as a security measure. You may cache the public key available at the links above, but if a JWT SSO token includes a different key ID than the value you have cached, you should retrieve the updated public key associated with the new key ID.

Token Usage

This section provides direction on the specific usage of the mCards JWT SSO token. Visit JWT.IO for a full explanation on the general operation and usage of JSON Web Tokens (JWTs).

The Partner Feature web application should use the following logic to obtain the mCards user information provided with the token:

• Verify the token is from mCards - This process involves validating the digital signature.
• Use the "phone_number" field in the token payload to identify the user in the Partner Feature web application

To validate the digital signature

1. Decode the three parts of the JWT token - As with any other JWT, the token provided by the mCards platform is base64 encoded. This must be decoded to obtain the digital signature.
2. Obtain the encryption Key ID from the kid field in the header of the token.
3. Obtain the public key from the publicly available mCards published key that matches the kid provided in the header.
4. Using the public key, decrypt the signature of the JWT.
5. Compare the decrypted result to the JWT header and payload to confirm that they match.

If the decrypted signature matches the header/payload, then you can be certain that the token was generated and sent by the mCards platform. You can now use the "phone_number" field in the payload to uniquely identify the user in your Partner Feature web application.