Add OAuth2 requirements

[csfreak92]

Ed note: This issue was originally called "v3.5 Token-based Session Management addition"

---

Ed note 2: If you are just joining us, the draft chapter is currently here: V51 OAuth 2.0 Protocol

Before you review it, read through this issue thread to collect the context and then feel free to open separate issues if you have specific questions or suggestions.

---

Original text starts here:

I think we need to add a control that validates the incoming HTTP request in an API endpoint which issues new access and refresh tokens. Usually this is with the refresh endpoint, but in some weirdly built applications, there were some implementations that every response would contain the new tokens that could be used for the next authenticated and authorized calls to the API. The requirement would be for the refresh token endpoints to have a validation of the requests, URL and request body must be validated before issuing the new set of tokens.

The rationale about this thought came to me when I was testing a few recent applications that either have refresh endpoints or a few ones that do not have refresh endpoints but the next authenticated tokens are coming from the HTTP responses. This is a bit of an old way of doing it as I understood and a bit uncommon. However, I noticed a pattern of accepting the request even if it was malformed or missing the object id or any reference for a resource (e.g. http://www.example.com/12345 but I the request was http://www.example.com/ralph; second URL is invalid and should be rejected). The application returns no valuable data except the new set of tokens which can be used for the succeeding calls to the API. I think it was a bad design, but for defense in depth purposes and preventing an attacker for prolonging their usage of the compromised account (which would be cut short had the application been following proper OIDC flow), the application should check for incoming HTTP requests to be correct in format, parameters, etc. and if anything is wrong then reject the request and never send back new tokens.

I would place this under v3.5 Token-based Session Management. I don't know whether this is still an acceptable thing to worry about and whether the threat model is too low to bother about this control, but I think it just seems like a basic thing that developers should have placed some sort of validation for requests before allowing the scenario described to happen. If this is too low risk, then we could scrap it.

[jmanico]

I like this, but do we need a new OAuth2 section that covers https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics-18 ?

[csfreak92]

That is a great question though.. In wishful thinking I think we should add something OAuth2 best practices as well. I believe a lot of developers are not aware how to properly implement this on their applications.

[jmanico]

OAuth2 is a special protocol for just delegation and is often misused. But a dedicated section for OAuth in 5.0 is a great idea!

[csfreak92]

@jmanico, would you like me to draft a proposal for OAuth2 dedicated section? I believe that also deals with the original issue I opened here.

[jmanico]

Mr. @csfreak92 absolutely yes. And we can a get few of the OAuth2 security group folks to review. You can extract a lot from https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics to help you

[csfreak92]

Sounds good, let me thoroughly read it and then draft something soon (might be a bit later). :)

[csfreak92]

Just an update. I'm still actively working on this over spare time, please do not close the issue.

[tghosth]

Hi @csfreak92, any update on this, would like to get this prepared for 5.0

@set-reminder 1 month consider closing this issue

[octo-reminder]

⏰ Reminder
Saturday, January 7, 2023 12:00 AM (GMT+01:00)

consider closing this issue

[csfreak92]

@tghosth, @jmanico, as promised here is my initial draft for the OAuth requirements (with some references to OpenID Connect) as I have derived from the RFC: (https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics).

I still need to add the CWE mappings and more details for the explanatory paragraphs about each of them. I have two questions how we wish to present these new to be added requirements:

1. I propose a section 3.8.x to keep all OAuth requirements separate and easier for anyone using ASVS for security audits. If that is good for you guys, then shall I keep it like this where there's a separating subsection as per the security threats presented RFC that I followed? Also, shall I add separate explanatory paragraphs each or do you prefer all those explanations about Authorization Servers, Clients, Resource Servers, PKCE, etc. all in one huge chunk of paragraphs right after 3.8.x section title? Which one do you think is better?
2. If having a separate section for OAuth requirements seem quite too much and redundant (as we have token-based session management requirements), then I will need further help with splitting them to other 3.x sections.

I am sure I might be missing a few more things, but I just pushed my initial draft so that I don't keep holding this issue from moving forward and start the year right. :)

[elarlang]

I have not yet went into details, but first impression is - 18 requirements on one topic is a bit too much and maybe we need some abstraction.

I don't think we need all related OAuth requirements in one category if the same point is covered in general somewhere else. To have easy to follow "checklist" is maybe more testing guide approach.

Maybe we should have discussion in the issue first, not discussion over PR's. From PR's it's hard to follow later, why some requirements got in or why some changes were made.

