{"id":27130840,"url":"https://github.com/majusko/grpc-jwt-spring-boot-starter","last_synced_at":"2025-04-07T20:18:55.598Z","repository":{"id":36012753,"uuid":"219345485","full_name":"majusko/grpc-jwt-spring-boot-starter","owner":"majusko","description":"Spring boot starter for gRPC framework with JWT authorization","archived":false,"fork":false,"pushed_at":"2023-02-28T06:58:10.000Z","size":191,"stargazers_count":39,"open_issues_count":13,"forks_count":7,"subscribers_count":3,"default_branch":"master","last_synced_at":"2025-03-30T15:36:07.671Z","etag":null,"topics":["annotations","autowire","grpc","grpc-framework","grpc-java","grpc-library","interceptor","java","java-library","jwt","jwt-authorization","microservices","ownerfield","proto","protobuf","signing","spring-boot","springboot-starter"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/majusko.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2019-11-03T18:22:08.000Z","updated_at":"2024-05-31T09:58:43.000Z","dependencies_parsed_at":"2025-03-30T15:40:53.135Z","dependency_job_id":null,"html_url":"https://github.com/majusko/grpc-jwt-spring-boot-starter","commit_stats":null,"previous_names":[],"tags_count":19,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majusko%2Fgrpc-jwt-spring-boot-starter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majusko%2Fgrpc-jwt-spring-boot-starter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majusko%2Fgrpc-jwt-spring-boot-starter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/majusko%2Fgrpc-jwt-spring-boot-starter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/majusko","download_url":"https://codeload.github.com/majusko/grpc-jwt-spring-boot-starter/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":247721897,"owners_count":20985084,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["annotations","autowire","grpc","grpc-framework","grpc-java","grpc-library","interceptor","java","java-library","jwt","jwt-authorization","microservices","ownerfield","proto","protobuf","signing","spring-boot","springboot-starter"],"created_at":"2025-04-07T20:18:54.969Z","updated_at":"2025-04-07T20:18:55.583Z","avatar_url":"https://github.com/majusko.png","language":"Java","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Spring boot starter for [gRPC framework](https://grpc.io/) with [JWT authorization](https://jwt.io/) - gRPC Java JWT\n\n[![Maven Central](https://maven-badges.herokuapp.com/maven-central/io.github.majusko/grpc-jwt-spring-boot-starter/badge.svg)](https://search.maven.org/search?q=g:io.github.majusko)\n[![Release](https://jitpack.io/v/majusko/grpc-jwt-spring-boot-starter.svg)](https://jitpack.io/#majusko/grpc-jwt-spring-boot-starter)\n[![Build Status](https://travis-ci.com/majusko/grpc-jwt-spring-boot-starter.svg?branch=master)](https://travis-ci.com/majusko/grpc-jwt-spring-boot-starter)\n[![Test Coverage](https://codecov.io/gh/majusko/grpc-jwt-spring-boot-starter/branch/master/graph/badge.svg)](https://codecov.io/gh/majusko/grpc-jwt-spring-boot-starter/branch/master)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT) [![Join the chat at https://gitter.im/grpc-jwt-spring-boot-starter/community](https://badges.gitter.im/grpc-jwt-spring-boot-starter/community.svg)](https://gitter.im/grpc-jwt-spring-boot-starter/community?utm_source=badge\u0026utm_medium=badge\u0026utm_campaign=pr-badge\u0026utm_content=badge)\n\nExtending great [gRPC library](https://github.com/LogNet/grpc-spring-boot-starter) with Auth module. Easy implementation using a simple annotations similar to ones used in Spring Security module.\n\n## Quick Start\n(Try example project: [gRPC example project](https://github.com/majusko/grpc-example) in Kotlin.)\n\nSimple start consist only from 3 simple steps.\n\n(If you never used [gRPC library](https://github.com/LogNet/grpc-spring-boot-starter) before, have a look on this [basic setup](https://github.com/LogNet/grpc-spring-boot-starter#4-show-case) first.)\n\n#### 1. Add Maven dependency\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003eio.github.majusko\u003c/groupId\u003e\n  \u003cartifactId\u003egrpc-jwt-spring-boot-starter\u003c/artifactId\u003e\n  \u003cversion\u003e${version}\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\n#### 2. Add `@Allow` annotation to your service method\n\nAll you need to do is to annotate your method in the service implementation.\n\n```java\n@GRpcService\npublic class ExampleServiceImpl extends ExampleServiceGrpc.ExampleServiceImplBase {\n\n    @Allow(roles = GrpcRole.INTERNAL)\n    public void getExample(GetExample request, StreamObserver\u003cEmpty\u003e response) {\n        //...\n    }\n}\n```\n\n#### 3. Add interceptor to client\n\nJust autowire already prepared `AuthClientInterceptor` bean and intercept your client. It will inject the internal token to every request by default.\n\n```java\n@Service\npublic class ExampleClient {\n\n    @Autowired\n    private AuthClientInterceptor authClientInterceptor;\n\n    public void exampleRequest() {\n        final ManagedChannel channel = ManagedChannelBuilder.forTarget(target).usePlaintext().build();\n        final Channel interceptedChannel = ClientInterceptors.intercept(channel,authClientInterceptor);\n        final ExampleServiceBlockingStub stub = ExampleServiceGrpc.newBlockingStub(interceptedChannel);\n        \n        stub.getExample(GetExample.newBuilder().build());\n    }\n}\n```\n\n## Documentation\n\n### 0. Basic setup of gRPC\nUseful only in case you never heard about [gRPC library from LogNet](https://github.com/LogNet/grpc-spring-boot-starter).\nYou can find there a nice [show case](https://github.com/LogNet/grpc-spring-boot-starter#4-show-case) too.\n\n#### 0.1 Service implementation\n\nThe service definition from .proto file looks like this \n\n```proto\nservice ExampleService {\n    rpc GetExample (GetExample) returns (Empty) {};\n}\n\nmessage Empty {}\nmessage GetExample {\n    string ownerField = 1;\n}\n```\n\n#### 0.2 Service implementation\n\nAll you need to do is to annotate your service implementation with `GRpcService`\n\n```java\n@GRpcService\npublic class ExampleServiceImpl extends ExampleServiceGrpc.ExampleServiceImplBase {\n\n    public void getExample(GetExample request, StreamObserver\u003cEmpty\u003e response) {\n        response.onNext(Empty.newBuilder().build());\n        response.onCompleted();\n    }\n}\n```\n\n### 1. Configuration\n\nYou can use `application.properties` to override the default configuration. \n\n* `grpc.jwt.algorithm` -\u003e Algorithm used for signing the JWT token. Default: `HmacSHA256`\n* `grpc.jwt.secret` -\u003e String used as a secret to sign the JWT token. Default: `default`\n* `grpc.jwt.expirationSec` -\u003e Number of seconds needed to token becoming expired. Default: `3600`\n\n```\ngrpc.jwt.algorithm=HmacSHA256\ngrpc.jwt.secret=secret\ngrpc.jwt.expirationSec=3600\n```\n\n### 2. Annotations\n\nWe know 2 types of annotation: `@Allow` and `@Expose`\n\n#### `@Allow` \n* `roles` -\u003e Algorithm used for signing the JWT token. Default: `HmacSHA256`\n* `ownerField` -\u003e 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. \n \n \n _**Example use case of `ownerField`**: Imagine, you want to list purchased orders of some user. \n You might want to reuse the exact same API for back-office and also for that particular user who created the orders.\n With `ownerField` you can check for the owner and also for some role if owner ownerField in JWT token is different._\n\n#### `@Exposed` \n* `environments` List of environments (Spring Profiles) where you can access the gRPC without checking for owner or roles.\nUse case: Debug endpoint for the client/front-end development team.\n\n```java\n@GRpcService\npublic class ExampleServiceImpl extends ExampleServiceGrpc.ExampleServiceImplBase {\n\n    @Allow(ownerField=\"ownerField\", roles = GrpcRole.INTERNAL)\n    @Exposed(environments={\"dev\",\"qa\"})\n    public void getExample(GetExample request, StreamObserver\u003cEmpty\u003e response) {\n        //...\n    }\n}\n```\n\n### Token generation\n\nYou 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.\n\n```java\n@Service\npublic class SomeClass {\n\n    private final static String ADMIN = \"admin\";\n\n    @Autowired\n    private JwtService jwtService;\n\n    public void someMethod() {\n        final JwtData data = new JwtData(\"user-id-12345\", new HashSet\u003c\u003e(ADMIN));\n\n        final String token = jwtService.generate(data);\n    }\n}\n```\n\n### Making requests\n\nWe have two types of usages for client.\n\n1. Inter-service communication.\n2. User communication.\n\n#### 1. Client for inter-service communication only.\n\n* Autowire `AuthClientInterceptor` to your service.\n* Register your interceptor with native `ClientInterceptors` class.\n* Call request from gRPC generated stub.\n\n```java\n@Service\npublic class SomeClass {\n\n    @Autowired\n    private AuthClientInterceptor authClientInterceptor;\n\n    public void customTokenRequest() {\n\n        final ManagedChannel channel = ManagedChannelBuilder.forTarget(target).usePlaintext().build();\n        final Channel interceptedChannel = ClientInterceptors.intercept(channel,authClientInterceptor);\n        final ExampleServiceBlockingStub stub = ExampleServiceGrpc.newBlockingStub(interceptedChannel);\n\n        final Empty response = stub.getExample(GetExample.newBuilder().setUserId(\"user-id-jr834fh\").build());\n    }\n}\n```\n\n#### 2. Client for custom token communication.\n\n* Add your token generated with `JwtService` to gRPC header with `GrpcHeader.AUTHORIZATION`\n* Call request from gRPC generated stub.\n\n```java\n@Service\npublic class SomeClass {\n\n    public void customTokenRequest() {\n\n        final Metadata header = new Metadata();\n        header.put(GrpcHeader.AUTHORIZATION, \"jwt-token-r348hf34hf43f93\");\n\n        final ManagedChannel channel = ManagedChannelBuilder.forTarget(target).usePlaintext().build();\n        final ExampleServiceBlockingStub stub = ExampleServiceGrpc.newBlockingStub(channel);\n        final ExampleServiceBlockingStub stubWithHeaders = MetadataUtils.attachHeaders(stub, header);\n\n        final Empty response = stub.getExample(GetExample.newBuilder().setUserId(\"user-id-jr834fh\").build());\n    }\n}\n```\n\n### Tests\n\nThe library is fully covered with integration tests which are also very useful as a usage example.\n\n`GrpcJwtSpringBootStarterApplicationTest`\n\n## Contributing\n\nAll contributors are welcome. If you never contributed to the open-source, start with reading the [Github Flow](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/github-flow).\n\n1. Create an [issue](https://help.github.com/en/github/managing-your-work-on-github/about-issues)\n2. Create a [pull request](https://help.github.com/en/github/collaborating-with-issues-and-pull-requests/about-pull-requests) with reference to the issue\n3. Rest and enjoy the great feeling of being a contributor.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajusko%2Fgrpc-jwt-spring-boot-starter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmajusko%2Fgrpc-jwt-spring-boot-starter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmajusko%2Fgrpc-jwt-spring-boot-starter/lists"}