Merge pull request #596 from yidongnan/feature/dynamic-bearer-token

Add dynamic CallCredentials helpers

Author: yidongnan

docs/en/client/security.md

@@ -12,6 +12,9 @@ This page describes how you connect to a grpc server and authenticate yourself.
   - [Trusting a Server](#trusting-a-server)
 - [Mutual Certificate Authentication](#mutual-certificate-authentication)
 - [Authentication](#authentication)
+  - [Creating CallCredentials](#creating-callcredentials)
+  - [Using CallCredentials](#using-callcredentials)
+  - [Retry with new Authentication](#retry-with-new-authentication)
 
 ## Additional Topics <!-- omit in toc -->
 
@@ -97,6 +100,8 @@ grpc.client.__name__.security.privateKey=file:certificates/client.key
 
 ## Authentication
 
+### Creating CallCredentials
+
 In addition to mutual certificate authentication, there are several other ways to authenticate yourself, such as
 `BasicAuth`.
 
@@ -106,6 +111,20 @@ various libraries out there that provide implementations for grpc's
 `CallCredentials` are potentially active components because they can authenticate the request using a (third party)
 service and can manage and renew session tokens themselves.
 
+````java
+@Bean
+CallCredentials basicAuthCredentials() {
+    return CallCredentialsHelper.basicAuth("user", "password");
+}
+
+@Bean
+CallCredentials bearerAuthForwardingCredentials() {
+    return CallCredentialsHelper.bearerAuth(() -> KeycloakSecurityContext.getTokenString());
+}
+````
+
+### Using CallCredentials
+
 If you have exactly one `CallCredentials` in your application context, we'll automatically create a `StubTransformer`
 for you and configure all `Stub`s to use it. If you wish to configure different credentials per stub, then you use our
 helper methods in the
@@ -122,6 +141,45 @@ MyServiceBlockingStub myServiceForUser = myService.withCallCredentials(userCrede
 return myServiceForUser.send(request);
 ````
 
+### Retry with new Authentication
+
+If you want to retry calls that failed due to an expired token (using grpc's built-in retry mechanism), you can use the
+following example `ClientInterceptor` as a guide to automatically report the failure to the token store.
+Please note that many popular token-based authentication systems (such as OAuth) also provide a token TTL that can be
+used to automatically update the token before the call is even sent for the first time, rendering this obsolete.
+
+````java
+@Override
+public <ReqT, RespT> ClientCall<ReqT, RespT> interceptCall(
+        MethodDescriptor<ReqT, RespT> method, CallOptions callOptions, Channel next) {
+
+    callOptions = callOptions
+            .withCallCredentials(this.credentials)
+            .withStreamTracerFactory(new ClientStreamTracer.Factory() {
+
+                @Override
+                public ClientStreamTracer newClientStreamTracer(
+                        ClientStreamTracer.StreamInfo info, Metadata headers) {
+
+                    // Make sure your implementations do _not_ block and return _immediately_
+                    final Object authToken = headers.get(AUTH_TOKEN_KEY);
+                    return new ClientStreamTracer() {
+
+                        @Override
+                        public void streamClosed(final Status status) {
+                            this.credentials.invalidate(authToken);
+                        }
+                    };
+
+                }
+            });
+
+    return next.newCall(method, callOptions);
+}
+````
+
+For more details refer to [How to retry with new auth token using builtin retry?](https://github.com/grpc/grpc-java/issues/7345#issuecomment-679295003)
+
 ## Additional Topics <!-- omit in toc -->
 
 - [Getting Started](getting-started.md)

grpc-client-spring-boot-autoconfigure/src/main/java/net/devh/boot/grpc/client/security/CallCredentialsHelper.java

@@ -27,6 +27,7 @@
 import java.util.Base64;
 import java.util.Map;
 import java.util.concurrent.Executor;
+import java.util.function.Supplier;
 
 import javax.annotation.Nullable;
 
@@ -57,6 +58,8 @@
  * </p>
  * <ul>
  * <li>{@link #basicAuth(String, String) Basic-Auth}</li>
+ * <li>{@link #bearerAuth(Supplier) Bearer-Auth}</li>
+ * <li>Other variants using static or dynamic headers</li>
  * <li>{@link #requirePrivacy(CallCredentials) Require privacy for the connection} (Wrapper)</li>
  * <li>{@link #includeWhenPrivate(CallCredentials) Include credentials only if connection is private} (Wrapper)</li>
  * </ul>
@@ -72,7 +75,7 @@
  * <pre>
  * <code>@Bean
  * CallCredentials myCallCredentials() {
- *     return CallCredentialsHelper#basicAuth("user", "password")}
+ *     return CallCredentialsHelper.basicAuth("user", "password");
  * }</code>
  * </pre>
  *
@@ -84,7 +87,7 @@
  * <pre>
  * <code>@Bean
  * StubTransformer myCallCredentialsTransformer() {
- *     return CallCredentialsHelper#mappedCredentialsStubTransformer(Map.of(
+ *     return CallCredentialsHelper.mappedCredentialsStubTransformer(Map.of(
  *         "myService1", basicAuth("user1", "password1"),
  *         "theService2", basicAuth("foo", "bar"),
  *         "publicApi", null // No credentials needed
@@ -96,7 +99,7 @@
  * <li>If you need different CallCredentials for each call, then you have to define it in the method yourself.
  *
  * <pre>
- * <code>stub.withCallCredentials(CallCredentialsHelper#basicAuth("user", "password")).doStuff(request);</code>
+ * <code>stub.withCallCredentials(CallCredentialsHelper.basicAuth("user", "password")).doStuff(request);</code>
  * </pre>
  *
  * </li>
@@ -159,7 +162,8 @@ public static StubTransformer mappedCredentialsStubTransformer(
     }
 
     /**
-     * Creates new call credentials with the given token for bearer auth.
+     * Creates new call credentials with the given token for bearer auth. Use this method if you have a permanent token
+     * or only use the call credentials for a single call/while the token is valid.
      *
      * <p>
      * <b>Note:</b> This method uses experimental grpc-java-API features.
@@ -174,6 +178,23 @@ public static CallCredentials bearerAuth(final String token) {
         return authorizationHeader(BEARER_AUTH_PREFIX + token);
     }
 
+    /**
+     * Creates new call credentials with the given token source for bearer auth. Use this method if you derive the token
+     * from the active context (e.g. currently logged in user) or dynamically obtain it from the authentication server.
+     *
+     * <p>
+     * <b>Note:</b> This method uses experimental grpc-java-API features.
+     * </p>
+     *
+     * @param tokenSource the bearer token source to use
+     * @return The newly created bearer auth credentials.
+     * @see SecurityConstants#BEARER_AUTH_PREFIX
+     * @see #authorizationHeader(Supplier)
+     */
+    public static CallCredentials bearerAuth(final Supplier<String> tokenSource) {
+        return authorizationHeader(() -> BEARER_AUTH_PREFIX + tokenSource);
+    }
+
     /**
      * Creates new call credentials with the given username and password for basic auth.
      *
@@ -228,32 +249,55 @@ public static String encodeBasicAuth(final String username, final String passwor
      * @see #authorizationHeaders(Metadata)
      */
     public static CallCredentials authorizationHeader(final String authorization) {
-        requireNonNull(authorization);
+        requireNonNull(authorization, "authorization");
         final Metadata extraHeaders = new Metadata();
         extraHeaders.put(AUTHORIZATION_HEADER, authorization);
         return authorizationHeaders(extraHeaders);
     }
 
+    /**
+     * Creates new call credentials with the given authorization information source.
+     *
+     * <p>
+     * <b>Note:</b> This method uses experimental grpc-java-API features.
+     * </p>
+     *
+     * @param authorizationSource The authorization source to use. The authorization usually starts with the scheme such
+     *        as as {@code "Basic "} or {@code "Bearer "} followed by the actual authentication information.
+     * @return The newly created call credentials.
+     * @see SecurityConstants#AUTHORIZATION_HEADER
+     * @see #authorizationHeaders(Supplier)
+     */
+    public static CallCredentials authorizationHeader(final Supplier<String> authorizationSource) {
+        requireNonNull(authorizationSource, "authorizationSource");
+
+        return authorizationHeaders(() -> {
+            final Metadata extraHeaders = new Metadata();
+            extraHeaders.put(AUTHORIZATION_HEADER, authorizationSource.get());
+            return extraHeaders;
+        });
+    }
+
     /**
      * Creates new call credentials with the given static authorization headers.
      *
      * @param authorizationHeaders The authorization headers to use.
      * @return The newly created call credentials.
      */
     public static CallCredentials authorizationHeaders(final Metadata authorizationHeaders) {
-        return new StaticSecurityHeaderCallCredentials(requireNonNull(authorizationHeaders));
+        return new StaticSecurityHeaderCallCredentials(authorizationHeaders);
     }
 
     /**
-     * The static security header {@link CallCredentials} simply add a set of predefined headers to the call. Their
+     * The static security header {@link CallCredentials} simply adds a set of predefined headers to the call. Their
      * specific meaning is server specific. This implementation can be used, for example, for BasicAuth.
      */
     private static final class StaticSecurityHeaderCallCredentials extends CallCredentials {
 
         private final Metadata extraHeaders;
 
-        StaticSecurityHeaderCallCredentials(final Metadata extraHeaders) {
-            this.extraHeaders = requireNonNull(extraHeaders, "extraHeaders");
+        StaticSecurityHeaderCallCredentials(final Metadata authorizationHeaders) {
+            this.extraHeaders = requireNonNull(authorizationHeaders, "authorizationHeaders");
         }
 
         @Override
@@ -272,6 +316,44 @@ public String toString() {
 
     }
 
+    /**
+     * Creates new call credentials with the given authorization headers source.
+     *
+     * @param authorizationHeadersSupplier The authorization headers source to use.
+     * @return The newly created call credentials.
+     */
+    public static CallCredentials authorizationHeaders(final Supplier<Metadata> authorizationHeadersSupplier) {
+        return new DynamicSecurityHeaderCallCredentials(authorizationHeadersSupplier);
+    }
+
+    /**
+     * The dynamic security header {@link CallCredentials} simply adds a set of dynamic headers to the call. Their
+     * specific meaning is server specific. This implementation can be used, for example, for BasicAuth.
+     */
+    private static final class DynamicSecurityHeaderCallCredentials extends CallCredentials {
+
+        private final Supplier<Metadata> extraHeadersSupplier;
+
+        DynamicSecurityHeaderCallCredentials(final Supplier<Metadata> authorizationHeadersSupplier) {
+            this.extraHeadersSupplier = requireNonNull(authorizationHeadersSupplier, "authorizationHeadersSupplier");
+        }
+
+        @Override
+        public void applyRequestMetadata(final RequestInfo requestInfo, final Executor appExecutor,
+                final MetadataApplier applier) {
+            applier.apply(this.extraHeadersSupplier.get());
+        }
+
+        @Override
+        public void thisUsesUnstableApi() {} // API evolution in progress
+
+        @Override
+        public String toString() {
+            return "DynamicSecurityHeaderCallCredentials [extraHeadersSupplier=" + this.extraHeadersSupplier + "]";
+        }
+
+    }
+
     /**
      * Checks whether the given security level provides privacy for all data being send on the connection.
      *