leonardowiest / grpc-java-jwt

JWT based authentication for gRPC-Java.

gRPC Java JWT support

Library that helps with authenticated communication in gRPC-Java based applications. It uses JSON Web Token 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.

<dependency>
  <groupId>com.avast.grpc.jwt</groupId>
  <artifactId>grpc-java-jwt</artifactId>
  <version>$latestVersion</version>
</dependency>

compile "com.avast.grpc.jwt:grpc-java-jwt:$latestVersion"

This base library contains a code that is not tied to any specific JWT implementation. So it requires instances of JwtTokenProvider interface (for client) and JwtTokenParser (for server) to work.

Keycloak support

There are implementations of the core interfaces for Keycloak.

<dependency>
  <groupId>com.avast.grpc.jwt</groupId>
  <artifactId>grpc-java-jwt-keycloak</artifactId>
  <version>$latestVersion</version>
</dependency>

compile "com.avast.grpc.jwt:grpc-java-jwt-keycloak:$latestVersion"

Configuration defaults can be found here. It uses HOCON and Lightbend Config.

Client usage

This ensures that each call contains Authorization header with Bearer prefixed Keycloak access token (as JWT).

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.

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 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 - 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 requires an instance of JwtTokenParser - 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 usingCallCredentials. So you can call applier.apply() method on any thread.
2. Our ServerInterceptor implementation handles it correctly.