From 79ae1708b1fb3f639bf47f9ed02ae6da18adb9f5 Mon Sep 17 00:00:00 2001
From: yybmion <yunyubin54@gmail.com>
Date: Fri, 28 Mar 2025 17:39:09 +0900
Subject: [PATCH] Deprecate Authentication#setAuthenticated

This commit deprecates the Authentication#setAuthenticated method
in favor of implementing isAuthenticated().

Closes gh-16668

Signed-off-by: yybmion <yunyubin54@gmail.com>
---
 .../security/core/Authentication.java         |  4 +-
 .../ROOT/pages/migration/authentication.adoc  | 51 +++++++++++++++++++
 2 files changed, 54 insertions(+), 1 deletion(-)

diff --git a/core/src/main/java/org/springframework/security/core/Authentication.java b/core/src/main/java/org/springframework/security/core/Authentication.java
index d3f38a5c114..fba8105d9a2 100644
--- a/core/src/main/java/org/springframework/security/core/Authentication.java
+++ b/core/src/main/java/org/springframework/security/core/Authentication.java
@@ -1,5 +1,5 @@
 /*
- * Copyright 2004, 2005, 2006 Acegi Technology Pty Limited
+ * Copyright 2002-2025 the original author or authors.
  *
  * Licensed under the Apache License, Version 2.0 (the "License");
  * you may not use this file except in compliance with the License.
@@ -131,7 +131,9 @@ public interface Authentication extends Principal, Serializable {
 	 * trusted (by passing <code>true</code> as the argument) is rejected due to the
 	 * implementation being immutable or implementing its own alternative approach to
 	 * {@link #isAuthenticated()}
+	 * @deprecated in favor of implementing {@link #isAuthenticated()}
 	 */
+	@Deprecated
 	void setAuthenticated(boolean isAuthenticated) throws IllegalArgumentException;
 
 }
diff --git a/docs/modules/ROOT/pages/migration/authentication.adoc b/docs/modules/ROOT/pages/migration/authentication.adoc
index 9c5407ae00a..81841cf2d91 100644
--- a/docs/modules/ROOT/pages/migration/authentication.adoc
+++ b/docs/modules/ROOT/pages/migration/authentication.adoc
@@ -66,3 +66,54 @@ fun introspector(): OpaqueTokenIntrospector {
 }
 ----
 ======
+
+== Deprecated Authentication#setAuthenticated
+
+The `Authentication#setAuthenticated` method has been deprecated in favor of implementing the `isAuthenticated()` method.
+
+Previously, implementations might use `setAuthenticated` to mark an authentication token as valid:
+
+[source,java]
+----
+Authentication auth = // create authentication
+auth.setAuthenticated(true); // DEPRECATED
+----
+
+Instead, implementations should override the `isAuthenticated()` method to determine authentication validity:
+
+[tabs]
+======
+Java::
++
+[source,java,role="primary"]
+----
+public class MyAuthentication implements Authentication {
+
+	// Other methods...
+
+	@Override
+	public boolean isAuthenticated() {
+		// Custom logic to determine if this authentication is valid
+		return this.validated;
+	}
+}
+----
+
+Kotlin::
++
+[source,kotlin,role="secondary"]
+----
+class MyAuthentication : Authentication {
+
+	// Other methods...
+
+	override fun isAuthenticated(): Boolean {
+		// Custom logic to determine if this authentication is valid
+		return this.validated
+	}
+}
+----
+======
+
+Note that existing implementations will still need to support `setAuthenticated` for backward compatibility,
+but new code should avoid calling this method.