initial commit

Author: augi

.gitignore

@@ -1,14 +1,6 @@
 .gradle
+.idea
 /build/
-
-# Ignore Gradle GUI config
-gradle-app.setting
-
+/out/
 # Avoid ignoring Gradle wrapper jar file (.jar files are usually ignored)
 !gradle-wrapper.jar
-
-# Cache of project
-.gradletasknamecache
-
-# # Work around https://youtrack.jetbrains.com/issue/IDEA-116898
-# gradle/wrapper/gradle-wrapper.properties

.travis.yml

@@ -0,0 +1,15 @@
+language: java
+services:
+  - docker
+
+after_success:
+  - test $TRAVIS_PULL_REQUEST == "false" && test "$TRAVIS_TAG" != "" && test $TRAVIS_REPO_SLUG == "avast/grpc-java-jwt" ./gradlew bintrayUpload -Pversion="$TRAVIS_TAG" --info --no-daemon
+
+before_cache:
+- rm -f  $HOME/.gradle/caches/modules-2/modules-2.lock
+- rm -fr $HOME/.gradle/caches/*/plugin-resolution/
+cache:
+  directories:
+  - $HOME/.gradle/caches/
+  - $HOME/.gradle/wrapper/
+  - $HOME/.m2

README.md

@@ -0,0 +1,74 @@
+# gRPC Java JWT support
+[![Build Status](https://travis-ci.org/avast/grpc-java-jwt.svg?branch=master)](https://travis-ci.org/avast/grpc-java-jwt) [![Download](https://api.bintray.com/packages/avast/maven/grpc-java-jwt/images/download.svg) ](https://bintray.com/avast/maven/grpc-java-jwt/_latestVersion)
+
+Library that helps with authenticated communication in gRPC-Java based applications. It uses [JSON Web Token](https://jwt.io/) transported in `Authorization` header (as `Bearer rawJWT`).
+
+Implementation of standard `CallCredentials` ensures that the header is sent, and `ServerInterceptor` ensures that the incoming header is valid and makes the parsed JWT available for the underlying code.
+
+```maven
+<dependency>
+  <groupId>com.avast.grpc</groupId>
+  <artifactId>grpc-java-jwt</artifactId>
+  <version>$latestVersion</version>
+</dependency>
+```
+```gradle
+compile "com.avast.grpc:grpc-java-jwt:$latestVersion"
+````
+
+## Keycloak support
+There are implementations of the core interfaces for [Keycloak](https://www.keycloak.org/).
+
+```maven
+<dependency>
+  <groupId>com.avast.grpc</groupId>
+  <artifactId>grpc-java-jwt-keycloak</artifactId>
+  <version>$latestVersion</version>
+</dependency>
+```
+```gradle
+compile "com.avast.grpc:grpc-java-jwt-keycloak:$latestVersion"
+````
+
+### Client usage
+This ensures that each call contains `Authorization` header with `Bearer ` prefixed Keycloak access token (as JWT).
+```java
+import com.avast.grpc.jwt.keycloak.client.KeycloakJwtCallCredentials;
+
+KeycloakJwtCallCredentials callCredentials = KeycloakJwtCallCredentials.fromConfig(yourConfig);
+YourService.newStub(aChannel).withCallCredentials(callCredentials);
+```
+
+### Server usage
+This ensures that only requests with valid `JWT` in `Authorization` header are processed.
+ The `fromConfig` method automatically downloads the Keycloak public key before the instance is actually created.
+```java
+import io.grpc.ServerServiceDefinition;
+import com.avast.grpc.jwt.keycloak.server.KeycloakJwtServerInterceptor;
+
+KeycloakJwtServerInterceptor serverInterceptor = KeycloakJwtServerInterceptor.fromConfig(yourConfig);
+ServerServiceDefinition interceptedService = ServerInterceptors.intercept(yourService, serverInterceptor);
+
+// read token in a gRPC method implementation
+import org.keycloak.representations.AccessToken;
+AccessToken accessToken = serverInterceptor.AccessTokenContextKey.get();
+```
+
+There is also [this integration test](keycloak/src/test/java/com/avast/grpc/jwt/keycloak/KeycloakTest.java) that can serve as nice example.
+
+## Implementation notes
+
+On the client side, there is implementation of `CallCredentials` that ensures the JWT token is correctly stored to the headers. Just call a static method on [JwtCallCredentials](core/src/main/java/com/avast/grpc/jwt/client/JwtCallCredentials.java) - it will require an instance of a _JwtTokenProvider_ (an interface that returns encoded JWT).
+
+On server side, there is `ServerInterceptor` implementation that parses the incoming JWT and verifies it. [JwtServerInterceptor](core/src/main/java/com/avast/grpc/jwt/server/JwtServerInterceptor.java) requires an instance of [JwtTokenParser](core/src/main/java/com/avast/grpc/jwt/server/JwtTokenParser.java) - it's an interface that parses and verifies the JWT.
+
+## About gRPC internals
+gRCP uses terms `Metadata` and `Context keys`. `Metadata` is set of key-value pairs that are transported between client and server, et vice versa. So it's like HTTP headers.
+
+On other hand, `Context key` is set of values that are available during request processing.
+ By default, a `Storage` implementation based on `ThreadLocal` is used.
+ Thanks to this, you can just call `get()` method on a Context key and you immediately get the value because it read the value from `Context.current()`.
+ 
+So when implementing interceptors, you must be sure that you read Context values from the right thread. It's actually no issue for us because:
+1. The right thread is automatically handled by gRPC-core when using`CallCredentials`. So you can call `applier.apply()` method on any thread.
+2. Our `ServerInterceptor` implementation is fully synchronous.

build.gradle

@@ -0,0 +1,68 @@
+plugins {
+    id 'com.github.sherter.google-java-format' version '0.8' apply false
+    id 'com.google.protobuf' version '0.8.8' apply false
+    id 'com.avast.gradle.docker-compose' version '0.9.2' apply false
+    id 'com.jfrog.bintray' version '1.8.4' apply false
+}
+
+allprojects {
+    group 'com.avast.grpc'
+    version = version == 'unspecified' ? 'DEVELOPER-SNAPSHOT' : version
+}
+
+ext {
+    grpcVersion = '1.20.0'
+    protobufVersion = '3.7.1'
+}
+
+subprojects {
+    apply plugin: 'java'
+    apply plugin: 'maven'
+    apply plugin: 'com.github.sherter.google-java-format'
+    apply plugin: 'com.jfrog.bintray'
+
+    sourceCompatibility = JavaVersion.VERSION_1_8
+
+    repositories {
+        mavenCentral()
+    }
+    
+    dependencies {
+        testCompile 'junit:junit:4.12'
+        testCompile 'org.mockito:mockito-core:2.27.0'
+    }
+
+    task sourcesJar(type: Jar) {
+        from sourceSets.main.allSource
+        archiveClassifier = 'sources'
+    }
+
+    artifacts {
+        archives sourcesJar
+    }
+
+    bintray {
+        user = System.getenv('BINTRAY_USER')
+        key = System.getenv('BINTRAY_KEY')
+        configurations = ['archives']
+        publish = true
+        dryRun = true
+        pkg {
+            repo = 'maven'
+            name = 'grpc-java-jwt'
+            desc = 'Library that helps with authenticated communication in gRPC-Java based applications. It uses JSON Web Token.'
+            userOrg = 'avast'
+            licenses = ['MIT']
+            vcsUrl = 'https://github.com/avast/grpc-java-jwt.git'
+            websiteUrl = 'https://github.com/avast/grpc-java-jwt'
+            issueTrackerUrl = 'https://github.com/avast/grpc-java-jwt/issues'
+            githubRepo = 'avast/grpc-java-jwt'
+            labels = ['grpc', 'java', 'jwt', 'keycloak']
+            version {
+                name = project.version
+                vcsTag = project.version
+            }
+        }
+    }
+
+}

core/build.gradle

@@ -0,0 +1,5 @@
+archivesBaseName = 'grpc-java-jwt'
+
+dependencies {
+    compile "io.grpc:grpc-core:$grpcVersion"    
+}

core/src/main/java/com/avast/grpc/jwt/Constants.java

@@ -0,0 +1,10 @@
+package com.avast.grpc.jwt;
+
+import io.grpc.Metadata;
+
+public final class Constants {
+  private Constants() {}
+
+  public static io.grpc.Metadata.Key<String> AuthorizationMetadataKey =
+      Metadata.Key.of("Authorization", Metadata.ASCII_STRING_MARSHALLER);
+}

core/src/main/java/com/avast/grpc/jwt/client/AsyncJwtTokenProvider.java

@@ -0,0 +1,9 @@
+package com.avast.grpc.jwt.client;
+
+import java.util.concurrent.CompletableFuture;
+
+@FunctionalInterface
+public interface AsyncJwtTokenProvider {
+  /* Gets encoded JWT token. */
+  CompletableFuture<String> get();
+}

