Add support for Federated Connection Access Token (#1911)

[nandan-bhat]

📋 Changes

This PR adds support for getFederatedConnectionAccessToken({ connection: string; login_hint?: string }), which can be used to obtain federated connection access token using the oauth/token endpoint.

In order to retrieve a federated connection access token, we call oauth/token using the following payload:

{
  "connection": "<connection(e.g. google-oauth2)>",
  "subject_token_type": "urn:ietf:params:oauth:token-type:refresh_token",
  "subject_token": "<refresh_token>",
  "requested_token_type": "http://auth0.com/oauth/token-type/federated-connection-access-token",
  "client_id": "<client_id>",
  "client_secret": "<client_secret>",
  "grant_type": "urn:auth0:params:oauth:grant-type:token-exchange:federated-connection-access-token"
}

The retrieved token will also be stored in the session store, comparable to regular session information.

Stateless
As the browser has a limit to the size of the cookie, each federated connection access token is stored in its own cookie, using the __FC_{index} name.

image

When an application needs to us many access tokens, it's recommended to consider using a stateful session store.

Stateful
For the stateful session store, nothing changes other than the fact that the provided SessionData, now has an additional federatedConnectionTokenSets property, being either undefined, or an array of FederatedConnectionTokenSet.

Just like getAccessToken(), the newly added getFederatedConnectionAccessToken() can not write to the cookies when called from a Server Component, and will log a warning when either of these two methods are called from such Server Component.

📎 References
N/A

🎯 Testing
I have tested this against the only environment that has the feature enabled, and I ensured the following scenario's:

When not logged in, calling getFederatedConnectionAccessToken throws the MISSING_REFRESH_TOKEN error.
When logged in, and no Federated Connection Access Token is in the cache, a call to oauth/token is mad, the resulting access token is stored in the stateless or stateful session store and returned.
When logged in, and a non expired Federated Connection Access token is in the cache, no call to oauth/token is made, and the access token from the cache is returned.
When logged in, and an expired Federated Connection Access token is in the cache, a call to oauth/token is mad, the resulting access token is stored in the stateless or stateful session store and returned.
When logging out, the __FC cookies are also removed.

[codecov-commenter]

Codecov Report

Attention: Patch coverage is 50.88968% with 138 lines in your changes missing coverage. Please review.

Project coverage is 72.64%. Comparing base (9cccf91) to head (80218b6).

Files with missing lines	Patch %	Lines
src/server/client.ts	0.00%	103 Missing ⚠️
src/server/session/stateless-session-store.ts	67.08%	26 Missing ⚠️
src/server/auth-client.ts	89.77%	9 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1921      +/-   ##
==========================================
- Coverage   74.69%   72.64%   -2.05%     
==========================================
  Files          19       19              
  Lines        1379     1601     +222     
  Branches      210      232      +22     
==========================================
+ Hits         1030     1163     +133     
- Misses        342      431      +89     
  Partials        7        7              

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.