Deprecate Authentication#setAuthenticated

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

Closes gh-16668

Signed-off-by: yybmion <[email protected]>

Author: yybmion

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;
 
 }

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.