JarCastingSpring boot starter for gRPC framework with JWT authorization - gRPC Java JWT
Extending great gRPC library with Auth module. Easy implementation using a simple annotations similar to ones used in Spring Security module.
Quick Start
(Try example project: gRPC example project in Kotlin.)
Simple start consist only from 3 simple steps.
(If you never used gRPC library before, have a look on this basic setup first.)
1. Add Maven dependency
<dependency>
<groupId>io.github.majusko</groupId>
<artifactId>grpc-jwt-spring-boot-starter</artifactId>
<version>${version}</version>
</dependency>
2. Add @Allow annotation to your service method
All you need to do is to annotate your method in the service implementation.
@GRpcService
public class ExampleServiceImpl extends ExampleServiceGrpc.ExampleServiceImplBase {
@Allow(roles = GrpcRole.INTERNAL)
public void getExample(GetExample request, StreamObserver<Empty> response) {
//...
}
}
3. Add interceptor to client
Just autowire already prepared AuthClientInterceptor bean and intercept your client. It will inject the internal token to every request by default.
@Service
public class ExampleClient {
@Autowired
private AuthClientInterceptor authClientInterceptor;
public void exampleRequest() {
final ManagedChannel channel = ManagedChannelBuilder.forTarget(target).usePlaintext().build();
final Channel interceptedChannel = ClientInterceptors.intercept(channel,authClientInterceptor);
final ExampleServiceBlockingStub stub = ExampleServiceGrpc.newBlockingStub(interceptedChannel);
stub.getExample(GetExample.newBuilder().build());
}
}
Documentation
0. Basic setup of gRPC
Useful only in case you never heard about gRPC library from LogNet. You can find there a nice show case too.
0.1 Service implementation
The service definition from .proto file looks like this
service ExampleService {
rpc GetExample (GetExample) returns (Empty) {};
}
message Empty {}
message GetExample {
string ownerField = 1;
}
0.2 Service implementation
All you need to do is to annotate your service implementation with GRpcService
@GRpcService
public class ExampleServiceImpl extends ExampleServiceGrpc.ExampleServiceImplBase {
public void getExample(GetExample request, StreamObserver<Empty> response) {
response.onNext(Empty.newBuilder().build());
response.onCompleted();
}
}
1. Configuration
You can use application.properties to override the default configuration.
grpc.jwt.algorithm-> Algorithm used for signing the JWT token. Default:HmacSHA256grpc.jwt.secret-> String used as a secret to sign the JWT token. Default:defaultgrpc.jwt.expirationSec-> Number of seconds needed to token becoming expired. Default:3600
grpc.jwt.algorithm=HmacSHA256
grpc.jwt.secret=secret
grpc.jwt.expirationSec=3600
2. Annotations
We know 2 types of annotation: @Allow and @Expose
@Allow
roles-> Algorithm used for signing the JWT token. Default:HmacSHA256ownerField-> Example:ownerField. Optional field. Your request will be parsed and if the mentioned field is found, it will compare equality with JWT token subject(e.g.: ownerField). By this comparison, you can be sure that any operation with that field is made by the owner of the token. If the fields don't match and data are owned by another user, specified roles will be checked after.
Example use case of ownerField: Imagine, you want to list purchased orders of some user. You might want to reuse the exact same API for back-office and also for that particular user who created the orders. With ownerField you can check for the owner and also for some role if owner ownerField in JWT token is different.
@Exposed
environmentsList of environments (Spring Profiles) where you can access the gRPC without checking for owner or roles. Use case: Debug endpoint for the client/front-end development team.
@GRpcService
public class ExampleServiceImpl extends ExampleServiceGrpc.ExampleServiceImplBase {
@Allow(ownerField="ownerField", roles = GrpcRole.INTERNAL)
@Exposed(environments={"dev","qa"})
public void getExample(GetExample request, StreamObserver<Empty> response) {
//...
}
}
Token generation
You will need to generate tokens for your users or clients. You might want to specify special roles for each user and also service method. You can use the JwtService for simple and performing usage.
@Service
public class SomeClass {
private final static String ADMIN = "admin";
@Autowired
private JwtService jwtService;
public void someMethod() {
final JwtData data = new JwtData("user-id-12345", new HashSet<>(ADMIN));
final String token = jwtService.generate(data);
}
}
Making requests
We have two types of usages for client.
- Inter-service communication.
- User communication.
1. Client for inter-service communication only.
- Autowire
AuthClientInterceptorto your service. - Register your interceptor with native
ClientInterceptorsclass. - Call request from gRPC generated stub.
@Service
public class SomeClass {
@Autowired
private AuthClientInterceptor authClientInterceptor;
public void customTokenRequest() {
final ManagedChannel channel = ManagedChannelBuilder.forTarget(target).usePlaintext().build();
final Channel interceptedChannel = ClientInterceptors.intercept(channel,authClientInterceptor);
final ExampleServiceBlockingStub stub = ExampleServiceGrpc.newBlockingStub(interceptedChannel);
final Empty response = stub.getExample(GetExample.newBuilder().setUserId("user-id-jr834fh").build());
}
}
2. Client for custom token communication.
- Add your token generated with
JwtServiceto gRPC header withGrpcHeader.AUTHORIZATION - Call request from gRPC generated stub.
@Service
public class SomeClass {
public void customTokenRequest() {
final Metadata header = new Metadata();
header.put(GrpcHeader.AUTHORIZATION, "jwt-token-r348hf34hf43f93");
final ManagedChannel channel = ManagedChannelBuilder.forTarget(target).usePlaintext().build();
final ExampleServiceBlockingStub stub = ExampleServiceGrpc.newBlockingStub(channel);
final ExampleServiceBlockingStub stubWithHeaders = MetadataUtils.attachHeaders(stub, header);
final Empty response = stub.getExample(GetExample.newBuilder().setUserId("user-id-jr834fh").build());
}
}
Tests
The library is fully covered with integration tests which are also very useful as a usage example.
GrpcJwtSpringBootStarterApplicationTest
Contributing
All contributors are welcome. If you never contributed to the open-source, start with reading the Github Flow.
- Create an issue
- Create a pull request with reference to the issue
- Rest and enjoy the great feeling of being a contributor.