core/src/main/java/com/avast/grpc/jwt/client/BlockingJwtTokenProvider.java

@@ -0,0 +1,7 @@
+package com.avast.grpc.jwt.client;
+
+@FunctionalInterface
+public interface BlockingJwtTokenProvider {
+  /* Gets encoded JWT token, can block (e.g. perform blocking I/O). */
+  String get();
+}

core/src/main/java/com/avast/grpc/jwt/client/JwtCallCredentials.java

@@ -0,0 +1,100 @@
+package com.avast.grpc.jwt.client;
+
+import com.avast.grpc.jwt.Constants;
+import io.grpc.CallCredentials;
+import io.grpc.Metadata;
+import io.grpc.Status;
+import java.util.concurrent.Executor;
+
+public abstract class JwtCallCredentials extends CallCredentials {
+
+  public static JwtCallCredentials synchronous(SynchronousJwtTokenProvider tokenProvider) {
+    return new Synchronous(tokenProvider);
+  }
+
+  public static JwtCallCredentials blocking(BlockingJwtTokenProvider tokenProvider) {
+    return new Blocking(tokenProvider);
+  }
+
+  public static JwtCallCredentials asynchronous(AsyncJwtTokenProvider tokenProvider) {
+    return new Asynchronous(tokenProvider);
+  }
+
+  @Override
+  public void thisUsesUnstableApi() {}
+
+  protected void applyToken(MetadataApplier applier, String jwtToken) {
+    Metadata metadata = new Metadata();
+    metadata.put(Constants.AuthorizationMetadataKey, "Bearer " + jwtToken);
+    applier.apply(metadata);
+  }
+
+  protected void applyFailure(MetadataApplier applier, Throwable e) {
+    applier.fail(
+        Status.UNAUTHENTICATED
+            .withDescription("An exception when obtaining JWT token")
+            .withCause(e));
+  }
+
+  public static class Synchronous extends JwtCallCredentials {
+
+    private final SynchronousJwtTokenProvider jwtTokenProvider;
+
+    public Synchronous(SynchronousJwtTokenProvider jwtTokenProvider) {
+      this.jwtTokenProvider = jwtTokenProvider;
+    }
+
+    @Override
+    public void applyRequestMetadata(
+        RequestInfo requestInfo, Executor appExecutor, MetadataApplier applier) {
+      try {
+        applyToken(applier, jwtTokenProvider.get());
+      } catch (RuntimeException e) {
+        applyFailure(applier, e);
+      }
+    }
+  }
+
+  public static class Blocking extends JwtCallCredentials {
+
+    private final BlockingJwtTokenProvider jwtTokenProvider;
+
+    public Blocking(BlockingJwtTokenProvider jwtTokenProvider) {
+      this.jwtTokenProvider = jwtTokenProvider;
+    }
+
+    @Override
+    public void applyRequestMetadata(
+        RequestInfo requestInfo, Executor appExecutor, MetadataApplier applier) {
+      appExecutor.execute(
+          () -> {
+            try {
+              applyToken(applier, jwtTokenProvider.get());
+            } catch (RuntimeException e) {
+              applyFailure(applier, e);
+            }
+          });
+    }
+  }
+
+  public static class Asynchronous extends JwtCallCredentials {
+
+    private final AsyncJwtTokenProvider jwtTokenProvider;
+
+    public Asynchronous(AsyncJwtTokenProvider jwtTokenProvider) {
+      this.jwtTokenProvider = jwtTokenProvider;
+    }
+
+    @Override
+    public void applyRequestMetadata(
+        RequestInfo requestInfo, Executor appExecutor, MetadataApplier applier) {
+      jwtTokenProvider
+          .get()
+          .whenComplete(
+              (token, e) -> {
+                if (token != null) applyToken(applier, token);
+                else applyFailure(applier, e);
+              });
+    }
+  }
+}

