Chriss/token cache peristence options doc improvements (Azure#23908)

* Add example to TokenCachePersistenceOptions

Author: christothes

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

@@ -40,10 +40,7 @@ In many cases applications require tight control over user interaction. In these
 
 ```C# Snippet:Identity_ClientSideUserAuthentication_DisableAutomaticAuthentication
 var credential = new InteractiveBrowserCredential(
-    new InteractiveBrowserCredentialOptions
-    {
-        DisableAutomaticAuthentication = true
-    });
+    new InteractiveBrowserCredentialOptions { DisableAutomaticAuthentication = true });
 
 await credential.AuthenticateAsync();
 
@@ -87,10 +84,7 @@ To configure a credential, such as the `InteractiveBrowserCredential`, to persis
 
 ```C# Snippet:Identity_ClientSideUserAuthentication_Persist_TokenCache
 var credential = new InteractiveBrowserCredential(
-    new InteractiveBrowserCredentialOptions
-    {
-        TokenCachePersistenceOptions = new TokenCachePersistenceOptions()
-    });
+    new InteractiveBrowserCredentialOptions { TokenCachePersistenceOptions = new TokenCachePersistenceOptions() });
 ```
 
 ### Persisting the AuthenticationRecord
@@ -130,8 +124,7 @@ using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, Fi
 var credential = new InteractiveBrowserCredential(
     new InteractiveBrowserCredentialOptions
     {
-        TokenCachePersistenceOptions = new TokenCachePersistenceOptions(),
-        AuthenticationRecord = authRecord
+        TokenCachePersistenceOptions = new TokenCachePersistenceOptions(), AuthenticationRecord = authRecord
     });
 ```
 

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

@@ -14,6 +14,7 @@ namespace Azure.Identity
     /// <summary>
     /// Account information relating to an authentication request.
     /// </summary>
