Decoding the ID Token¶

ID Token as a JSON Web Token (JWT)¶

The ID Token is represented as a JSON Web Token (JWT). The JWT is signed using a JSON Web Signature (JWS) and consists of three parts separated by ‘.’ (period).

An ID Token has the following syntax:

Base64(JOSE header).Base64(Payload).Base64(Signature)

{
    "alg":"ES256",
    "kid":"87350ad9ce04550819b62079b193a42055a36b71"
}

ID Token Payload¶

The payload contains Claims about the authentication event. The following JSON fields are contained in the payload.

• iss - (Issuer) The Issuer Identifier for the Issuer of the response. Clients must validate that the value is equal to https://api.login.yahoo.com.
• sub - (Subject) The unique user identifier.
• aud - (Audience) The value of the Client’s ID (client_id). Clients must verify that it is equal to their Client ID.
• exp - (Expiration Time) The expiration for the ID Token. Clients must verify that this expiry time has not passed.
• iat - (Issued At) The issue time for the ID Token.
• nonce - The nonce passed as a parameter during authorization.
• at_hash - (Access Token Hash Value) The Access Token hash (if issued with the flow), which can be used to mitigate cross-site request forgery (CSRF).

{
   "sub": "MCX7TR7RTB5L3YRYR4FIAKX2IE",
   "aud": "dj0yJmk9NDdXZzBEcmJ6UjJxJmQ9WVdrOVlVWktjR0ZLTkdFbWNHbzlNQS0tJnM9Y29uc3VtZXJzZWNyZXQmeD04OQ--",
   "email_verified": true,
   "iss": "https://api.login.yahoo.com",
   "name": "Jasmine Smith",
   "exp": 1440569876,
   "locale": "en-US",
   "given_name": "Jasmine",
   "nonce": "YihsFwGKgt3KJUh6tPs2",
   "iat": 1440566276,
   "family_name": "Smith",
   "email": "jasmine_smith@yahoo.com"
}

Signature¶

The last part of the ID Token is the digital signature, which is generated for the JOSE header and payload data (Base64(JOSE header).Base64(Payload)). Clients must validate the signature and return an error if the validation fails. To validate the signature, clients should fetch public keys from the keys endpoint. The endpoint is available from the jwks_uri field in the Yahoo Discovery document. We’ll learn to validate the signature in Validate the ID Token.

Decoding Example¶

We’re going to decode the following ID Token:

/#id_token=eyJhbGciOiJFUzI1NiIsImtpZCI6IjM0NjZkNTFmN2RkMGM3ODA1NjU2ODhjMTgzOTIxODE2YzQ1ODg5YWQifQ.eyJhdWQiOiJkajB5Sm1rOWJrMTVhM0ZYVjJ0NWNEbHRKbVE5V1Zkck9WbFZNWFJrYmtJMVRsUkJiV05IYnpsTlFTMHRKbk05WTI5dWMzVnRaWEp6WldOeVpYUW1lRDA0TUEtLSIsInN1YiI6IlVRSURXSk5XVk5RRDRHWFo1TkdNWlVTVFE0IiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi55YWhvby5jb20iLCJleHAiOjE0NDQ2OTcwNDUsIm5vbmNlIjoiWWloc0Z3R0tndDNLSlVoNnRQczIiLCJpYXQiOjE0NDQ2OTM0NDV9.XiyNdHHHoYqarDZGkhln5sF_SQNNVvV67SZsFAk7yo8NreJjzVw7LmtkwpiUQe87-Km39PeIwf1W_PqEH9RqjA"

1. First, extract the encoded JOSE header, the payload, and the signature by splitting the ID Token string on ”.”:

   jose_header = "eyJhbGciOiJFUzI1NiIsImtpZCI6IjM0NjZkNTFmN2RkMGM3ODA1NjU2ODhjMTgzOTIxODE2YzQ1ODg5YWQifQ"
   payload = "eyJhdWQiOiJkajB5Sm1rOWJrMTVhM0ZYVjJ0NWNEbHRKbVE5V1Zkck9WbFZNWFJrYmtJMVRsUkJiV05IYnpsTlFTMHRKbk05WTI5dWMzVnRaWEp6WldOeVpYUW1lRDA0TUEtLSIsInN1YiI6IlVRSURXSk5XVk5RRDRHWFo1TkdNWlVTVFE0IiwiaXNzIjoiaHR0cHM6Ly9sb2dpbi55YWhvby5jb20iLCJleHAiOjE0NDQ2OTcwNDUsIm5vbmNlIjoiWWloc0Z3R0tndDNLSlVoNnRQczIiLCJpYXQiOjE0NDQ2OTM0NDV9"
   signature = "XiyNdHHHoYqarDZGkhln5sF_SQNNVvV67SZsFAk7yo8NreJjzVw7LmtkwpiUQe87-Km39PeIwf1W_PqEH9RqjA"
   

2. Use a Base64 library to decode the strings. You can use https://www.base64decode.org/ to help you decode the strings for this tutorial:

   jose_header = {
      "alg":"ES256",
      "kid":"3466d51f7dd0c780565688c183921816c45889ad"
   }
   
   payload = {
       "aud":"dj0yJmk9bk15a3FXV2t5cDltJmQ9WVdrOVlVMXRkbkI1TlRBbWNHbzlNQS0tJnM9Y29uc3VtZXJzZWNyZXQmeD04MA--",
       "sub":"UQIDWJNWVNQD4GXZ5NGMZUSTQ4",
       "iss":"https://api.login.yahoo.com",
       "exp":1444697045,
       "nonce":"YihsFwGKgt3KJUh6tPs2",
       "iat":1444693445
   }
   
   signature = "XiyNdHHHoYqarDZGkhln5sF_SQNNVvV67SZsFAk7yo8NreJjzVw7LmtkwpiUQe87-Km39PeIwf1W_PqEH9RqjA"
   

   The alg Header Parameter is “ES256”, so you would validate the ECDSA P-256 SHA-256 digital signature contained in the JWS Signature.

3. Congratulations, you have decoded your ID Token. The next step is to validate the ID Token.

Validate the ID Token¶

After decoding your ID Token, you will still need to validate it. Because the validation of an ID Token depends on an expiration time, instead of walking through an example, we’re going to instead provide you with validation steps.

public boolean validateECDSASignatureWithNimbus(String x, String y) throws Throwable {
   JWSVerifier verifier = new ECDSAVerifier(new BigInteger(Base64.decodeBase64(x)), new BigInteger(Base64.decodeBase64(y)));
   return SignedJWT.parse(idToken).verify(verifier);
}

Resources¶

• Yahoo Discovery document
• OpenID Connect 1.0 Libraries, Products, and Tools
• JSON Web Signature (JWS): Appendix A. JWS Examples