Google OAuth: What do the various fields in id_token stand for?

2.6k views Asked by At

The id_token I get at the end of the OAuth exchange has the following:

"id_token": {  
   "aud":"xxx.apps.googleusercontent.com",
   "email_verified":true,
   "iss":"accounts.google.com",
   "email":"[email protected]",
   "iat":1234,
   "exp":1234,
   "azp":"xxx.apps.googleusercontent.com",
   "at_hash":"xxxy",
   "sub":"1243"
}

I wanted to know what these stand for? More importantly, which of these fields can I use as a primary key (id)?

1

There are 1 answers

0
Hans Z. On BEST ANSWER

Google adheres to the OpenID Connect standard which defines the id_token. So you can find the meaning in that specification here: http://openid.net/specs/openid-connect-core-1_0.html#IDToken

iss REQUIRED.
Issuer Identifier for the Issuer of the response.
The iss value is a case sensitive URL using the https scheme that contains scheme, host, and optionally, port number and path components and no query or fragment components.

sub REQUIRED.
Subject Identifier.
A locally unique and never reassigned identifier within the Issuer for the End-User, which is intended to be consumed by the Client, e.g., 24400320 or AItOawmwtWwcT0k51BayewNvutrJUqsvl6qs7A4. It MUST NOT exceed 255 ASCII characters in length. The sub value is a case sensitive string.

aud REQUIRED.
Audience(s) that this ID Token is intended for.
It MUST contain the OAuth 2.0 client_id of the Relying Party as an audience value. It MAY also contain identifiers for other audiences. In the general case, the aud value is an array of case sensitive strings. In the common special case when there is one audience, the aud value MAY be a single case sensitive string.

exp REQUIRED. Expiration time on or after which the ID Token MUST NOT be accepted for processing.
The processing of this parameter requires that the current date/time MUST be before the expiration date/time listed in the value. Implementers MAY provide for some small leeway, usually no more than a few minutes, to account for clock skew. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time. See RFC 3339 [RFC3339] for details regarding date/times in general and UTC in particular. iat REQUIRED. Time at which the JWT was issued. Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

iat REQUIRED.
Time at which the JWT was issued.
Its value is a JSON number representing the number of seconds from 1970-01-01T0:0:0Z as measured in UTC until the date/time.

azp OPTIONAL.
Authorized party - the party to which the ID Token was issued.
If present, it MUST contain the OAuth 2.0 Client ID of this party. This Claim is only needed when the ID Token has a single audience value and that audience is different than the authorized party. It MAY be included even when the authorized party is the same as the sole audience. The azp value is a case sensitive string containing a StringOrURI value.

at_hash OPTIONAL.
Access Token hash value.
Its value is the base64url encoding of the left-most half of the hash of the octets of the ASCII representation of the access_token value, where the hash algorithm used is the hash algorithm used in the alg Header Parameter of the ID Token's JOSE Header. For instance, if the alg is RS256, hash the access_token value with SHA-256, then take the left-most 128 bits and base64url encode them. The at_hash value is a case sensitive string.

Furthermore email and email_verified are standardized claims, found here http://openid.net/specs/openid-connect-core-1_0.html#StandardClaims:

email string
End-User's preferred e-mail address.
Its value MUST conform to the RFC 5322 [RFC5322] addr-spec syntax. The RP MUST NOT rely upon this value being unique, as discussed in Section 5.7.

email_verified boolean
True if the End-User's e-mail address has been verified; otherwise false.
When this Claim Value is true, this means that the OP took affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed. The means by which an e-mail address is verified is context-specific, and dependent upon the trust framework or contractual agreements within which the parties are operating.

So you'll notice that the sub is the primary key, which is unique per user over time at least within the scope of the Provider. E-mail is not, because it may be reassigned at some point.