feat: Adds Token Vault support

[kailash-b]

Changes

Adds Token Vault support to the Auth0.AuthenticationApi package. Token Vault lets a private client exchange an Auth0 token for an access token issued by one of Auth0's federated connections (Google, Facebook, etc.), so the app can call that provider's APIs on the user's behalf.

Classes/methods added:

• New model FederatedConnectionAccessTokenRequest (implements IClientAuthentication) — carries SubjectToken, SubjectTokenType, Connection (required), optional LoginHint, Nonce, and the standard client-auth members (ClientId, ClientSecret, ClientAssertionSecurityKey, ClientAssertionSecurityKeyAlgorithm, SigningAlgorithm).
• New overload Task<AccessTokenResponse> GetTokenAsync(FederatedConnectionAccessTokenRequest request, CancellationToken) on IAuthenticationApiClient / AuthenticationApiClient. Builds the request body, applies client authentication, hardcodes requested_token_type, POSTs to /oauth/token, and reuses the existing AccessTokenResponse (the federated token is returned in AccessToken; issued_token_type is surfaced via IssuedTokenType).
• New TokenType constants: RefreshToken (urn:ietf:params:oauth:token-type:refresh_token) and FederatedConnectionAccessToken (http://auth0.com/oauth/token-type/federated-connection-access-token).

Usage:

var auth = new AuthenticationApiClient("YOUR_AUTH0_DOMAIN");

var tokenResponse = await auth.GetTokenAsync(new FederatedConnectionAccessTokenRequest
{
    ClientId = "YOUR_CLIENT_ID",
    ClientSecret = "YOUR_CLIENT_SECRET",
    SubjectToken = "THE_AUTH0_ACCESS_TOKEN",
    SubjectTokenType = TokenType.AccessToken,
    Connection = "google-oauth2",
    LoginHint = "THE_GOOGLE_USER_ID"   // optional
});

Console.WriteLine($"Federated Access Token: {tokenResponse.AccessToken}");

References

• Auth0 docs: Access token exchange with Token Vault

Testing

• This change adds unit test coverage
• This change adds integration test coverage
• This change has been tested on the latest version of the platform/language or why not

Checklist

• I have read the Auth0 general contribution guidelines
• I have read the Auth0 Code of Conduct
• All existing and new tests complete without errors

[codecov]

Codecov Report

❌ Patch coverage is 97.67442% with 1 line in your changes missing coverage. Please review.
✅ Project coverage is 25.53%. Comparing base (3fc2a21) to head (5b53c29).

Files with missing lines	Patch %	Lines
...pi/Models/FederatedConnectionAccessTokenRequest.cs	90.00%	1 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##           master    #1064      +/-   ##
==========================================
+ Coverage   25.51%   25.53%   +0.02%     
==========================================
  Files        3155     3156       +1     
  Lines      148277   148320      +43     
  Branches    10018    10021       +3     
==========================================
+ Hits        37832    37874      +42     
- Misses     108132   108133       +1     
  Partials     2313     2313              

Flag	Coverage Δ
authIntTests	2.38% <97.67%> (+0.02%)	⬆️
mgmtIntTests	24.51% <0.00%> (-0.01%)	⬇️
unittests	0.22% <0.00%> (-0.01%)	⬇️

Flags with carried forward coverage won't be shown. Click here to find out more.

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

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[nandan-bhat]

This doc says the subject token must be an Auth0 refresh token, but the example, every test in this PR, and the Token Vault docs all use an access token (subject_token_type = urn:ietf:params:oauth:token-type:access_token). The Auth0 docs describe subject_token as the Auth0 access token that identifies the user.

The class remark on line 11 and the SubjectTokenType note on line 25 say the same refresh token thing, so all three spots contradict what the code actually does. Since this text shows up in IntelliSense, a user following it would pass a refresh token and get a 400. Can we update these to say access token (TokenType.AccessToken)? If refresh tokens are also valid, then let us word it as access or refresh token, but right now nothing exercises the refresh token path.

[kailash-b]

Addressed in 5b53c29
subject_token_type can be both AccessToken or RefreshToken. Updated the code docs to reflect the same.

[nandan-bhat]

SubjectToken and SubjectTokenType are both required but we add them to the body with no check. We already throw a clear ArgumentException for a missing Connection a few lines up, so it feels odd to let these two through and get back an opaque 400 from the server.

Can we add the same kind of early null or empty guard for SubjectToken and SubjectTokenType?

[kailash-b]

Addressed in 5b53c29
Added validation

[nandan-bhat]

This RefreshToken constant does not seem to be used anywhere in the feature. All the code paths and tests use AccessToken. It looks like it was added only to support the refresh token wording in the request model, which I think is not correct (left a note there).

If refresh token subjects are genuinely supported, can we add a test that uses this? Otherwise I would drop it so we do not signal a path that does not work. Low priority either way.

[kailash-b]

Addressed in 5b53c29
This is a public property. Also, now we have added test cases that use this RefreshToken as well.