feat: FGI-1573 add MRRT support

[sam-muncke]

Changes

Introduces ability to use Multi-resource Refresh Tokens (MRRT) to obtain access tokens from multiple audiences using a single refresh token.

• Adds optional audience and scope parameters to get_access_token() method
• Allows the ability to configure default scopes for multiple audiences in the ServerClient configuration

References

https://auth0team.atlassian.net/browse/FGI-1573

Testing

See included docs for testing instructions.

• 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

[github-actions]

Claude finished @sam-muncke's task —— View job

---

Code Review Complete

• Read PR diff and understand changes
• Read project architecture documentation
• Perform code quality review
• Perform security review
• Perform performance review
• Provide overall assessment

---

Overall Assessment

❌ This PR requires fixes before merging. While the MRRT feature implementation is well-structured with comprehensive test coverage, there are several critical issues related to audience handling consistency, edge case validation, and a syntax error in documentation that must be addressed.

Key Issues:

• Inconsistent None vs "default" audience handling across the codebase could cause token lookup failures
• Missing null-safety checks in scope splitting logic
• Syntax error in documentation example (missing comma)
• Potential security concern with unvalidated audience values
• Edge cases in scope merging logic when handling empty strings

Strengths:

• Excellent test coverage for MRRT scenarios
• Clean separation of concerns with helper methods
• Good documentation explaining the feature
• Backward compatibility maintained

---

Job Run | Branch: FGI-1573_mrrt_support

[kishore7snehil]

When multiple coroutines concurrently request a token for the same (audience, scope) that isn't cached, they all execute this line simultaneously, making redundant refresh token requests to Auth0.
We can build something referring to this Next.js Implementation

[sam-muncke]

This is the case regardless of whether MRRT is being used or not. Prior to this PR, the same issue exists. I think adding a caching layer to this SDK is beyond the scope of this implementation. Also even if we were to add this, it would likely best be as a framework specific implementation rather than the generic python lib. How effective a local memory request cache would be would be very dependent on what framework/infrastructure was using the library. Arguably this would best be handled as a caching StateStore implementation, given that as soon as we receive the token, we update the StateStore and return. Adding an additional abstraction for request cache seems unnecessary.

[kishore7snehil]

I understand the scope concern, but I want to clarify the issue isn't about "caching" rather it's about request deduplication for in-flight requests.

StateStore caching helps with sequential requests (request 1 stores token -> request 2 reads from cache).
But for concurrent requests, all 5 coroutines check StateStore at the same time before any can write. This results in unnecessary duplicate API calls.

[sam-muncke]

I understand the point you are trying to make but the value this adds beyond a just a stateful StateStore is questionable and highly dependent on the framework using this SDK (and more practically the infrastructure setup of the specific application is being run on).

Regardless in as much as this is an issue, its an issue that exists independently of MRRT. Its no more or less of a problem before or after this PR. If its an optimisation that you think is worth while, I suggest it is done a standalone improvement to the SDK in a future piece of work.

[kishore7snehil]

When requesting an access token for an audience not in the MRRT policy, the SDK returns a cached token for a different audience without raising an error or warning.

[sam-muncke]

This is the behaviour of MRRT and consistent with all the other SDKs. This concern has been raised with the Sessions team and they address this by returning the requested resource in the the response for oauth/token in order for consumers to validate it in the future but as of right no, that does not exist.

[kishore7snehil]

The method returns or constructs a response that claims audience: X but the actual JWT has aud: Y

[sam-muncke]

Is this a reference to when MRRT is not configured or another scenario. If it is - see my other comments.

[kishore7snehil]

When Auth0 rejects the audience, the SDK may be using DEFAULT_AUDIENCE_STATE_KEY without informing the caller.

[sam-muncke]

I'm not sure what you mean by "rejects the audience" since Auth0 will not reject any audience you pass to oauth/token for the RT exchange - it will either use it and return the correct AT or ignore it and return an AT for the original audience used to obtain the RT. As mentioned above, I agree with you that this second behaviour is not ideal but that is the current behaviour of the MRRT feature, there is some complexity over this and it has been raised with the Sessions team. I discussed the possibility of erroring in the SDK with @frederikprijck and he advised not to error in this case and the handling here is consistent with the other SDKs.

As for the use of DEFAULT_AUDIENCE_STATE_KEY, this is only used when no audience is specified in the default auth params or the request auth params. This actually resolves an issue whereby default was always used as the state key due to the fact that the previous code was attempting to pull the audience from the /oauth/token response but would never find it because that endpoint doesnt return it. This was sort-of fine for single audience applications now we're introducing more.