+    /// <seealso cref="TokenCachePersistenceOptions"/>.
     public class AuthenticationRecord
     {
         internal const string CurrentVersion = "1.0";

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

@@ -9,7 +9,7 @@ namespace Azure.Identity
     public class ClientCertificateCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

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

@@ -9,7 +9,7 @@ namespace Azure.Identity
     public class ClientSecretCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

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

@@ -35,7 +35,7 @@ public string TenantId
         public string ClientId { get; set; } = Constants.DeveloperSignOnClientId;
 
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

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

@@ -97,7 +97,7 @@ public virtual AuthenticationRecord Authenticate(CancellationToken cancellationT
         }
 
         /// <summary>
-        /// Interactively authenticates a user via the default browser.
+        /// Interactively authenticates a user via the default browser. The resulting <see cref="AuthenticationRecord"/> will automatically be used in subsequent calls to <see cref="GetTokenAsync"/>.
         /// </summary>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
         /// <returns>The result of the authentication request, containing the acquired <see cref="AccessToken"/>, and the <see cref="AuthenticationRecord"/> which can be used to silently authenticate the account.</returns>
@@ -110,7 +110,7 @@ public virtual async Task<AuthenticationRecord> AuthenticateAsync(CancellationTo
         }
 
         /// <summary>
-        /// Interactively authenticates a user via the default browser.
+        /// Interactively authenticates a user via the default browser. The resulting <see cref="AuthenticationRecord"/> will automatically be used in subsequent calls to <see cref="GetToken"/>.
         /// </summary>
         /// <param name="cancellationToken">A <see cref="CancellationToken"/> controlling the request lifetime.</param>
         /// <param name="requestContext">The details of the authentication request.</param>

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

@@ -34,7 +34,7 @@ public string TenantId
         public string ClientId { get; set; } = Constants.DeveloperSignOnClientId;
 
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
 

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

@@ -1,11 +1,59 @@
-// Copyright (c) Microsoft Corporation. All rights reserved.
+// Copyright (c) Microsoft Corporation. All rights reserved.
 // Licensed under the MIT License.
 
 namespace Azure.Identity
 {
     /// <summary>
     /// Options controlling the storage of the token cache.
     /// </summary>
+    /// <example>
+    /// <para>
+    /// This is an example showing how TokenCachePersistenceOptions and an AuthenticationRecord can be used together to enable silent authentication
+    /// across executions of a client application.
+    /// </para>
+    /// <code snippet="Snippet:AuthenticationRecord_TokenCachePersistenceOptions" language="csharp">
+    /// const string TOKEN_CACHE_NAME = &quot;MyTokenCache&quot;;
+    /// InteractiveBrowserCredential credential;
+    /// AuthenticationRecord authRecord;
+    ///
+    /// // Check if an AuthenticationRecord exists on disk.
+    /// // If it does not exist, get one and serialize it to disk.
+    /// // If it does exist, load it from disk and deserialize it.
+    /// if (!File.Exists(AUTH_RECORD_PATH))
+    /// {
+    ///     // Construct a credential with TokenCachePersistenceOptions specified to ensure that the token cache is persisted to disk.
+    ///     // We can also optionally specify a name for the cache to avoid having it cleared by other applications.
+    ///     credential = new InteractiveBrowserCredential(
+    ///         new InteractiveBrowserCredentialOptions { TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME } });
+    ///
+    ///     // Call AuthenticateAsync to fetch a new AuthenticationRecord.
+    ///     authRecord = await credential.AuthenticateAsync();
+    ///
+    ///     // Serialize the AuthenticationRecord to disk so that it can be re-used across executions of this initialization code.
+    ///     using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write);
+    ///     await authRecord.SerializeAsync(authRecordStream);
+    /// }
+    /// else
+    /// {
+    ///     // Load the previously serialized AuthenticationRecord from disk and deserialize it.
+    ///     using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read);
+    ///     authRecord = await AuthenticationRecord.DeserializeAsync(authRecordStream);
+    ///
+    ///     // Construct a new client with our TokenCachePersistenceOptions with the addition of the AuthenticationRecord property.
+    ///     // This tells the credential to use the same token cache in addition to which account to try and fetch from cache when GetToken is called.
+    ///     credential = new InteractiveBrowserCredential(
+    ///         new InteractiveBrowserCredentialOptions
+    ///         {
+    ///             TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME },
+    ///             AuthenticationRecord = authRecord
+    ///         });
+    /// }
+    ///
+    /// // Construct our client with the credential which is connected to the token cache
+    /// // with the capability of silent authentication for the account specified in the AuthenticationRecord.
+    /// var client = new SecretClient(new Uri(&quot;https://myvault.vault.azure.net/&quot;), credential);
+    /// </code>
+    /// </example>
     public class TokenCachePersistenceOptions
     {
         /// <summary>

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

@@ -9,7 +9,7 @@ namespace Azure.Identity
     public class UsernamePasswordCredentialOptions : TokenCredentialOptions, ITokenCacheOptions
     {
         /// <summary>
-        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted.
+        /// Specifies the <see cref="TokenCachePersistenceOptions"/> to be used by the credential. If not options are specified, the token cache will not be persisted to disk.
         /// </summary>
         public TokenCachePersistenceOptions TokenCachePersistenceOptions { get; set; }
     }

sdk/identity/Azure.Identity/tests/samples/UserAuthenticationSnippets.cs

@@ -15,46 +15,52 @@ namespace Azure.Identity.Samples
     public class UserAuthenticationSnippets
     {
         #region Snippet:Identity_ClientSideUserAuthentication_Persist_TokenCache_AuthRecordPath
+
         private const string AUTH_RECORD_PATH = "./tokencache.bin";
+
         #endregion
 
         public void Identity_ClientSideUserAuthentication_SimpleInteractiveBrowser()
         {
             #region Snippet:Identity_ClientSideUserAuthentication_SimpleInteractiveBrowser
+
             var client = new SecretClient(
                 new Uri("https://myvault.vault.azure.net/"),
                 new InteractiveBrowserCredential()
             );
+
             #endregion
         }
 
         public void Identity_ClientSideUserAuthentication_SimpleDeviceCode()
         {
             #region Snippet:Identity_ClientSideUserAuthentication_SimpleDeviceCode
+
             var credential = new DeviceCodeCredential();
 
             var client = new BlobClient(
                 new Uri("https://myaccount.blob.core.windows.net/mycontainer/myblob"),
                 credential
             );
+
             #endregion
         }
 
         public async Task Identity_ClientSideUserAuthentication_DisableAutomaticAuthentication()
         {
             #region Snippet:Identity_ClientSideUserAuthentication_DisableAutomaticAuthentication
+
             var credential = new InteractiveBrowserCredential(
-                new InteractiveBrowserCredentialOptions
-                {
-                    DisableAutomaticAuthentication = true
-                });
+                new InteractiveBrowserCredentialOptions { DisableAutomaticAuthentication = true });
 
             await credential.AuthenticateAsync();
 
             var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);
+
             #endregion
 
             #region Snippet:Identity_ClientSideUserAuthentication_DisableAutomaticAuthentication_ExHandling
+
             try
             {
                 client.GetSecret("secret");
@@ -67,6 +73,7 @@ public async Task Identity_ClientSideUserAuthentication_DisableAutomaticAuthenti
 
                 client.GetSecret("secret");
             }
+
             #endregion
         }
 
@@ -77,14 +84,14 @@ public static async Task<TokenCredential> GetUserCredentialAsync()
             if (!File.Exists(AUTH_RECORD_PATH))
             {
                 #region Snippet:Identity_ClientSideUserAuthentication_Persist_TokenCache
+
                 var credential = new InteractiveBrowserCredential(
-                    new InteractiveBrowserCredentialOptions
-                    {
-                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions()
-                    });
+                    new InteractiveBrowserCredentialOptions { TokenCachePersistenceOptions = new TokenCachePersistenceOptions() });
+
                 #endregion
 
                 #region Snippet:Identity_ClientSideUserAuthentication_Persist_AuthRecord
+
                 AuthenticationRecord authRecord = await credential.AuthenticateAsync();
 
                 using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write))
