[Identity] Merging feature/identity/140 back to master (Azure#17083)

* {Identity] Prototype TokenCache option to enable sharing cache across credentials and executions

* prototype updates

* adding client side user authentication samples

* adding persistent token cache options

* fix compilation issues

* adding token cache samples

* fix header

* reword

* updating API spec

* temporary fix for AzureStack eng bits

* workaround for MSA account

* ignore failure test cases temporarily

* update api sig

* update version

* update change log

* update version

* fix changelog

* fix msal cache

* update msal version

* removing AuthenticationTokenRecord workaround

* adding configuration to SharedTokenCacheCredential

* upgrading msal

* update snippet

* [Identity] prepare for 1.4.0-beta.1 release (Azure#16021)

* Updating changelog for 1.4.0-beta.1 release

* updating MSAL dependency

* Increment package version after release of Azure.Identity (Azure#16028)

* make AuthenticationRecord public

* making APIs public that got switched to internal in merge

* adressing PR feedback

* add tests for new STCC options

Co-authored-by: Erich(Renyong) Wang <[email protected]>
Co-authored-by: Azure SDK Bot <[email protected]>

Author: 3 people

sdk/identity/Azure.Identity/CHANGELOG.md

@@ -1,7 +1,13 @@
 # Release History
+## 1.4.0-beta.2 (Unreleased)
 
-## 1.4.0-beta.1 (Unreleased)
 
+## 1.4.0-beta.1 (2020-10-15)
+
+### New Features
+- Redesigned Application Authentication APIs
+  - Adds `TokenCache` and `PersistentTokenCache` classes to give more user control over how the tokens are cached and how the cache is persisted.
+  - Adds `TokenCache` property to options for credentials supporting token cache configuration.
 
 ## 1.3.0 (2020-11-12)
 

sdk/identity/Azure.Identity/api/Azure.Identity.netstandard2.0.cs

@@ -0,0 +1,105 @@
+# Client side user authentication
+
+Client side applications often need to authenticate users to interact with resources in Azure. Some examples of this might be a command line tool which fetches secrets a user has access to from a key vault to setup a local test environment, or a GUI based application which allows a user to browse storage blobs they have access to. This sample demonstrates authenticating users with the `Azure.Identity` library.
+
+## Interactive user authentication
+
+Most often authenticating users requires some user interaction. Properly handling this user interaction for OAuth2 authorization code or device code authentication can be challenging. To simplify this for client side applications the `Azure.Identity` library provides the `InteractiveBrowserCredential` and the `DeviceCodeCredential`. These credentials are designed to handle the user interactions needed to authenticate via these two client side authentication flows, so the application developer can simply create the credential and authenticate clients with it.
+
+
+## Authenticating users with the InteractiveBrowserCredential
+
+For clients which have a default browser available, the `InteractiveBrowserCredential` provides the most simple user authentication experience. In the sample below an application authenticates a `SecretClient` using the `InteractiveBrowserCredential`.
+
+```C# Snippet:Identity_ClientSideUserAuthentication_SimpleInteractiveBrowser
+var client = new SecretClient(new Uri("https://myvault.azure.vaults.net/"), new InteractiveBrowserCredential());
+```
+As code uses the `SecretClient` in the above sample, the `InteractiveBrowserCredential` will automatically authenticate the user by launching the default system browser prompting the user to login. In this case the user interaction happens on demand as is necessary to authenticate calls from the client.
+
+
+## Authenticating users with the DeviceCodeCredential
+
+For terminal clients without an available web browser, or clients with limited UI capabilities the `DeviceCodeCredential` provides the ability to authenticate any client using a device code. The next sample shows authenticating a `BlobClient` using the `DeviceCodeCredential`.
+
+```C# Snippet:Identity_ClientSideUserAuthentication_SimpleDeviceCode
+var credential = new DeviceCodeCredential();
+
+var client = new BlobClient(new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"), credential);
+```
+Similarly to the `InteractiveBrowserCredential` the `DeviceCodeCredential` will also initiate the user interaction automatically as needed. To instantiate the `DeviceCodeCredential` the application must provide a callback which is called to display the device code along with details on how to authenticate to the user. In the above sample a lambda is provided which prints the full device code message to the console.
+
+
+## Controlling user interaction
+
+In many cases applications require tight control over user interaction. In these applications automatically blocking on required user interaction is often undesired or impractical. For this reason, credentials in the `Azure.Identity` library which interact with the user offer mechanisms to fully control user interaction.
+
+```C# Snippet:Identity_ClientSideUserAuthentication_DisableAutomaticAuthentication
+var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialOptions { DisableAutomaticAuthentication = true });
+
+await credential.AuthenticateAsync();
+
+var client = new SecretClient(new Uri("https://myvault.azure.vaults.net/"), credential);
+```
+In this sample the application is again using the `InteractiveBrowserCredential` to authenticate a `SecretClient`, but with two major differences from our first example. First, in this example the application is explicitly forcing any user interaction to happen before the credential is given to the client by calling `AuthenticateAsync`. 
+
+The second difference is here the application is preventing the credential from automatically initiating user interaction. Even though the application authenticates the user before the credential is used, further interaction might still be needed, for instance in the case that the user's refresh token expires, or a specific method require additional consent or authentication. 
+
+By setting the option `DisableAutomaticAuthentication` to `true` the credential will fail to automatically authenticate calls where user interaction is necessary. Instead, the credential will throw an `AuthenticationRequiredException`. The following example demonstrates an application handling such an exception to prompt the user to authenticate only after some application logic has completed.
+
+```C# Snippet:Identity_ClientSideUserAuthentication_DisableAutomaticAuthentication_ExHandling
+try
+{
+    client.GetSecret("secret");
+}
+catch (AuthenticationRequiredException e)
+{
+    await EnsureAnimationCompleteAsync();
+
+    await credential.AuthenticateAsync(e.TokenRequestContext);
+
+    client.GetSecret("secret");
+}
+```
+
+## Persisting user authentication data
+
+Quite often applications desire the ability to be run multiple times without having to reauthenticate the user on each execution. This requires that data from the original authentication be persisted outside of the application memory, so that it can authenticate silently on subsequent executions. Specifically two pieces of data need to be persisted, the `TokenCache` and the `AuthenticationRecord`. 
+
+### Persisting the TokenCache
+
+The `TokenCache` contains all the data needed to silently authenticate, one or many accounts. It contains sensitive data such as refresh tokens, and access tokens and must be protected to prevent compromising the accounts it houses tokens for. The `Azure.Identity` library provides the `PersistentTokenCache` class which by default will protect and persist the cache using available platform data protection. 
+
+To use the `PersistentTokenCache` to persist the cache of any credential simply set the `TokenCache` option.
+
+```C# Snippet:Identity_ClientSideUserAuthentication_Persist_TokenCache
+var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialOptions { TokenCache = new PersistentTokenCache() });
+```
+
+### Persisting the AuthenticationRecord
+
+The `AuthenticationRecord` which is returned from the `Authenticate` and `AuthenticateAsync`, contains data identifying an authenticated account. It is needed to identify the appropriate entry in the `TokenCache` to silently authenticate on subsequent executions. There is no sensitive data in the `AuthenticationRecord` so it can be persisted in a non-protected state.
+
+Here is an example of an application storing the `AuthenticationRecord` to the local file system after authenticating the user.
+
+```C# Snippet:Identity_ClientSideUserAuthentication_Persist_AuthRecord
+AuthenticationRecord authRecord = await credential.AuthenticateAsync();
+
+using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write);
+
+await authRecord.SerializeAsync(authRecordStream);
+
+await authRecordStream.FlushAsync();
+```
+### Silent authentication with AuthenticationRecord and PersistentTokenCache
+
+Once an application has persisted both the `TokenCache` and the `AuthenticationRecord` this data can be used to silently authenticate. This example demonstrates an application using the `PersistentTokenCache` and retrieving an `AuthenticationRecord` from the local file system to create an `InteractiveBrowserCredential` capable of silent authentication.
+
+```C# Snippet:Identity_ClientSideUserAuthentication_Persist_SilentAuth
+using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read);
+
+AuthenticationRecord authRecord = await AuthenticationRecord.DeserializeAsync(authRecordStream);
+
+var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialOptions { TokenCache = new PersistentTokenCache(), AuthenticationRecord = authRecord });
+```
+
+The credential created in this example will silently authenticate given that a valid token for corresponding to the `AuthenticationRecord` still exists in the `TokenCache`. There are some cases where interaction will still be required such as on token expiry, or when additional authentication is required for a particular resource.

sdk/identity/Azure.Identity/samples/ClientSideUserAuthentication.md

@@ -0,0 +1,81 @@
+# Persisting the credential TokenCache
+Many credential implementations in the Azure.Identity library have an underlying `TokenCache` which caches sensitive authentication data such as account information, access tokens, and refresh tokens. By default this `TokenCache` instance is an in memory cache which is specific to the credential instance. However, there are scenarios where an application needs to share the token cache across credentials, and persist it across executions. To accomplish this the Azure.Identity provides the `TokenCache` and `PeristantTokenCache` classes.
+
+>IMPORTANT! The `TokenCache` contains sensitive data and **MUST** be protected to prevent compromising accounts. All application decisions regarding the storage of the `TokenCache` must consider that a breach of its content will fully compromise all the accounts it contains.
+
+## Using the default PersistentTokenCache
+
+The simplest way to persist the `TokenCache` of a credential is to to use the default `PersistentTokenCache`. This will persist and read the `TokenCache` from a shared persisted token cache protected to the current account.
+
+```C# Snippet:Identity_TokenCache_PersistentDefault
+var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialOptions { TokenCache = new PersistentTokenCache() });
+```
+
+## Using a named PersistentTokenCache
+
+Some applications may prefer to isolate the `PersistentTokenCache` they user rather than using the shared instance. To accomplish this they can specify a `PersistentTokenCacheOptions` when creating the `PersistentTokenCache` and provide a `Name` for the persisted cache instance.
+
+```C# Snippet:Identity_TokenCache_PersistentNamed
+var tokenCache = new PersistentTokenCache(new PersistentTokenCacheOptions { Name = "my_application_name" });
+
+var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialOptions { TokenCache = tokenCache });
+```
+
+## Allowing unencrypted storage
+By default the `PersistentTokenCache` will protect any data which is persisted using the user data protection APIs available on the current platform. However, there are cases where no data protection is available, and applications may choose to still persist the token cache in an unencrypted state. This is accomplished with the `AllowUnencryptedStorage` option.
+
+```C# Snippet:Identity_TokenCache_PersistentUnencrypted
+var tokenCache = new PersistentTokenCache(new PersistentTokenCacheOptions { AllowUnencryptedStorage = true });
+
+var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialOptions { TokenCache =  tokenCache});
+```
+By setting `AllowUnencryptedStorage` to `true`, the `PersistentTokenCache` will encrypt the contents of the `TokenCache` before persisting it if data protection is available on the current platform, otherwise it will write and read the `TokenCache` data to an unencrypted local file ACL'd to the current account. If `AllowUnencryptedStorage` is `false` (the default) a `CredentialUnavailableException` will be raised in the case no data protection is available.
+
+## Implementing custom TokenCache persistence 
+Some applications may require complete control of how the `TokenCache` is persisted. To enable this the `TokenCache` provides the methods `Serialize`, `SerializeAsync`, `Deserialize` and `DeserializeAsync` methods so applications can write the `TokenCache` to any stream. The following samples illustrate how to use these serialization methods to write and read the cache from a stream. 
+
+> IMPORTANT! This sample assumes the location of the file it is using for storage is secure. The `Serialize` and `SerializeAsync` methods will write the unencrypted content of the `TokenCache` to the provide stream. It is the responsibility the implementer to properly protect the `TokenCache` data.
+
+The `Serialize` or `SerializeAsync` methods can be used to write out content of a `TokenCache` to any writeable stream.
+
+```C# Snippet:Identity_TokenCache_CustomPersistence_Write
+using var cacheStream = new FileStream(TokenCachePath, FileMode.Create, FileAccess.Write);
+
+await tokenCache.SerializeAsync(cacheStream);
+```
+
+The `Deserialize` or `DeserializeAsync` methods can be used to read the content of a `TokenCache` from any readable stream.
+
+```C# Snippet:Identity_TokenCache_CustomPersistence_Read
+using var cacheStream = new FileStream(TokenCachePath, FileMode.OpenOrCreate, FileAccess.Read);
+
+var tokenCache = await TokenCache.DeserializeAsync(cacheStream);
+```
+
+Applications can combine these methods along with the `Updated` event to automatically persist and read the token from a storage solution of their choice.
+```C# Snippet:Identity_TokenCache_CustomPersistence_Usage
+public static async Task<TokenCache> ReadTokenCacheAsync()
+{
+    using var cacheStream = new FileStream(TokenCachePath, FileMode.OpenOrCreate, FileAccess.Read);
+
+    var tokenCache = await TokenCache.DeserializeAsync(cacheStream);
+
+    tokenCache.Updated += WriteCacheOnUpdateAsync;
+
+    return tokenCache;
+}
+
+public static async Task WriteCacheOnUpdateAsync(TokenCacheUpdatedArgs args)
+{
+    using var cacheStream = new FileStream(TokenCachePath, FileMode.Create, FileAccess.Write);
+
+    await args.Cache.SerializeAsync(cacheStream);
+}
+
+public static async Task Main()
+{
+    var tokenCache = await ReadTokenCacheAsync();
+
+    var credential = new InteractiveBrowserCredential(new InteractiveBrowserCredentialOptions { TokenCache = tokenCache });
+}
+```

sdk/identity/Azure.Identity/samples/TokenCache.md

@@ -15,7 +15,7 @@ namespace Azure.Identity
     /// <summary>
     /// Account information relating to an authentication request.
     /// </summary>
-    internal class AuthenticationRecord
+    public class AuthenticationRecord
     {
         private const string UsernamePropertyName = "username";
         private const string AuthorityPropertyName = "authority";

sdk/identity/Azure.Identity/src/AuthenticationRecord.cs

@@ -9,7 +9,7 @@ namespace Azure.Identity
     /// <summary>
     /// An exception indicating that interactive authentication is required.
     /// </summary>
-    internal class AuthenticationRequiredException : CredentialUnavailableException
+    public class AuthenticationRequiredException : CredentialUnavailableException
     {
         /// <summary>
         /// Creates a new <see cref="AuthenticationRequiredException"/> with the specified message and context.

sdk/identity/Azure.Identity/src/AuthenticationRequiredException.cs

@@ -2,7 +2,7 @@
   <PropertyGroup>
     <Description>This is the implementation of the Azure SDK Client Library for Azure Identity</Description>
     <AssemblyTitle>Microsoft Azure.Identity Component</AssemblyTitle>
-    <Version>1.4.0-beta.1</Version>
+    <Version>1.4.0-beta.2</Version>
     <ApiCompatVersion>1.3.0</ApiCompatVersion>
     <PackageTags>Microsoft Azure Identity;$(PackageCommonTags)</PackageTags>
     <TargetFrameworks>$(RequiredTargetFrameworks)</TargetFrameworks>

sdk/identity/Azure.Identity/src/Azure.Identity.csproj

@@ -8,24 +8,14 @@ namespace Azure.Identity
     /// </summary>
     public class ClientCertificateCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
-
-        /// <summary>
-        /// If set to true the credential will store tokens in a cache persisted to the machine, protected to the current user, which can be shared by other credentials and processes.
-        /// </summary>
-        internal bool EnablePersistentCache { get; set; }
-
         /// <summary>
-        /// If set to true the credential will fall back to storing tokens in an unencrypted file if no OS level user encryption is available.
+        /// Specifies the <see cref="TokenCache"/> to be used by the credential.
         /// </summary>
-        internal bool AllowUnencryptedCache { get; set; }
+        public TokenCache TokenCache { get; set; }
 
         /// <summary>
         /// Will include x5c header in client claims when acquiring a token to enable subject name / issuer based authentication for the <see cref="ClientCertificateCredential"/>.
         /// </summary>
         public bool SendCertificateChain { get; set; }
-
-        bool ITokenCacheOptions.EnablePersistentCache => EnablePersistentCache;
-
-        bool ITokenCacheOptions.AllowUnencryptedCache => AllowUnencryptedCache;
     }
 }

sdk/identity/Azure.Identity/src/ClientCertificateCredentialOptions.cs

@@ -60,7 +60,7 @@ public ClientSecretCredential(string tenantId, string clientId, string clientSec
         /// <param name="clientId">The client (application) ID of the service principal</param>
         /// <param name="clientSecret">A client secret that was generated for the App Registration used to authenticate the client.</param>
         /// <param name="options">Options that allow to configure the management of the requests sent to the Azure Active Directory service.</param>
-        internal ClientSecretCredential(string tenantId, string clientId, string clientSecret, ClientSecretCredentialOptions options)
+        public ClientSecretCredential(string tenantId, string clientId, string clientSecret, ClientSecretCredentialOptions options)
             : this(tenantId, clientId, clientSecret, options, null, null)
         {
         }

sdk/identity/Azure.Identity/src/ClientSecretCredential.cs

@@ -6,17 +6,12 @@ namespace Azure.Identity
     /// <summary>
     /// Options used to configure the <see cref="ClientSecretCredential"/>.
     /// </summary>
-    internal class ClientSecretCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
+    public class ClientSecretCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
-
         /// <summary>
-        /// If set to true the credential will store tokens in a persistent cache shared by other credentials.
+        /// Specifies the <see cref="TokenCache"/> to be used by the credential.
         /// </summary>
-        public bool EnablePersistentCache { get; set; }
+        public TokenCache TokenCache { get; set; }
 
-        /// <summary>
-        /// If set to true the credential will fall back to storing tokens in an unencrypted file if no OS level user encryption is available.
-        /// </summary>
-        public bool AllowUnencryptedCache { get; set; }
     }
 }