TokenCache becomes internal and only exposes TokenCachePersistenceOptions (Azure#19240)

* TokenCache becomes internal and only exposes TokenCachePersistenceOptions

Co-authored-by: Scott Schaab <sschaab@microsoft.com>

Author: christothes

sdk/identity/Azure.Identity/CHANGELOG.md

@@ -32,7 +32,7 @@
 ### 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` and `TokenCache` 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

@@ -69,7 +69,7 @@ public partial class ClientCertificateCredentialOptions : Azure.Identity.TokenCr
     {
         public ClientCertificateCredentialOptions() { }
         public bool SendCertificateChain { get { throw null; } set { } }
-        public Azure.Identity.TokenCache TokenCache { get { throw null; } set { } }
+        public Azure.Identity.TokenCachePersistenceOptions TokenCachePersistenceOptions { get { throw null; } set { } }
     }
     public partial class ClientSecretCredential : Azure.Core.TokenCredential
     {
@@ -83,7 +83,7 @@ public ClientSecretCredential(string tenantId, string clientId, string clientSec
     public partial class ClientSecretCredentialOptions : Azure.Identity.TokenCredentialOptions
     {
         public ClientSecretCredentialOptions() { }
-        public Azure.Identity.TokenCache TokenCache { get { throw null; } set { } }
+        public Azure.Identity.TokenCachePersistenceOptions TokenCachePersistenceOptions { get { throw null; } set { } }
     }
     public partial class CredentialUnavailableException : Azure.Identity.AuthenticationFailedException
     {
@@ -138,7 +138,7 @@ public DeviceCodeCredentialOptions() { }
         public System.Func<Azure.Identity.DeviceCodeInfo, System.Threading.CancellationToken, System.Threading.Tasks.Task> DeviceCodeCallback { get { throw null; } set { } }
         public bool DisableAutomaticAuthentication { get { throw null; } set { } }
         public string TenantId { get { throw null; } set { } }
-        public Azure.Identity.TokenCache TokenCache { get { throw null; } set { } }
+        public Azure.Identity.TokenCachePersistenceOptions TokenCachePersistenceOptions { get { throw null; } set { } }
     }
     [System.Runtime.InteropServices.StructLayoutAttribute(System.Runtime.InteropServices.LayoutKind.Sequential)]
     public partial struct DeviceCodeInfo
@@ -188,7 +188,7 @@ public InteractiveBrowserCredentialOptions() { }
         public bool DisableAutomaticAuthentication { get { throw null; } set { } }
         public System.Uri RedirectUri { get { throw null; } set { } }
         public string TenantId { get { throw null; } set { } }
-        public Azure.Identity.TokenCache TokenCache { get { throw null; } set { } }
+        public Azure.Identity.TokenCachePersistenceOptions TokenCachePersistenceOptions { get { throw null; } set { } }
     }
     public partial class ManagedIdentityCredential : Azure.Core.TokenCredential
     {
@@ -197,16 +197,6 @@ public ManagedIdentityCredential(string clientId = null, Azure.Identity.TokenCre
         public override Azure.Core.AccessToken GetToken(Azure.Core.TokenRequestContext requestContext, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
         public override System.Threading.Tasks.ValueTask<Azure.Core.AccessToken> GetTokenAsync(Azure.Core.TokenRequestContext requestContext, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
     }
-    public partial class PersistentTokenCache : Azure.Identity.TokenCache
-    {
-        public PersistentTokenCache(Azure.Identity.PersistentTokenCacheOptions options = null) { }
-    }
-    public partial class PersistentTokenCacheOptions
-    {
-        public PersistentTokenCacheOptions() { }
-        public bool AllowUnencryptedStorage { get { throw null; } set { } }
-        public string Name { get { throw null; } set { } }
-    }
     public partial class SharedTokenCacheCredential : Azure.Core.TokenCredential
     {
         public SharedTokenCacheCredential() { }
@@ -219,36 +209,36 @@ public SharedTokenCacheCredential(string username, Azure.Identity.TokenCredentia
     public partial class SharedTokenCacheCredentialOptions : Azure.Identity.TokenCredentialOptions
     {
         public SharedTokenCacheCredentialOptions() { }
-        public SharedTokenCacheCredentialOptions(Azure.Identity.TokenCache tokenCache) { }
+        public SharedTokenCacheCredentialOptions(Azure.Identity.TokenCachePersistenceOptions tokenCacheOptions) { }
         public Azure.Identity.AuthenticationRecord AuthenticationRecord { get { throw null; } set { } }
         public string ClientId { get { throw null; } set { } }
         public bool EnableGuestTenantAuthentication { get { throw null; } set { } }
         public string TenantId { get { throw null; } set { } }
-        public Azure.Identity.TokenCache TokenCache { get { throw null; } }
+        public Azure.Identity.TokenCachePersistenceOptions TokenCachePersistenceOptions { get { throw null; } }
         public string Username { get { throw null; } set { } }
     }
-    public partial class TokenCache
+    public partial class TokenCachePersistenceOptions
     {
-        public TokenCache() { }
-        public event System.Func<Azure.Identity.TokenCacheUpdatedArgs, System.Threading.Tasks.Task> Updated { add { } remove { } }
-    }
-    public static partial class TokenCacheSerializer
-    {
-        public static Azure.Identity.TokenCache Deserialize(System.IO.Stream stream, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public static System.Threading.Tasks.Task<Azure.Identity.TokenCache> DeserializeAsync(System.IO.Stream stream, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
-        public static void Serialize(Azure.Identity.TokenCache tokenCache, System.IO.Stream stream, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { }
-        public static System.Threading.Tasks.Task SerializeAsync(Azure.Identity.TokenCache tokenCache, System.IO.Stream stream, System.Threading.CancellationToken cancellationToken = default(System.Threading.CancellationToken)) { throw null; }
+        public TokenCachePersistenceOptions() { }
+        public string Name { get { throw null; } set { } }
+        public bool UnsafeAllowUnencryptedStorage { get { throw null; } set { } }
     }
     public partial class TokenCacheUpdatedArgs
     {
         internal TokenCacheUpdatedArgs() { }
-        public Azure.Identity.TokenCache Cache { get { throw null; } }
+        public System.ReadOnlyMemory<byte> UnsafeCacheData { get { throw null; } }
     }
     public partial class TokenCredentialOptions : Azure.Core.ClientOptions
     {
         public TokenCredentialOptions() { }
         public System.Uri AuthorityHost { get { throw null; } set { } }
     }
+    public abstract partial class UnsafeTokenCacheOptions : Azure.Identity.TokenCachePersistenceOptions
+    {
+        protected UnsafeTokenCacheOptions() { }
+        protected internal abstract System.Threading.Tasks.Task<System.ReadOnlyMemory<byte>> RefreshCacheAsync();
+        protected internal abstract System.Threading.Tasks.Task TokenCacheUpdatedAsync(Azure.Identity.TokenCacheUpdatedArgs tokenCacheUpdatedArgs);
+    }
     public partial class UsernamePasswordCredential : Azure.Core.TokenCredential
     {
         protected UsernamePasswordCredential() { }
@@ -265,7 +255,7 @@ public UsernamePasswordCredential(string username, string password, string tenan
     public partial class UsernamePasswordCredentialOptions : Azure.Identity.TokenCredentialOptions
     {
         public UsernamePasswordCredentialOptions() { }
-        public Azure.Identity.TokenCache TokenCache { get { throw null; } set { } }
+        public Azure.Identity.TokenCachePersistenceOptions TokenCachePersistenceOptions { get { throw null; } set { } }
     }
     public partial class VisualStudioCodeCredential : Azure.Core.TokenCredential
     {

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

@@ -40,7 +40,8 @@ In many cases applications require tight control over user interaction. In these
 
 ```C# Snippet:Identity_ClientSideUserAuthentication_DisableAutomaticAuthentication
 var credential = new InteractiveBrowserCredential(
-    new InteractiveBrowserCredentialOptions {
+    new InteractiveBrowserCredentialOptions
+    {
         DisableAutomaticAuthentication = true
     });
 
@@ -72,24 +73,31 @@ catch (AuthenticationRequiredException e)
 
 ## 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`.
+Quite often applications desire the ability to be run multiple times without having to re-authenticate the user on each execution.
+This requires that data from credentials be persisted outside of the application memory so that it can authenticate silently on subsequent executions.
+Applications can persist this data using `TokenPersistenceOptions` when constructing the credential, and persisting the `AuthenticationRecord` returned from `Authenticate`.
 
-### Persisting the TokenCache
+### Persisting the token cache
 
-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.
+The credential handles persisting all the data needed to silently authenticate one or many accounts.
+It manages sensitive data such as refresh tokens and access tokens which must be protected to prevent compromising the accounts related to them.
+By default, the `Azure.Identity` library will protect and cache sensitive token data using available platform data protection.
 
-To use the `PersistentTokenCache` to persist the cache of any credential simply set the `TokenCache` option.
+To configure a credential, such as the `InteractiveBrowserCredential`, to persist token data, simply set the `TokenCachePersistenceOptions` option.
 
 ```C# Snippet:Identity_ClientSideUserAuthentication_Persist_TokenCache
 var credential = new InteractiveBrowserCredential(
-    new InteractiveBrowserCredentialOptions {
-        TokenCache = new PersistentTokenCache()
+    new InteractiveBrowserCredentialOptions
+    {
+        TokenCachePersistenceOptions = new TokenCachePersistenceOptions()
     });
 ```
 
 ### 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.
+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 persisted token cache 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.
 
@@ -106,9 +114,10 @@ using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create,
 }
 ```
 
-### Silent authentication with AuthenticationRecord and PersistentTokenCache
+### Silent authentication with AuthenticationRecord and TokenCachePersistenceOptions
 
-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.
+Once an application has configured a credential to persist token data and an `AuthenticationRecord`, it is possible to silently authenticate.
+This example demonstrates an application setting the `TokenCachePersistenceOptions` and retrieving an `AuthenticationRecord` from the local file system to create an `InteractiveBrowserCredential` capable of silent authentication.
 
 ```C# Snippet:Identity_ClientSideUserAuthentication_Persist_SilentAuth
 AuthenticationRecord authRecord;
@@ -119,10 +128,12 @@ using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, Fi
 }
 
 var credential = new InteractiveBrowserCredential(
-    new InteractiveBrowserCredentialOptions {
-        TokenCache = new PersistentTokenCache(),
+    new InteractiveBrowserCredentialOptions
+    {
+        TokenCachePersistenceOptions = new TokenCachePersistenceOptions(),
         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.
+The credential created in this example will silently authenticate given that a valid token for corresponding to the `AuthenticationRecord` still exists in the persisted token data.
+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.