Really nice input to work on!

[csfreak92]

@elarlang, yeah I do agree that 18 requirements for one topic is quite too much, honestly. I have this dilemma too, but there's another dilemma if I will cut them down.

An example is if you look at 3.8.12 - 3.8.14 in that draft, those all pertain to IDORs and ACLs which are covered somewhere in ASVS. However, OAuth-specific ones kind of make sense if our main objective in this issue is to teach developers and engineers how to properly use OAuth. This is one of my dilemmas which had been paralyzing me for a while what to do with it. I'd like to hear it from the community so that I can finally get that off my head. :)

All of these 18 are derived from the OAuth RFC which is quite comprehensive. Great yeah, having a discussion about the issue would be very helpful too, at least in my view for trimming down the PR.

[jmanico]

OAuth is complex. 18 requirements are critical. https://datatracker.ietf.org/doc/html/draft-ietf-oauth-security-topics has many more and is recent...

[jmanico]

I love this work! Steallar!

[elarlang]

Another topic is category - I don't think session management is the best place for covering OAuth. If it is 18 requirements (or even 10+) with splitting to different topics, it may be worth separate main category.

[jmanico]

OAuth is so important for _access delegation and API access that I do think it's critical for a new category.

Once we have the initial batch I can loop in some top tier experts to review.

And please be sure to include the requirements from the OAuth 2.0 BCP (Best Current Practice) for the most up to date requirements.

[octo-reminder]

🔔 @tghosth

consider closing this issue

[csfreak92]

@jmanico, almost those 18 requirements I have drafted there were straight from the RFC's best current practice. I may have left some out, which I will do another few passes to ensure at least the critical ones are included.

Also, if this will be a new category, what number shall I assign to it? Should it be next to Session Management category so that it stays relative?

[tghosth]

Hi @csfreak92,

This is really fantastic work, I can see how much effort you have put into it.

However, I am a little nervous that the level of detail is significantly more that we should probably have in the ASVS. The level of detail feels more like an OWASP cheatsheet. (I think this point could also be accurately made about parts of V2 but that is a different discussion for another day).

@jmanico what do you think?

@csfreak92 Do you think there is any way it could be trimmed down to key essentials?

For now I have created a dedicated branch for it.

[csfreak92]

Thanks @tghosth, @jmanico and @elarlang for chiming in your thoughts and praises! It is still draft at first stages, but I had a lot of dilemmas presenting these requirements as I said earlier that some of them may have been covered by ASVS in other sections (in some ways or another).

@tghosth, I have the same worry too as the level of detail was taken straight from the RFC which makes it too strict of an implementation guideline including the Authorization Server, Resource Server and other components that make up an OAuth setup.

I'll see what I can do to trim them down to the key essentials and push another commit soon. I'll add the subsection explanatory paragraphs too to explain such terms and their meaning.

[tghosth]

thanks, I think it deserves it's own section and I think it should obsolete 3.5.1

[csfreak92]

Hi @elarlang and @tghosth, let me take a look at adding OAuth 2.1 as well. Good idea if we can put it on ASVS 5.0 and be ahead. Let me do more research on it and push changes soon.

[jmanico]

@csfreak92 do you think targeting OAuth2.1 is possible. I agree that conceptually it would make for a good aim and better to be ahead of the curve.

The requirements that came from the OAuth 2 BCP is essentially what is being moved to OAuth 2.1

[jmanico]

I open a bit wider question.

Should we really be limited with OAuth 2.0 or should take direction to OAuth 2.1:

• https://oauth.net/2.1/
• https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09

Yes, it's draft, yes, it's not released etc.. but.. it is a patch for OAuth 2.0 known weaknesses.

For software components we have requirement:

Description L1 L2 L3 CWE

14.2.1 Verify that all components are up to date, preferably using a dependency checker during build or compile time. (C2) ✓ ✓ ✓ 1026
I interpret, that using features provided by OAuth 2.0 is using component with known weaknesses. There are reasons why OAuth 2.1 is proposed and for it makes sense to require to use technical solutions without known weaknesses.

In this context it means - can we just require everyone to use only PKCE flow for public OAuth clients (so-called "Standard Authorization Code flow" is not good enough). It also disallows using implicit flow and password grant.

Take into account, that it takes time to release v5.0 and then it takes years to release v6.0, between them we can not have breaking or major changes, we going to set the situation for years. I don't want to go with a solution, which is deprecated from the start.

