Update WithPoP comments - not experimental on PCA with broker (#4048)

Update WithPoP comments.

src/client/Microsoft.Identity.Client/ApiConfig/AbstractConfidentialClientAcquireTokenParameterBuilder.cs

@@ -62,15 +62,15 @@ protected override void Validate()
         internal IConfidentialClientApplicationExecutor ConfidentialClientApplicationExecutor { get; }
 
         /// <summary>
-        ///  Modifies the token acquisition request so that the acquired token is a Proof of Possession token (PoP), rather than a Bearer token. 
+        ///  Modifies the token acquisition request so that the acquired token is a Proof-of-Possession token (PoP), rather than a Bearer token. 
         ///  PoP tokens are similar to Bearer tokens, but are bound to the HTTP request and to a cryptographic key, which MSAL can manage on Windows.
         ///  See https://aka.ms/msal-net-pop
         /// </summary>
-        /// <param name="popAuthenticationConfiguration">Configuration properties used to construct a proof of possession request.</param>
+        /// <param name="popAuthenticationConfiguration">Configuration properties used to construct a Proof-of-Possession request.</param>
         /// <returns>The builder.</returns>
         /// <remarks>
         /// <list type="bullet">
-        /// <item><description>An Authentication header is automatically added to the request</description></item>
+        /// <item><description>An Authentication header is automatically added to the request.</description></item>
         /// <item><description>The PoP token is bound to the HTTP request, more specifically to the HTTP method (GET, POST, etc.) and to the Uri (path and query, but not query parameters).</description></item>
         /// <item><description>MSAL creates, reads and stores a key in memory that will be cycled every 8 hours.</description></item>
         /// <item><description>This is an experimental API. The method signature may change in the future without involving a major version upgrade.</description></item>

src/client/Microsoft.Identity.Client/ApiConfig/AcquireTokenByUsernamePasswordParameterBuilder.cs

@@ -54,22 +54,22 @@ public AcquireTokenByUsernamePasswordParameterBuilder WithFederationMetadata(str
         }
 
         /// <summary>
-        ///  Modifies the token acquisition request so that the acquired token is a Proof of Possession token (PoP), rather than a Bearer token. 
+        ///  Modifies the token acquisition request so that the acquired token is a Proof-of-Possession token (PoP), rather than a Bearer token. 
         ///  PoP tokens are similar to Bearer tokens, but are bound to the HTTP request and to a cryptographic key, which MSAL can manage on Windows.
         ///  Note that only the host and path parts of the request URI will be bound.
         ///  See https://aka.ms/msal-net-pop
         /// </summary>
-        /// <param name="httpMethod">The HTTP method ("GET", "POST" etc.) method that will be bound to the token. Leave null and the POP token will not be bound to the method.
-        /// Corresponds to the "m" part of the a signed HTTP request.</param>
-        /// <param name="requestUri">The URI to bind the signed HTTP request to.</param>
         /// <param name="nonce">Nonce of the protected resource (RP) which will be published as part of the WWWAuthenticate header associated with a 401 HTTP response
         /// or as part of the AuthorityInfo header associated with 200 response. Set it here to make it part of the Signed HTTP Request part of the POP token.</param>
+        /// <param name="httpMethod">The HTTP method ("GET", "POST" etc.) method that will be bound to the token. If set to null, the PoP token will not be bound to the method.
+        /// Corresponds to the "m" part of the a signed HTTP request.</param>
+        /// <param name="requestUri">The URI to bind the signed HTTP request to.</param>
         /// <returns>The builder.</returns>
         /// <remarks>
         /// <list type="bullet">
-        /// <item><description>An Authentication header is automatically added to the request</description></item>
+        /// <item><description>An Authentication header is automatically added to the request.</description></item>
         /// <item><description>The PoP token is bound to the HTTP request, more specifically to the HTTP method (GET, POST, etc.) and to the Uri (path and query, but not query parameters).</description></item>
-        /// <item><description>This is an experimental API. The method signature may change in the future without involving a major version upgrade.</description></item>
+        /// <item><description>Broker is required to use Proof-of-Possession on public clients.</description></item>
         /// </list>
         /// </remarks>
 #if iOS || ANDROID || WINDOWS_UWP

src/client/Microsoft.Identity.Client/ApiConfig/AcquireTokenInteractiveParameterBuilder.cs

@@ -336,22 +336,22 @@ public AcquireTokenInteractiveParameterBuilder WithParentActivityOrWindow(NSWind
         #endregion
 
         /// <summary>
-        ///  Modifies the token acquisition request so that the acquired token is a Proof of Possession token (PoP), rather than a Bearer token. 
+        ///  Modifies the token acquisition request so that the acquired token is a Proof-of-Possession token (PoP), rather than a Bearer token. 
         ///  PoP tokens are similar to Bearer tokens, but are bound to the HTTP request and to a cryptographic key, which MSAL can manage on Windows.
         ///  Note that only the host and path parts of the request URI will be bound.
         ///  See https://aka.ms/msal-net-pop
         /// </summary>
-        /// <param name="httpMethod">The HTTP method ("GET", "POST" etc.) method that will be bound to the token. Leave null and the POP token will not be bound to the method.
+        /// <param name="nonce">Nonce of the protected resource which will be published as part of the WWW-Authenticate header associated with a 401 HTTP response
+        /// or as part of the AuthorityInfo header associated with 200 response. Set it here to make it part of the Signed HTTP Request part of the PoP token.</param>
+        /// <param name="httpMethod">The HTTP method ("GET", "POST" etc.) method that will be bound to the token. If set to null, the PoP token will not be bound to the method.
         /// Corresponds to the "m" part of the a signed HTTP request.</param>
         /// <param name="requestUri">The URI to bind the signed HTTP request to.</param>
-        /// <param name="nonce">Nonce of the protected resource (RP) which will be published as part of the WWWAuthenticate header associated with a 401 HTTP response
-        /// or as part of the AuthorityInfo header associated with 200 response. Set it here to make it part of the Signed HTTP Request part of the POP token.</param>
         /// <returns>The builder.</returns>
         /// <remarks>
         /// <list type="bullet">
-        /// <item><description>An Authentication header is automatically added to the request</description></item>
+        /// <item><description>An Authentication header is automatically added to the request.</description></item>
         /// <item><description>The PoP token is bound to the HTTP request, more specifically to the HTTP method (GET, POST, etc.) and to the Uri (path and query, but not query parameters).</description></item>
-        /// <item><description>This is an experimental API. The method signature may change in the future without involving a major version upgrade.</description></item>
+        /// <item><description>Broker is required to use Proof-of-Possession on public clients.</description></item>
         /// </list>
         /// </remarks>
 #if iOS || ANDROID || WINDOWS_UWP

src/client/Microsoft.Identity.Client/ApiConfig/AcquireTokenSilentParameterBuilder.cs

@@ -146,11 +146,11 @@ public AcquireTokenSilentParameterBuilder WithSendX5C(bool withSendX5C)
         }
 
         /// <summary>
-        ///  Modifies the token acquisition request so that the acquired token is a Proof of Possession token (PoP), rather than a Bearer token. 
+        ///  Modifies the token acquisition request so that the acquired token is a Proof-of-Possession token (PoP), rather than a Bearer token. 
         ///  PoP tokens are similar to Bearer tokens, but are bound to the HTTP request and to a cryptographic key, which MSAL can manage on Windows.
         ///  See https://aka.ms/msal-net-pop
         /// </summary>
-        /// <param name="popAuthenticationConfiguration">Configuration properties used to construct a proof of possession request.</param>
+        /// <param name="popAuthenticationConfiguration">Configuration properties used to construct a Proof-of-Possession request.</param>
         /// <remarks>
         /// <list type="bullet">
         /// <item><description>An Authentication header is automatically added to the request.</description></item>
@@ -160,7 +160,7 @@ public AcquireTokenSilentParameterBuilder WithSendX5C(bool withSendX5C)
         /// </list>
         /// </remarks>
 #if !SUPPORTS_CONFIDENTIAL_CLIENT
-        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]  // hide confidential client on mobile
+        [System.ComponentModel.EditorBrowsable(System.ComponentModel.EditorBrowsableState.Never)]  // hide on public client
 #endif
         public AcquireTokenSilentParameterBuilder WithProofOfPossession(PoPAuthenticationConfiguration popAuthenticationConfiguration)
         {
@@ -175,23 +175,24 @@ public AcquireTokenSilentParameterBuilder WithProofOfPossession(PoPAuthenticatio
         }
 
         /// <summary>
-        ///  Modifies the token acquisition request so that the acquired token is a Proof of Possession token (PoP), rather than a Bearer token. 
+        ///  Modifies the token acquisition request so that the acquired token is a Proof-of-Possession token (PoP), rather than a Bearer token. 
         ///  PoP tokens are similar to Bearer tokens, but are bound to the HTTP request and to a cryptographic key, which MSAL can manage on Windows.
         ///  Note that only the host and path parts of the request URI will be bound.
         ///  See https://aka.ms/msal-net-pop
         /// </summary>
-        /// <param name="httpMethod">The HTTP method ("GET", "POST" etc.) method that will be bound to the token. Leave null and the POP token will not be bound to the method.
-        /// Corresponds to the "m" part of the a signed HTTP request.</param>
-        /// <param name="requestUri">The URI to bind the signed HTTP request to.</param>
         /// <param name="nonce">Nonce of the protected resource (RP) which will be published as part of the WWWAuthenticate header associated with a 401 HTTP response
         /// or as part of the AuthorityInfo header associated with 200 response. Set it here to make it part of the Signed HTTP Request part of the POP token.</param>
+        /// <param name="httpMethod">The HTTP method ("GET", "POST" etc.) method that will be bound to the token. If set to null, the PoP token will not be bound to the method.
+        /// Corresponds to the "m" part of the a signed HTTP request.</param>
+        /// <param name="requestUri">The URI to bind the signed HTTP request to.</param>
         /// <returns>The builder.</returns>
         /// <remarks>
         /// <list type="bullet">
-        /// <item><description>An Authentication header is automatically added to the request</description></item>
+        /// <item><description>An Authentication header is automatically added to the request.</description></item>
         /// <item><description>The PoP token is bound to the HTTP request, more specifically to the HTTP method (GET, POST, etc.) and to the Uri (path and query, but not query parameters).</description></item>
         /// <item><description>MSAL creates, reads and stores a key in memory that will be cycled every 8 hours.</description></item>
-        /// <item><description>This is an experimental API. The method signature may change in the future without involving a major version upgrade.</description></item>
+        /// <item><description>On confidential clients, this is an experimental API. The method signature may change in the future without involving a major version upgrade.</description></item>
+        /// <item><description>Broker is required to use Proof-of-Possession on public clients.</description></item>
         /// </list>
         /// </remarks>
 #if iOS || ANDROID || WINDOWS_UWP
@@ -200,7 +201,9 @@ public AcquireTokenSilentParameterBuilder WithProofOfPossession(PoPAuthenticatio
         public AcquireTokenSilentParameterBuilder WithProofOfPossession(string nonce, HttpMethod httpMethod, Uri requestUri)
         {
             if (ServiceBundle.Config.IsConfidentialClient)
+            {
                 ValidateUseOfExperimentalFeature();
+            }
 
             // On public client, we only support POP via the broker
             if (!ServiceBundle.Config.IsConfidentialClient &&

src/client/Microsoft.Identity.Client/MsalError.cs

@@ -890,14 +890,14 @@ public static class MsalError
         public const string CryptoNet45 = "crypto_net45";
 
         /// <summary>
-        /// <para>What happens?</para>The request has broker enabled and proof of possession configured but the broker does not support proof of possession
-        /// <para>Mitigation</para>only configure proof of possession for public clients on windows.
+        /// <para>What happens?</para>The request has broker enabled and Proof-of-Possession configured but the broker does not support Proof-of-Possession
+        /// <para>Mitigation</para>only configure Proof-of-Possession for public clients on windows.
         /// </summary>
         public const string BrokerDoesNotSupportPop = "broker_does_not_support_pop";
 
         /// <summary>
-        /// <para>What happens?</para>The request has proof of possession configured but does not have broker enabled. Broker is required for proof of possession on public clients
-        /// <para>Mitigation</para>Enable the broker when proof of possession is configured.
+        /// <para>What happens?</para>The request has Proof-of-Possession configured but does not have broker enabled. Broker is required to use Proof-of-Possession on public clients
+        /// <para>Mitigation</para>Enable the broker when Proof-of-Possession is configured.
         /// </summary>
         public const string BrokerRequiredForPop = "broker_required_for_pop";
 
@@ -908,8 +908,8 @@ public static class MsalError
         public const string AdfsNotSupportedWithBroker = "adfs_not_supported_with_broker";
 
         /// <summary>
-        /// <para>What happens?</para>The request has proof of possession configured but does not have a nonce configured. A nonce is required for proof of possession on public clients
-        /// <para>Mitigation</para>Provide a nonce when proof of possession is configured for public clients.
+        /// <para>What happens?</para>The request has Proof-of-Possession configured but does not have a nonce configured. A nonce is required for Proof-of-Possession on public clients
+        /// <para>Mitigation</para>Provide a nonce when Proof-of-Possession is configured for public clients.
         /// </summary>
         public const string NonceRequiredForPopOnPCA = "nonce_required_for_pop_on_pca";
 #if iOS

src/client/Microsoft.Identity.Client/MsalErrorMessage.cs

@@ -131,7 +131,7 @@ public static string iOSBrokerKeySaveFailed(string keyChainResult)
         public const string CannotInvokeBrokerForPop = "MSAL cannot invoke the broker and it is required for Proof-of-Possession. WAM (Broker) may not be installed on the user's device or there was an error invoking the broker. Use IPublicCleintApplication.IsProofOfPossessionSupportedByClient to ensure Proof-of-Possession can be performed before using WithProofOfPossession." +
             "Check logs for more details and see https://aka.ms/msal-net-pop. ";
         public const string BrokerDoesNotSupportPop = "The broker does not support Proof-of-Possession on the current platform.";
-        public const string BrokerRequiredForPop = "The request has Proof-of-Possession configured but does not have broker enabled. Broker is required for Proof-of-Possession on public clients. Use IPublicCleintApplication.IsProofOfPossessionSupportedByClient to ensure Proof-of-Possession can be performed before using WithProofOfPossession.";
+        public const string BrokerRequiredForPop = "The request has Proof-of-Possession configured but does not have broker enabled. Broker is required to use Proof-of-Possession on public clients. Use IPublicCleintApplication.IsProofOfPossessionSupportedByClient to ensure Proof-of-Possession can be performed before using WithProofOfPossession.";
         public const string NonceRequiredForPop = "The request has Proof-of-Possession configured for public clients but does not have a nonce provided. A nonce is required for Proof-of-Possession on public clients.";
         public const string AdfsNotSupportedWithBroker = "Broker does not support ADFS environments. If using Proof-of-Possession, use IPublicCleintApplication.IsProofOfPossessionSupportedByClient to ensure Proof-of-Possession can be performed before calling WithProofOfPossession.";