V51 OAuth: Improve scope definition for new OAuth chapter

[TobiasAhnoff]

A suggestion is to define the scope for the new OAuth chapter like this (where the first section of the chapter i Control Objective and the last is OAuth2 References. Note that this assumes a new OIDC chapter as well (see #2037) and address (closes) #1924.

Control Objective

OAuth2 has become industry standard for API protection and the also the basis for federated login using OpenID Connect (OIDC).
This chapter highlights core best current practices for OAuth2 based on references in the OAuth2 References section of this chapter, while OIDC is addressed in the OIDC chapter.

Note that additional OAuth2 features such as JAR, RAR, Resource indicators, Token exchange etc are considered out of scope.

Please read this chapter in combination with all other chapters at this same level; we do not duplicate authentication, authorization, session management, general input validation concerns and so on. Rather, the general requirements from other chapters always apply and therefore this chapter can not be taken out of context and be tested separately.

This chapter only contains OAuth2 specific verifications and in example token validation is addressed in ASVS chapter 4 and 13.
Note that all verification in this chapter also applies to OIDC.

OAuth2 References

OAuth2 is defined by a large set of specifications, see in example https://oauth.net/2/. Verification for this chapter has primarily been aligned with the following resources and the original RFCs they reference:

• https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-11
• https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics
• https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps

Together with the OpenID working group security profile for Financial grade APIs (FAPI) 2.0, see https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html. FAPI applies to any OAuth2/OIDC application with high security requirements, such as finance, healthcare and government sectors.

[elarlang]

More points to address:

• only widespread and most common mistakes are addressed in ASVS as separate requirements
• the current ASVS release is a snapshot in time and as OAuth2 develops fast, new specifications and add-ons are created, then it is required to follow the latest specs for best practices

(to make it easier to follow, you can make changes to the original text in the issue)

[TobiasAhnoff]

only widespread and most common mistakes are addressed in ASVS as separate requirements

Good point!

the current ASVS release is a snapshot in time and as OAuth2 develops fast, new specifications and add-ons are created, then it is required to follow the latest specs for best practices

I agree! Setting a good scope and keep it up to date is a challenge (also noted in #1924)

[randomstuff]

OAuth2 has become industry standard for API protection and the also the basis for federated login using OpenID Connect (OIDC). This chapter highlights core best current practices for OAuth2 based on references in the OAuth2 References section of this chapter, while OIDC is addressed in the OIDC chapter.

I would separate OAuth and OIDC in separate sentences (or paragraphs):

OAuth2 has become industry standard for API protection. This chapter highlights core best current practices for OAuth2 based on references in the OAuth2 References section of this chapter. OAuth2 is also the basis for federated login using OpenID Connect (OIDC) and all verifications in this chapter therefore applies to OIDC as well. However, additional OIDC-specific verifications are discussed in a dedicated chapter.

[randomstuff]

Note that additional OAuth2 features such as JAR, RAR, Resource indicators, Token exchange etc are considered out of scope.

Is it? There are some interesting things which could be said about RAR such as:

• Verify that the user cannot tamper with RAR requests. This can be achieved with PAR or JAR/JWS.
• Verify that the user cannot see confidential data in RAR requests. This can be achieved with PAR or JAR (JWE+JWS).
• Verify the the authorization server ensures that the user consents with the content of the RAR request.

[TobiasAhnoff]

I agreee that RAR adds good security features! My concern is that there are so many specs and that the scope for ASVS will become hard to maintain...and I suggested a minimal scope (aligned with FAPI 2) to start a discussion on what to include or not.

Whit that said, I think adding RAR to the scope and RAR-verifications as you suggested would be good, perhaps ASVS need to have something to capture this note from FAPI 2 (see https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html#section-5.3.2.2).

NOTE 5: The use of OAuth 2.0 Rich Authorization Requests (RAR) [RFC9396] is recommended when the scope parameter is not expressive enough to convey the authorization that a client may want to obtain.

But I am not sure that is something to express as a verification, more of a guideline thing, and obvious that RAR is optional to use when needed (given that ASVS does not have a verification that states that RAR must be used for all levels).

Maybe add https://www.rfc-editor.org/rfc/rfc9396 to the OAuth/OIDC scope and create a new issue to add RAR-verifications for the Authorization Server?

[randomstuff]

Note that my examples might probably be integrated into existing verifications.

[elarlang]

@randomstuff - do you think there is need to formulate some separate requirements from examples listed here #2036 (comment) ?

[randomstuff]

do you think there is need to formulate some separate requirements [...]

If RAR is considered in scope, it might be useful I guess. Maybe this might included (or already be part) of other requirements.

Verify that the user cannot tamper with RAR requests. This can be achieved with PAR or JAR/JWS.

I think this is probably important but only makes sens for backend clients.

Verify that the user cannot see confidential data in RAR requests. This can be achieved with PAR or JAR (JWE+JWS).

This could be generalized into "verify that the authorization request does not expose data to the user data the user should not be able to see" (of sort), even if in practice this is probably mostly be a problem for RAR. I don't believe we have one like that.

Verify the the authorization server ensures that the user consents with the content of the RAR request.

This could probably be included in something like: "verify that the authorization server provides consent verification with sufficient information (for example when a RAR request is used)".

[elarlang]

fyi: first idea was to include only level 1 and level 2 requirements, so called base-layer. Now we have crossed the line long time ago and it's is complicated to draw the line "this is in the scope and this is not".

What I would like to see, that if it is more like level 3 make things just correct or it does not give clear security impact, then it is subject to leave out.

For the (potential) requirements, please open a separate issue for each one, then it's easier to follow and discuss them. (And we are not limited with the requirements that were listed here, if there is something more to add)