@@ -99,6 +106,7 @@ public static async Task<TokenCredential> GetUserCredentialAsync()
             else
             {
                 #region Snippet:Identity_ClientSideUserAuthentication_Persist_SilentAuth
+
                 AuthenticationRecord authRecord;
 
                 using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read))
@@ -109,9 +117,9 @@ public static async Task<TokenCredential> GetUserCredentialAsync()
                 var credential = new InteractiveBrowserCredential(
                     new InteractiveBrowserCredentialOptions
                     {
-                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions(),
-                        AuthenticationRecord = authRecord
+                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions(), AuthenticationRecord = authRecord
                     });
+
                 #endregion
 
                 return credential;
@@ -120,41 +128,50 @@ public static async Task<TokenCredential> GetUserCredentialAsync()
 
         public static async Task Main()
         {
+            #region Snippet:AuthenticationRecord_TokenCachePersistenceOptions
+
+            const string TOKEN_CACHE_NAME = "MyTokenCache";
             InteractiveBrowserCredential credential;
+            AuthenticationRecord authRecord;
 
+            // Check if an AuthenticationRecord exists on disk.
+            // If it does not exist, get one and serialize it to disk.
+            // If it does exist, load it from disk and deserialize it.
             if (!File.Exists(AUTH_RECORD_PATH))
             {
+                // Construct a credential with TokenCachePersistenceOptions specified to ensure that the token cache is persisted to disk.
+                // We can also optionally specify a name for the cache to avoid having it cleared by other applications.
                 credential = new InteractiveBrowserCredential(
-                    new InteractiveBrowserCredentialOptions
-                    {
-                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions()
-                    });
+                    new InteractiveBrowserCredentialOptions { TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME } });
 
-                AuthenticationRecord authRecord = await credential.AuthenticateAsync();
+                // Call AuthenticateAsync to fetch a new AuthenticationRecord.
+                authRecord = await credential.AuthenticateAsync();
 
-                using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write))
-                {
-                    await authRecord.SerializeAsync(authRecordStream);
-                }
+                // Serialize the AuthenticationRecord to disk so that it can be re-used across executions of this initialization code.
+                using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Create, FileAccess.Write);
+                await authRecord.SerializeAsync(authRecordStream);
             }
             else
             {
-                AuthenticationRecord authRecord;
-
-                using (var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read))
-                {
-                    authRecord = await AuthenticationRecord.DeserializeAsync(authRecordStream);
-                }
+                // Load the previously serialized AuthenticationRecord from disk and deserialize it.
+                using var authRecordStream = new FileStream(AUTH_RECORD_PATH, FileMode.Open, FileAccess.Read);
+                authRecord = await AuthenticationRecord.DeserializeAsync(authRecordStream);
 
+                // Construct a new client with our TokenCachePersistenceOptions with the addition of the AuthenticationRecord property.
+                // This tells the credential to use the same token cache in addition to which account to try and fetch from cache when GetToken is called.
                 credential = new InteractiveBrowserCredential(
                     new InteractiveBrowserCredentialOptions
                     {
-                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions(),
+                        TokenCachePersistenceOptions = new TokenCachePersistenceOptions { Name = TOKEN_CACHE_NAME },
                         AuthenticationRecord = authRecord
                     });
             }
 
+            // Construct our client with the credential which is connected to the token cache
+            // with the capability of silent authentication for the account specified in the AuthenticationRecord.
             var client = new SecretClient(new Uri("https://myvault.vault.azure.net/"), credential);
+
+            #endregion
         }
     }
 }