From aea7f333f76e45c7420bc504a859774696040c92 Mon Sep 17 00:00:00 2001
From: Josh Cummings <3627351+jzheaux@users.noreply.github.com>
Date: Thu, 16 Jan 2025 20:01:47 -0700
Subject: [PATCH] Document OpaqueTokenIntrospector Migration

Issue gh-15988
---
 .../ROOT/pages/migration/authentication.adoc  | 68 +++++++++++++++++++
 1 file changed, 68 insertions(+)
 create mode 100644 docs/modules/ROOT/pages/migration/authentication.adoc

diff --git a/docs/modules/ROOT/pages/migration/authentication.adoc b/docs/modules/ROOT/pages/migration/authentication.adoc
new file mode 100644
index 0000000000..9c5407ae00
--- /dev/null
+++ b/docs/modules/ROOT/pages/migration/authentication.adoc
@@ -0,0 +1,68 @@
+= Authentication Changes
+
+== Opaque Token Credentials Will Be Encoded For You
+
+In order to comply more closely with the Introspection RFC, Spring Security's opaque token support will encode the client id and secret before creating the authorization header.
+This change means you will no longer have to encode the client id and secret yourself.
+
+If your client id or secret contain URL-unsafe characters, then you can prepare yourself for this change by doing the following:
+
+=== Replace Usage of `introspectionClientCredentials`
+
+Since Spring Security can now do the encoding for you, replace xref:servlet/oauth2/resource-server/opaque-token.adoc#oauth2resourceserver-opaque-introspectionuri-dsl[using `introspectionClientCredentials`] with publishing the following `@Bean`:
+
+[tabs]
+======
+Java::
++
+[source,java,role="primary"]
+----
+@Bean
+OpaqueTokenIntrospector introspector() {
+	return SpringOpaqueTokenIntrospector.withIntrospectionUri(introspectionUri)
+            .clientId(unencodedClientId).clientSecret(unencodedClientSecret).build();
+}
+----
+
+Kotlin::
++
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun introspector(): OpaqueTokenIntrospector {
+    return SpringOpaqueTokenIntrospector.withIntrospectionUri(introspectionUri)
+            .clientId(unencodedClientId).clientSecret(unencodedClientSecret).build()
+}
+----
+======
+
+The above will be the default in 7.0.
+
+If this setting gives you trouble or you cannot apply it for now, you can use the `RestOperations` constructor instead:
+
+[tabs]
+======
+Java::
++
+[source,java,role="primary"]
+----
+@Bean
+OpaqueTokenIntrospector introspector() {
+	RestTemplate rest = new RestTemplate();
+	rest.addInterceptor(new BasicAuthenticationInterceptor(encodedClientId, encodedClientSecret));
+	return new SpringOpaqueTokenIntrospector(introspectionUri, rest);
+}
+----
+
+Kotlin::
++
+[source,kotlin,role="secondary"]
+----
+@Bean
+fun introspector(): OpaqueTokenIntrospector {
+	val rest = RestTemplate()
+	rest.addInterceptor(BasicAuthenticationInterceptor(encodedClientId, encodedClientSecret))
+	return SpringOpaqueTokenIntrospector(introspectionUri, rest)
+}
+----
+======