[Core] Update AccessToken

[pvaneck]

Earlier, refresh_on was added to AccessToken as an optional property. This had unintended breaking side effects. The azure-servicebus package recently ran into issues when they were unpacking the get_token() call:

access_token, self._token_expiry_on = self._credential.get_token(self._endpoint)

This yielded: ValueError: too many values to unpack (expected 2).

To avoid breaking users who might be unpacking like this, this change converts AccessToken into a DataClass. A NamedTuple and frozen DataClass are functionally the same for our purposes, but a DataClass provides more flexibility. Here, I override the __iter__, __getitem__, and __len__ methods to provide the same functionality as previously.

---

Why we need refresh_on?

In some cases, our current strategy of requesting a new token if it is within five minutes of expiration is not sufficient. Some customers have long-running jobs that span longer than five minutes and would like earlier refresh times to avoid authentication issues causing interruptions. In some cases, tokens can contain info on when it can/should be refreshed. We want to be able to use that info in our BearerTokenCredentialPolicies.

Issue: #35473

[azure-sdk]

API change check

APIView has identified API level changes in this PR and created following API reviews.

azure-core

[pvaneck]

This change should avoid breaking people using AccessToken unless others can think of more scenarios that I can test.

The following usage scenarios are tested and still work as it did previously:

access_token = AccessToken("token", 42)
assert access_token.token == "token"
assert access_token.expires_on == 42

Unpacking (not a common occurrence, at least in our SDKs) still works as before:

token, expires_on = AccessToken("token, 42")
assert token == "token"
assert expires_on == 42

# Unpacking all values still works, but this assumes refresh_on is set:
token, expires_on, refresh_on = AccessToken("token", 42, 21)
assert token == "token"
assert expires_on == 42
assert refresh_on == 21

For the rare occurrence of people using numeric-indices to access values, this still works

token = AccessToken("token", 42)
assert token[0] == "token"
assert token[1] == 42
assert token[:2] == ("token", 42)

The BearerTokenCredentialPolicies will still work even if refresh_on doesn't exist as a property for the saved token in the case people implement their own credentials that return a different (non-core) declaration of an AccessToken (even though typing might not be happy, it'll still work). There is also a test for this.

Azure CLI does not import Azure Core's AccessToken or use Azure Core's BearerTokenCredentialPolicy, so no qualms there.

[johanste]

@catalinaperalta , we should make sure that our breaking change tool catches additions of values to named tuples are flagged as breaking....

[pvaneck]

The following also works for all test cases if we would prefer to keep it NamedTuple:

class AccessToken(NamedTuple):
    """Represents an OAuth access token."""

    token: str
    expires_on: int
    refresh_on: Optional[int] = None

    def __iter__(self) -> Any:
        return (getattr(self, field) for field in self._fields if getattr(self, field) is not None)

    def __getitem__(self, index: int) -> Any:
        return tuple(self)[index]

    def __len__(self) -> int:
        return len(tuple(self.__iter__()))

The only caveat that I can see with this compared to dataclasses deals with typing:

Functionally, this still works.

[xiangyan99]

@catalinaperalta , we should make sure that our breaking change tool catches additions of values to named tuples are flagged as breaking....

We will implement it in a non-breaking way which is not supposed to be caught.

[xiangyan99]

We also want to test the case:

token, expires_on = AccessToken(token="token", expires_on=42, refresh_on=21)
assert token == "token"
assert expires_on == 42