Request: credentials property

[izahirclemencia]

What happened?

The library currently lacks support for including credentials such as cookies with requests made through the API. This feature is critical for interacting with endpoints that require the use of credentials for various purposes such as extra measures for authentication.

https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API

Version

v2.3.0

Runtime

Browser

Runtime Details

18.18.0

Code to reproduce

Current Behavior:

When using the library to make requests, there is no option available to include credentials.
This results in failed requests when interacting with servers requiring credentials.
Expected Behavior:

The library should provide an option allowing developers to include credentials with requests.
This option should support different credential inclusion types such as 'include', 'same-origin', and 'omit'.
Steps to Reproduce:

Attempt to make a request to an endpoint that requires credentials.
Observe that there is no option to include credentials, and the request fails due to the absence of credentials.

Required

• I have searched the issues tracker and discussions for similar topics and couldn't find anything related.
• I agree to follow this project's Code of Conduct

[panva]

Hi @izahirclemencia

What requests using the RFC6749 framework (or its related documents and extensions) depend on credentials (cookies in this case)?

[izahirclemencia]

As a form of credentials, cookies can be involved in various steps of the OAuth 2.0 flow, primarily for maintaining sessions and preserving the state between requests. It is not explicitly stated since the RFC6749 framework mainly focuses on authorization.

[panva]

Please elaborate on concrete examples, when, during the standard oauth dance and subsequent API access using the Access Token, do you require cookies to be sent?

[izahirclemencia]

With secure httpOnly cookies we can do the following to enhance security:

User Authorization:
Keeps users logged in during authorization, meaning session cookies reduce login hassles when granting permissions.

Redirect URI:
Stores temporary state between the auth request and callback, ensuring secure and seamless transitions during redirects

Refreshing Tokens:
Attaching secure cookies to refresh token requests as an extra measure of security.

[izahirclemencia]

3.1. Authorization Endpoint

The authorization endpoint is used to interact with the resource
owner and obtain an authorization grant. The authorization server
MUST first verify the identity of the resource owner. The way in
which the authorization server authenticates the resource owner
(e.g., username and password login, session cookies) is beyond the
scope of this specification.
https://www.rfc-editor.org/rfc/rfc6749

3.2.3. Token Response

Authorization servers SHOULD determine, based on a risk assessment and their own policies, whether to issue refresh tokens to a certain client. If the authorization server decides not to issue refresh tokens, the client MAY obtain new access tokens by starting the OAuth flow over, for example initiating a new authorization code request. In such a case, the authorization server may utilize cookies and persistent grants to optimize the user experience.
https://datatracker.ietf.org/doc/html/draft-ietf-oauth-v2-1-09

I highlighted the points where the RFC6749 mentions cookies for you & made prepared the necessary changes: #81

[panva]

Thank you @izahirclemencia.

User Authorization: Keeps users logged in during authorization, meaning session cookies reduce login hassles when granting permissions.

Redirect URI: Stores temporary state between the auth request and callback, ensuring secure and seamless transitions during redirects

3.1. Authorization Endpoint
...

The authorization endpoint is not accessed via fetch() at all and its interaction with the user-agent is not orchestrated by oauth4webapi.

3.2.3. Token Response

... the client MAY obtain new access tokens by starting the OAuth flow over, for example initiating a new authorization code request. In such a case, the authorization server may utilize cookies and persistent grants to optimize the user experience.

This only means the authorization server may reject the Access Token Request based on its policy and that the client may start a new authorization, in which case it would start over with a new redirect to the authorization endpoint which then may of course utilize sessions and persisted grants to make the subsequent redirects as seamless as possible. Again, not something that you can a) control as a client and b) something that the client needs to introduce changes for because (see the quote above) the authorization endpoint is not accessed via fetch() at all and its interaction with the user-agent is not orchestrated by oauth4webapi.

Refreshing Tokens: Attaching secure cookies to refresh token requests as an extra measure of security.

DPoP is the mechanism to tie the authorization request, subsequent token endpoint interaction (initial authorization code exchange as well as future refresh token exchanges), and protected resource requests to a user-agent (via a unique non-extractable CryptoKey instance generated and stored in the browser's IndexedDB).

[izahirclemencia]

1. That's correct. We set the identifier cookie when the user is navigated to the Authorization Endpoint following the redirection.
2. This identifier cookie is crucial for us while processing the authenticated requests as it helps in maintaining the integrity and security of the user sessions during the authorization process.
3. Besides using DPoP, we are implementing an additional layer of security using cookies for authenticated requests to consume refresh tokens for authorization.

[izahirclemencia]

Oh and by the way, DPoP is a mechanism to tie these requests to a specific client (application) rather than directly to a user-agent (the actual user) :)

[panva]

That entirely depends on how you use dpop, eg on the server with a confidential application vs on the user-agent as a public client. If the latter, which I assume is what you're after given your request to include cookies, a dpop private key generated for each user in the browser's non-extractable storage is no different in representing a given user-agent than a server set httpOnly session cookie would be.

[izahirclemencia]

If you use DPoP Conform RFC 9449, DPoP tokens are designed to proof that the client is the client, nothing else. The HTTP-only cookies serve fundamentally different purposes ;) I will fork the repo np

[panva]

I think you're missing my point, but anyway, since you're rolling your own proprietary oauth server you might as well roll your own client for it. Forking is a better choice than including proprietary mechanism.

[panva]

I'm looking for feedback for #94 which would enable you to pass whatever you want to fetch.