ID Token Verification

Introspection

Hellō provides an introspection API per RFC 7662 (opens in a new tab) at https://wallet.hello.coop/oauth/introspect that will examine the token, ensure it was from Hellō, has not expired, and return the payload.

Request

No authentication is required to call the introspection endpoint. You MUST pass your client_id, and if you provided a nonce in the request URL, you MUST provide the nonce. The token, client_id, and optional nonce are sent as JSON.

NOTE: This is a stateless endpoint. This endpoint verifies the ID Token and returns the contents.

Sample code to make Introspection API call

const url = 'https://wallet.hello.coop/oauth/introspect'
const params = {
  token,        // the ID Token received
  client_id,    // your apps client_id
  nonce,        // the nonce sent in the request
}
const options = {
    method: 'POST',
    mode: 'cors',
    cache: 'no-cache',
    headers: {'Content-type': 'application/x-www-form-urlencoded'},
    body: new URLSearchParams(params).toString()
}
const response = await fetch(url, options)
const json = await response.json()

Response

If successfully verified, you will receive the ID Token payload with active:true to indicate it is an active token. If unsuccessful, you will receive an Introspection Error.

Sample Introspection Response

{
  "iss": "https://issuer.hello.coop",
  "aud": "3574f001-0874-4b20-bffd-8f3e37634274",
  "nonce": "b957cea0-f159-4390-ba48-5c5d7e943ea4",
  "jti": "8ad167d1-d170-46c9-b3c6-47dda735a4e3",
  "sub": "f9e21f0f-9f0e-41b0-a58b-c2d63bcc7b4f",
  "scope": [
      "name",
      "nickname",
      "picture",
      "email",
      "openid"
  ],
  "name": "Dick Hardt",
  "nickname": "Dick",
  "picture": "https://cdn.hello.coop/images/default-picture.png",
  "email": "dick.hardt@hello.coop",
  "email_verified": true,
  "iat": 1669399110,
  "exp": 1669399410,
  "active": true
}

Note the response is an ID Token with the additional claim active: true as highlighted.

Self Verification

There are many OpenID Connect and JSON Web Token libraries that include ID Token validation. The OpenID Foundation maintains a list here (opens in a new tab). Getting security right is HARD. We recommend you use a proven library and NOT write your own validation. We include the information below for reference.

Signature Verification Keys

Hellō provides OpenId Provider configuration information per OpenID Connect Discovery (opens in a new tab) at:

https://issuer.hello.coop/.well-known/openid-configuration (opens in a new tab)

The jwks_uri property in the configuration file contains the URI for a JSON file containing the public keys in JSON Web Key format (RFC 7517 (opens in a new tab)) for verifying the signature per step (6) above.

ID Token Verification Steps

Following are details for each ID Token verification step per OpenID Connect 3.1.3.7 (opens in a new tab)

1. N/A - The ID Token is not encrypted
2. The iss value MUST be https://issuer.hello.coop
3. The aud value MUST be the client_id value provided in the request
4. N/A - The ID Token will not contain multiple audiences
5. There will not be an azp claim
6. The ID Token is signed per JWS. The certificates are XXX
7. The alg value will be RS256
8. N/A - the alg is always RS256
9. The current time must be before exp. Note the time is seconds since the Epoch, not milliseconds. ID Tokens expire after one hour.
10. The iat may be used by the client if the one hour expiry is longer than is desirable by the client.
11. The nonce is included if provided in the request.
12. The acr Claim is not supported at this time.
13. The auth_time Claim is not supported at this time.