For sure. Here are the main differences between OAuth 2.0 and 2.1 and topics we should cover to address 2.1.

• PKCE is required for all OAuth clients using the authorization code flow
• Redirect URIs must be compared using exact string-matching
• The Implicit grant (response_type=token) is omitted from this specification
• The Resource Owner Password Credentials grant is omitted from this specification
• Bearer token usage omits the use of bearer tokens in the query string of URIs
• Refresh tokens for public clients must either be sender-constrained or one-time use

[csfreak92]

The requirements that came from the OAuth 2 BCP is essentially what is being moved to OAuth 2.1

Yup, that's why I was still double checking if I missed something on the Best Current Practices from our current draft though most seems to cover OAuth 2.1 as you have pointed out @jmanico. There were some that we have omitted in the current OAuth 2.0 draft as it is covered in other ASVS chapters like the URL redirect handling (which is also in OAuth 2.1 exact string matching that maybe we should call out?).

[tghosth]

Hi everyone,

If you are just joining us, the draft chapter is currently here: V51 OAuth 2.0 Protocol

We'd love people to review the chapter and provide feedback. Before you review it, please read through this issue thread to collect the context and then feel free to open separate issues if you have specific questions or suggestions.

[jmanico]

I had some of my OAuth2 friends review this, this morning. Here are a few suggestions: * *PKCE Requirement:* Originally, PKCE was advised for public clients. Now, it's a best practice for all OAuth clients, including confidential clients, to prevent authorization code interception attacks. This recommendation needs clear emphasis. * *Refresh Token Strategy:* Implement rotating and expiring refresh tokens to avoid long-term misuse. This should be done in conjunction with sender-constraining mechanisms for enhanced security. * *Avoid Resource Owner Password Credentials Grant:* This grant type is not recommended due to security concerns. Instead, use the authorization code grant with PKCE. * *Consistent Terminology*: Use "Authorization Server" and "Resource Server" consistently throughout the document to avoid confusion, especially for newcomers. * *Clarify OAuth vs. OpenID Connect*: Emphasize that OAuth 2.0 focuses on authorization delegation, while OpenID Connect deals with authentication federation. Expand on this to help readers understand their distinct purposes. ** Prevent Authorization Server Mix-Up Attacks:* Include up-to-date strategies for mitigating mix-up attacks in environments with multiple Authorization Servers. Detail the use of the "iss" parameter and recommend additional checks like verifying the "aud" claim. **Detailed Scope and Audience Implementation:* Provide concrete examples of how to implement and validate access token restrictions based on scope and audience to offer actionable guidance.

[csfreak92]

I had some of my OAuth2 friends review this, this morning. Here are a few suggestions: *

Thanks Jim! I'll take a look and create a PR to address these and bundle the OAuth 2.1 additions that are needed.

[TmmmmmR]

It's a wonderful addition to have a dedicated section for OAuth.

Regarding section 51.1.4 token rotation can mitigate token replay attacks, it cannot entirely prevent them.

Consider the scenario where an attacker exploits an XSS in a client-side JS application that performs silent token refresh. This allows the attacker to intercept all token refresh operations. In this case, the attacker simply waits until the client becomes inactive and then catch the latest refresh token to obtain fresh tokens. So, as long as the attacker don't use the stolen refresh tokens immediately, the authorization server's detection mechanisms remain inactive.

This article describe this scenario with more details : https://www.pingidentity.com/en/resources/blog/post/refresh-token-rotation-spa.html

[TobiasAhnoff]

Hi! I would like to contribute with feedback and have a few initial questions to get better understanding of goals, level of detail etc, before adding feedback as more specific issues.

To start with, I think it is good that ASVS adds guidance on OAuth and OIDC, since many web applications built today use OAuth/OIDC in some way and technically detailed guidance/requirements are a little bit "hidden" in specs and RFCs. But a concern is that it will be challenging for ASVS to summarize and highlight the most important things, get the right amount of detail and align with all "best current practices" as they change...

Perhaps this will make my thoughts clearer:

In the first section it is stated that this "summarizes the best current security practices for OAuth 2.0 as derived from its RFC 6750 and 6749" and OIDC is also is mentioned.

Two set of specs for OAuth2/OIDC that are often referenced and used for guidance when building and testing OAuth2/OIDC solutions are https://oauth.net/2.1/ (in particular https://datatracker.ietf.org/doc/html/draft-ietf-oauth-browser-based-apps) and https://openid.net/wg/fapi/specifications/ (in particular https://openid.bitbucket.io/fapi/fapi-2_0-security-profile.html, applicable for domains with high security requirements like finance and healthcare etc).

