Additional information about OpenID Connect?

[snowc0de]

Hello,

I think there are some missing information about OpenID Connect in the book.

"openid" scope is required

The spec about OpenID Core specifies the following:

scope: REQUIRED. OpenID Connect requests MUST contain the openid scope value. If the openid scope value is not present, the behavior is entirely unspecified. Other scope values MAY be present.

I think it's important to mention that in the book.

Mention the "nonce" value

OpenID Connect allows a specific kind of protection using a "nonce" value. The idea is the following:

• The client creates a random value and sets it into the cookie
• A hash of this random value is used a "nonce" and is provided in the authorization URL
• Once the authorization code has been exchanged into a token and id_token, the client can verify that the nonce value (retrieved by hashing the cookie's value) is indeed present in the id_token

This is done to mitigate replay attacks, but also serves as a way to prevent stolen authorization codes from being used (as the attacker would have to also know the original value used to generate the nonce).

Unlike PKCE, the check is done on the client-side (and therefore only works for confidential clients). And unlike PKCE, "nonce" is required in the Core OpenId protocol specification.

Therefore, all OpenId providers must support this protection, and if they aren't standard and don't do it, the client can immediately notice the absence of the "nonce" value in the ID token and return an error.

This is in contrast with PKCE code exchanges where if the provider didn't implement PKCE code exchange, the client has no way to know there was no protection (as the code_challenge and code_verifier would simply be ignored by the provider).

PKCE, state and nonce can all be used for increased protection in OpenID in order to have client-side and server-side verification.

Here's the relevant bits of the spec talking about "nonce" in the OpenID protocol spec:

In the ID token section:

nonce: String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. If present in the ID Token, Clients MUST verify that the nonce Claim Value is equal to the value of the nonce parameter sent in the Authentication Request. If present in the Authentication Request, Authorization Servers MUST include a nonce Claim in the ID Token with the Claim Value being the nonce value sent in the Authentication Request. Authorization Servers SHOULD perform no other processing on nonce values used. The nonce value is a case-sensitive string.

In the "authentication request" section:

nonce: OPTIONAL. String value used to associate a Client session with an ID Token, and to mitigate replay attacks. The value is passed through unmodified from the Authentication Request to the ID Token. Sufficient entropy MUST be present in the nonce values used to prevent attackers from guessing values. For implementation notes, see Section 15.5.2.

In the "nonce implementation notes" section:

The nonce parameter value needs to include per-session state and be unguessable to attackers. One method to achieve this for Web Server Clients is to store a cryptographically random value as an HttpOnly session cookie and use a cryptographic hash of the value as the nonce parameter. In that case, the nonce in the returned ID Token is compared to the hash of the session cookie to detect ID Token replay by third parties. A related method applicable to JavaScript Clients and other Browser-Based Clients is to store the cryptographically random value in HTML5 local storage and use a cryptographic hash of this value.

Other considerations (access token verification and dynamic client registration)

Other considerations that I find pretty unnecessary when HTTPS is used are access token verification (a hash of the access token is added into the ID token, the client can therefore check the access token hasn't been tampered with.

Here's what's said about it in the spec:

The contents of the ID Token are as described in Section 2. When using the Authorization Code Flow, these additional requirements for the following ID Token Claims apply:

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.

Another consideration, but I don't know how important it would be to mention it, given almost no provider actually supports it (kinda sad because it has potential), is the OpenID Dynamic Client Registration. Basically providers can choose to let the clients register themselves automatically. So it would in theory let any user provide their own, personal OpenID Provider to a website, and the website would be able to automatically register itself on it. So it's a sort of federated/decentralized authentication method.

---

Anyway, thanks for reading all that ^^'. I really love this book and I find the low-level explanation of oauth2 very interesting. I just thought the OpenID Connect section might need some more details.

Let me know what you think 💜