User authentication API for applications

[chlowell]

The new API in this PR is intended for applications using credentials which require user interaction to authenticate (DeviceCodeCredential and InteractiveBrowserCredential).

Here's what it does and how:

• Allow applications to control the timing of interactive authentication prompts
  • The authenticate method begins interactive authentication. Applications can call it at their convenience.
  • authenticate accepts optional scopes, allowing an application which knows the scopes it needs to cache an access token for them before sending service requests
  • constructor argument disable_automatic_authentication configures get_token to raise AuthenticationRequiredError rather than immediately begin interactive authentication whenever it's necessary
• Enable applications to persist authentication details so they don't need to prompt for authentication every time they run
  • DeviceCodeCredential and InteractiveBrowserCredential use a persistent cache on supported platforms (today, Windows). Constructor argument disable_persistent_cache allows opting out, configuring a credential to cache in memory only.
  • authenticate returns a serializable AuthenticationRecord
  • applications can initialize a credential with an AuthenticationRecord, enabling that credential to use data cached during prior executions

Usage

Prompt a user to authenticate, store the record

credential = InteractiveBrowserCredential()
record = credential.authenticate()
record_json = record.serialize()

with open(RECORD_PATH, 'w') as f:
    f.write(record_json)

Initialize a credential with a record

with open(RECORD_PATH, 'r') as f:
    record_json = f.read()

deserialized_record = AuthenticationRecord.deserialize(record_json)
credential = InteractiveBrowserCredential(authentication_record=deserialized_record)

Prevent automatic authentication prompts

Applications decide how to respond when user interaction is required. This example demonstrates the simplest case, authenticating immediately and retrying a request, to show the API:

credential = InteractiveBrowserCredential(disable_automatic_authentication=True)
try:
    result = service_client.do_something()
except AuthenticationRequiredError as ex:
    requested_scopes = ex.scopes
    credential.authenticate(scopes=requested_scopes)

    result = service_client.do_something()

Closes #11128, closes #11043, closes #10278, closes #9744

[xiangyan99]

Why AuthenticationRequiredError is a subclass of CredentialUnavailableError?

It seems to me AuthenticationRequiredError is a HttpRequestError but CredentialUnavailableError may be not?

[chlowell]

Silent authentication can succeed or fail without sending a request. The question is really about the behavior of chained credentials: if a credential is configured to authenticate silently only, should a chain try its next credential when silent auth fails? I lean toward "yes", hence CredentialUnavailableError. What do you think?

[schaabs]

It can't go under HttpRequestError, because as Charles said there might have been no request made when we determine that authentication is required. As far as if it should fall under CredentialUnavailableError, i.e. allow other credentials in a chain to be attempted, I also lean towards yes. However, as we develop this more we might find we have to tweak this over the course of the preview.