Have you considered adding additional requirements and recommended mitigations found there?

For example, FAPI 2.0 defines about 30 verifications for the authorization server while ASVS currently has 6, in particular ASVS does not mention PAR. And if we compare FAPI and ASVS guidance for resource servers ASVS has 3 requirements while FAPI has 5, which looks like this, some overlap, but also differences.

5.3.4. Requirements for resource servers
The FAPI 2.0 endpoints are OAuth 2.0 protected resource endpoints that return protected information for the resource owner associated with the submitted access token.
Resource servers with the FAPI endpoints

1. shall accept access tokens in the HTTP header as in Section 2.1 of OAuth 2.0 Bearer Token Usage [RFC6750];
2. shall not accept access tokens in the query parameters stated in Section 2.3 of OAuth 2.0 Bearer Token Usage [RFC6750];
3. shall verify the validity, integrity, expiration and revocation status of access tokens;
4. shall verify that the authorization represented by the access token is sufficient for the requested resource access and otherwise return errors as in Section 3.1 of [RFC6750]; and
5. shall support and verify sender-constrained access tokens using one or both of the following methods:

• MTLS as described in [RFC8705],
• DPoP as described in [RFC9449].

I understand if it is hard to answer this open question, but it would be interesting if you could elaborate some more on this, for example why there are differences and what role ASVS is meant to play in addition to guidance and requirements found at https://oauth.net/2.1/ and https://openid.net/wg/fapi/specifications/

Thanks for all work with ASVS, it is a great resource!
Please let me know if you would like me to submit more concrete feedback in issues.

[elarlang]

Hi @TmmmmmR - I have addressed the issue from another perspective, such as do not allow any refresh tokens to the browser at all. See #1916 (comment) # Discussion/Proposal 1.

If you agree it is the same topic and the same problem, please continue the discussion in the other issue.

[elarlang]

Hi, @TobiasAhnoff - I agree with your point of view and (y) for the attitude to understand the situation first.

The situation at the moment:

• The entire OAuth paragraph is the first draft. It is published to get feedback and based on that to validate and improve requirements.
• If ASVS already has requirements to address certain issues, such as validating JWT, then those requirements are not duplicated to the OAuth section.

The action plan here can be - if you feel, that the OAuth paragraph is missing some requirement, then just point it out. If it is covered somewhere else, we can then say it. For me it's probably faster to say is it covered than for you to investigate the entire ASVS for each potential proposal.

[TobiasAhnoff]

Hi, @TobiasAhnoff - I agree with your point of view and (y) for the attitude to understand the situation first.

The situation at the moment:

* The entire OAuth paragraph is the first draft. It is published to get feedback and based on that to validate and improve requirements.

* If ASVS already has requirements to address certain issues, such as validating JWT, then those requirements are not duplicated to the OAuth section.

The action plan here can be - if you feel, that the OAuth paragraph is missing some requirement, then just point it out. If it is covered somewhere else, we can then say it. For me it's probably faster to say is it covered than for you to investigate the entire ASVS for each potential proposal.

👍 I will structure my feedback and add some issues during this week, some of it might be covered in other parts of ASVS, but faster if you note if it is covered or not, thank you!

[TobiasAhnoff]

I have added two Github issues, hope this will be a good way to provide feedback on the OAuth chapter
#1924
#1925

[elarlang]

I have added two Github issues, hope this will be a good way to provide feedback on the OAuth chapter #1924 #1925

Thank you, I'll take a look in few days.

[tghosth]

@csfreak92 would be good to get your feedback as well!

[csfreak92]

Hi @tghosth, will get back to this thread once I got back home from traveling. For sure will review all the feedback from the community for the OAuth 2.0 section. Cheers!

[csfreak92]

Updates from my end evaluating @jmanico's comments with my comments. Will push a PR with the OAuth 2.1 draft together with updates and notes from these comments :) @elarlang, @TobiasAhnoff, @jsherm-fwdsec, @tghosth.

I had some of my OAuth2 friends review this, this morning. Here are a few suggestions:

• PKCE Requirement: Originally, PKCE was advised for public clients. Now, it's a best practice for all OAuth clients, including confidential clients, to prevent authorization code interception attacks. This recommendation needs clear emphasis.
  ---> [Covered with 51.2.2, but adding this for more emphasis]

