What is gRPC

gRPC is a high-performance RPC framework implemented on top of HTTP/2. And also it is a CNCF (Cloud Native Computation Foundation) incubating project. You can find more details here.

Why you need a microgateway for gRPC

One of the most important features in gRPC is that you can generate your client and server stubs in so many different programming languages. But if the gRPC service developer needs some advanced features like authentication, authorization, and rate-limiting, it is required to put a considerable effort. By using the wso2 microgateway, the service developer can focus on the actual service implementation rather than worrying about those features. The following features are provided by the wso2 microgateway.

Authentication
- The supported authentication schemes are JWT, Basic Auth and API Key.
Authorization
- Users can add scopes to the methods inside the service definition so that the gRPC clients only access those specific methods only if they are authorized.
Rate Limiting
- Rate limiting can be applied based on RPC method invocations per-method basis or per-service basis.
Single Source of Truth
- In gRPC, the .proto file containing the service definition acts as the single source of truth. Hence the configurations related to microgateway including endpoint configurations, authentication schemes, etc. need to be provided inside the gRPC service definition.

Please refer to the "Microgateway Extensions" segment below for more information.

Microgateway Extensions

To generate the microgateway for gRPC services, there is a set of extensions introduced which need to be added to the existing service .proto files inside the microgateway project. Those extensions are defined in a separate .proto file called "wso2_options.proto" which is defined by the microgateway.

syntax = "proto3";
package wso2;

option java_package = "org.wso2.apimgt.gateway.cli.protobuf";
option java_outer_classname = "ExtensionHolder";

import "google/protobuf/descriptor.proto";

//service level extensions
extend google.protobuf.ServiceOptions {
  Endpoints production_endpoints = 50001;
  Endpoints sandbox_endpoints = 50002;
  repeated Security security = 50003;
  string throttling_tier = 50004;
}

//method level extensions
extend google.protobuf.MethodOptions {
  	string method_throttling_tier = 50006;
  	string method_scopes = 50007;
}

//to define endpoints
message Endpoints {
	repeated string url = 1;
	EndpointType type = 2;
}

enum EndpointType {
	DEFAULT = 0;
}

enum Security {
	NONE = 0;
	BASIC = 1;
	OAUTH2 = 2;
	JWT = 3;
	APIKEY = 4;
}

Service Extensions

Method Extensions

How to setup gRPC microgateway

Implement a gRPC server and a client.
Make sure to follow install and set up guide.
Create an API Microgateway project (e.g., grpc-helloworld-project).
Navigate to a preferred folder where you want to create the Microgateway project, and then run the following command.
Navigate to the directory <project-location>/grpc_definitions. Create a sub-directory inside. And then copy the .proto file/files of your project to that sub-directory preserving the directory structure. (In the protocol buffers context, the compiler should be able to compile the service .proto files without providing --proto-path parameter.) In our case, it is only required to copy the above mentioned .proto file. Then, the directory structure will appear as follows.
It is mandatory to customize the gRPC service definition .proto file/files with the predefined set of extensions. First, you need to add the specific import statement to allow wso2 microgateway specific extensions. To keep the example simple, only the production endpoint field and the security scheme is added. To add more functionalities like authorization and rate-limiting, please refer to the above section on extensions. (Please note that you do not need to copy the wso2_options.proto file to the grpc_definitions directory as it is internally handled by the toolkit).
Build the microgateway project.
Run the microgateway project. (Microgateway Runtime is used here. Please refer installation prerequisites for more information).
For the provided sample implementation, you need to obtain an API-KEY token.
Finally, you can start your gRPC server and gRPC client with the acquired token.