Specify clientRegistrationId in TokenRelay filter (#2922)

docs/src/main/asciidoc/spring-cloud-gateway.adoc

@@ -2032,7 +2032,46 @@ consumer can be a pure Client (like an SSO application) or a Resource
 Server.
 
 Spring Cloud Gateway can forward OAuth2 access tokens downstream to the services
-it is proxying. To add this functionality to the gateway, you need to add the `TokenRelayGatewayFilterFactory` like this:
+it is proxying using the `TokenRelay` `GatewayFilter`.
+
+The `TokenRelay` `GatewayFilter` takes one optional parameter, `clientRegistrationId`.
+The following example configures a `TokenRelay` `GatewayFilter`:
+
+.App.java
+[source,java]
+----
+
+@Bean
+public RouteLocator customRouteLocator(RouteLocatorBuilder builder) {
+    return builder.routes()
+            .route("resource", r -> r.path("/resource")
+                    .filters(f -> f.tokenRelay("myregistrationid"))
+                    .uri("http://localhost:9000"))
+            .build();
+}
+----
+
+or this
+
+.application.yaml
+[source,yaml]
+----
+spring:
+  cloud:
+    gateway:
+      routes:
+      - id: resource
+        uri: http://localhost:9000
+        predicates:
+        - Path=/resource
+        filters:
+        - TokenRelay=myregistrationid
+----
+
+The example above specifies a `clientRegistrationId`, which can be used to obtain and forward an OAuth2 access token for any available `ClientRegistration`.
+
+Spring Cloud Gateway can also forward the OAuth2 access token of the currently authenticated user `oauth2Login()` is used to authenticate the user.
+To add this functionality to the gateway, you can omit the `clientRegistrationId` parameter like this:
 
 .App.java
 [source,java]
@@ -2073,10 +2112,10 @@ To enable this for Spring Cloud Gateway add the following dependencies
 
 - `org.springframework.boot:spring-boot-starter-oauth2-client`
 
-How does it work?  The
-{githubmaster}/src/main/java/org/springframework/cloud/gateway/security/TokenRelayGatewayFilterFactory.java[filter]
-extracts an access token from the currently authenticated user,
-and puts it in a request header for the downstream requests.
+How does it work?  The {github-code}/src/main/java/org/springframework/cloud/gateway/security/TokenRelayGatewayFilterFactory.java[filter]
+extracts an OAuth2 access token from the currently authenticated user for the provided `clientRegistrationId`.
+If no `clientRegistrationId` is provided, the currently authenticated user's own access token (obtained during login) is used.
+In either case, the extracted access token is placed in a request header for the downstream requests.
 
 For a full working sample see https://github.com/spring-cloud-samples/sample-gateway-oauth2login[this project].