core/src/main/java/com/avast/grpc/jwt/client/SynchronousJwtTokenProvider.java

@@ -0,0 +1,7 @@
+package com.avast.grpc.jwt.client;
+
+@FunctionalInterface
+public interface SynchronousJwtTokenProvider {
+  /* Gets encoded JWT token without blocking. */
+  String get();
+}

core/src/main/java/com/avast/grpc/jwt/server/JwtServerInterceptor.java

@@ -0,0 +1,51 @@
+package com.avast.grpc.jwt.server;
+
+import com.avast.grpc.jwt.Constants;
+import io.grpc.*;
+
+public class JwtServerInterceptor<T> implements ServerInterceptor {
+  public final io.grpc.Context.Key<T> AccessTokenContextKey = Context.key("AccessToken");
+
+  private static final String AUTH_HEADER_PREFIX = "Bearer ";
+
+  private final JwtTokenParser<T> tokenParser;
+
+  public JwtServerInterceptor(JwtTokenParser<T> tokenParser) {
+    this.tokenParser = tokenParser;
+  }
+
+  @Override
+  public <ReqT, RespT> ServerCall.Listener<ReqT> interceptCall(
+      ServerCall<ReqT, RespT> call, Metadata headers, ServerCallHandler<ReqT, RespT> next) {
+    String authHeader = headers.get(Constants.AuthorizationMetadataKey);
+    if (authHeader == null) {
+      call.close(
+          Status.UNAUTHENTICATED.withDescription(
+              Constants.AuthorizationMetadataKey.name() + " header not found"),
+          new Metadata());
+      return new ServerCall.Listener<ReqT>() {};
+    }
+    if (!authHeader.startsWith(AUTH_HEADER_PREFIX)) {
+      call.close(
+          Status.UNAUTHENTICATED.withDescription(
+              Constants.AuthorizationMetadataKey.name()
+                  + " header does not start with "
+                  + AUTH_HEADER_PREFIX),
+          new Metadata());
+      return new ServerCall.Listener<ReqT>() {};
+    }
+    try {
+      T token = tokenParser.parseToValid(authHeader.substring(AUTH_HEADER_PREFIX.length()));
+      return Contexts.interceptCall(
+          Context.current().withValue(AccessTokenContextKey, token), call, headers, next);
+    } catch (Exception e) {
+      call.close(
+          Status.UNAUTHENTICATED.withDescription(
+              Constants.AuthorizationMetadataKey.name()
+                  + " header does not start with "
+                  + AUTH_HEADER_PREFIX),
+          new Metadata());
+      return new ServerCall.Listener<ReqT>() {};
+    }
+  }
+}

core/src/main/java/com/avast/grpc/jwt/server/JwtTokenParser.java

@@ -0,0 +1,8 @@
+package com.avast.grpc.jwt.server;
+
+@FunctionalInterface
+public interface JwtTokenParser<T> {
+
+  /** Get valid JWT token, throws an exception otherwise. */
+  T parseToValid(String jwtToken) throws Exception;
+}