From 44a4804f180b9f99da05db780710bed11aa7b86d Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Ahmet=20=C4=B0brahim=20Aksoy?= <aaksoy@microsoft.com>
Date: Mon, 8 Jun 2026 13:06:38 +0200
Subject: [PATCH] Clarify NegotiateAuthentication.IsAuthenticated post-failure
 behavior

The IsAuthenticated property returns true after the authentication exchange has finished, including in many post-negotiation failure cases (verified across the Windows, Unix, and ManagedSpnego PAL implementations in dotnet/runtime). The previous summary (successfully completed and the session was established) implied that a true value means successful authentication, which is misleading.

Update the summary, value, and remarks to clarify that callers must inspect the NegotiateAuthenticationStatusCode returned by GetOutgoingBlob to determine actual success.

Also remove a misleading `(see IsAuthenticated)` reference on TargetName that reinforced the same misconception.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
---
 .../NegotiateAuthentication.xml                | 18 ++++++++++++++----
 1 file changed, 14 insertions(+), 4 deletions(-)

diff --git a/xml/System.Net.Security/NegotiateAuthentication.xml b/xml/System.Net.Security/NegotiateAuthentication.xml
index 7e0b6c06de1..7173aa9fdf5 100644
--- a/xml/System.Net.Security/NegotiateAuthentication.xml
+++ b/xml/System.Net.Security/NegotiateAuthentication.xml
@@ -287,9 +287,19 @@ When <xref:System.Net.Security.NegotiateAuthenticationStatusCode.ContinueNeeded>
         <ReturnType>System.Boolean</ReturnType>
       </ReturnValue>
       <Docs>
-        <summary>Gets a value that indicates whether authentication was successfully completed and the session was established.</summary>
-        <value>To be added.</value>
-        <remarks>To be added.</remarks>
+        <summary>Gets a value that indicates whether the authentication exchange has completed.</summary>
+        <value><see langword="true" /> if the authentication exchange has completed; otherwise, <see langword="false" />.</value>
+        <remarks>
+          <format type="text/markdown"><![CDATA[
+
+## Remarks
+
+This property indicates whether the authentication exchange has completed, not whether authentication succeeded. A `true` value can be returned after either successful authentication or a terminal authentication failure.
+
+To determine whether authentication actually succeeded, inspect the <xref:System.Net.Security.NegotiateAuthenticationStatusCode> returned by the most recent call to <xref:System.Net.Security.NegotiateAuthentication.GetOutgoingBlob%2A>. The status is <xref:System.Net.Security.NegotiateAuthenticationStatusCode.Completed> on success; any other value indicates that authentication didn't complete successfully.
+
+          ]]></format>
+        </remarks>
       </Docs>
     </Member>
     <Member MemberName="IsEncrypted">
@@ -544,7 +554,7 @@ The negotiated level of protection is only available when the session
 ## Remarks
 
 For the server side of the authentication, the property returns the target name
-             specified by the client after successful authentication (see <xref:System.Net.Security.NegotiateAuthentication.IsAuthenticated>).
+             specified by the client after authentication completes successfully.
 
 For the client side of the authentication, the property returns the target name
              specified in <xref:System.Net.Security.NegotiateAuthenticationClientOptions.TargetName>.