• Refresh Token Strategy: Implement rotating and expiring refresh tokens to avoid long-term misuse. This should be done in conjunction with sender-constraining mechanisms for enhanced security.
  ---> [Covered with 51.1.4]

• Avoid Resource Owner Password Credentials Grant: This grant type is not recommended due to security concerns. Instead, use the authorization code grant with PKCE.
  ---> [Covered and added to the ### Resource Owner Password Credentials Grant paragraph explanation at the bottom]

• Consistent Terminology: Use "Authorization Server" and "Resource Server" consistently throughout the document to avoid confusion, especially for newcomers.
  ---> [Covered in the whole chapter unless I am missing something?? Can someone point anything that was not consistent so that I can fix it with an updated PR :) ]

• Clarify OAuth vs. OpenID Connect: Emphasize that OAuth 2.0 focuses on authorization delegation, while OpenID Connect deals with authentication federation. Expand on this to help readers understand their distinct purposes.
  ---> [This is ongoing work with other folks during the meeting regarding OAuth 2.0 and OpenID Connect. Noted and will be kept in mind]

• Prevent Authorization Server Mix-Up Attacks: Include up-to-date strategies for mitigating mix-up attacks in environments with multiple Authorization Servers. Detail the use of the "iss" parameter and recommend additional checks like verifying the "aud" claim.
  ---> [Covered with 51.2.1 and reference links at the bottom. Noted about the "aud" claim and will keep it in mind in the updated PR that is on the works with the other folks during the meeting :) ]

• Detailed Scope and Audience Implementation: Provide concrete examples of how to implement and validate access token restrictions based on scope and audience to offer actionable guidance.
  ---> [This is ongoing work with other folks during the meeting regarding OAuth 2.0 and OpenID Connect. Noted and will be kept in mind for creating a further concrete example and guidance for this in the updated PR. :) ]

[ThunderSon]

Hey all 👋
Great work on this piece. As I have interest and expertise in OAuth and OIDC, I'll give this a look in the coming week(s)

My first question if you don't mind, why is everything L3? Is there a basis for how we are setting them?
I can see several of those can be split between L1->3 based on priority and conformance with the protocols at hand and profile required.

Looking forward to better understand the work set here behind this :)

[elarlang]

Hey @ThunderSon - we are waiting for your input :) As it is valid for every opened issue, but on the topic, all OAuth/OIDC related issues are with label V51 Group issues related to OAuth

Levels - I can not see L3, everything is L1 at the moment. But anyhow, we still don't have levels defined and time should not be wasted at the moment for the discussion of levels. In the big picture, the same is for chapter texts - let's get necessary requirements in first, rest of it comes later (as a result of requirements and how those are divided into chapters).

[csfreak92]

Update from @jmanico's comments on OAuth 2.1:

Should we really be limited with OAuth 2.0 or should take direction to OAuth 2.1:

For sure. Here are the main differences between OAuth 2.0 and 2.1 and topics we should cover to address 2.1.

• PKCE is required for all OAuth clients using the authorization code flow ---> [Covered and added some verbiage for OAuth 2.1 coverage in 51.2.2]

• Redirect URIs must be compared using exact string-matching ---> [Added new requirement numbers 51.2.5 and 51.1.7 to cover for this ]

ADDED on my PR #1971
51.2.5 Verify that Clients do not expose URLs that forward the user's browser to arbitrary URIs obtained from a query parameter ("open redirectors") and any URI redirects must be compared using exact string-matching.

51.1.7 Verify that the Authorization Server does not expose URLs that forward the user's browser to arbitrary URIs obtained from a query parameter ("open redirectors") which can enable exfiltration of authorization codes and access tokens. Redirect URIs must be compared using exact string-matching.

• The Implicit grant (response_type=token) is omitted from this specification ---> [Should we add some language to say this is a big no, no thing to use? In my initial pull requests, it was pointed out by Josh that we should have language as "use this instead of avoid using this..." I can always add that to my pull request, but just want to make sure we are all on the same page. What are everyone's thoughts about this? ]

• The Resource Owner Password Credentials grant is omitted from this specification ---> [Covered by adding some sentence at the end of the ### Resource Owner Password Credentials Grant]

• Bearer token usage omits the use of bearer tokens in the query string of URIs ---> [NEED HELP to research on how this helps and what it prevents... I am not sure about this part]

• Refresh tokens for public clients must either be sender-constrained or one-time use ---> [Covered already with 51.1.4]

Ping @elarlang, @TobiasAhnoff, @tghosth and @jsherm-fwdsec