gRPC-Web

Note

This feature is experimental.

The Java/Scala API’s to enable this feature may still change in further versions of Pekko gRPC, and future versions of this feature may not work with services generated with older versions of Pekko gRPC.

There may be missing features and bugs in the current implementation. If you encounter any, you are welcome to share a reproducer in our issue tracker.

gRPC cannot be used directly from the browser because of limitations on the amount of control the Javascript code has on the behavior of the browser.

The gRPC-Web protocol was designed to be usable from a browser, but be easily translatable into native gRPC calls.

The most common deployment model of gRPC-Web is to use a proxy such as Envoy to translate between the gRPC-Web frontend and a native gRPC back-end. This is a great choice with Pekko gRPC services.

However, in some situations it may be operationally simpler if your service supports gRPC-Web directly. This is now possible with Pekko gRPC as well.

To serve a gRPC service with Pekko gRPC, it is recommended to serve the native gRPC protocol on a different port than gRPC-Web, as the two protocols will likely require a different security story. You can use WebHandler.grpcWebHandlerWebHandler.grpcWebHandler to serve your gRPC-Web endpoint with basic CORS infrastructure in place. To use CORS, you will need to add the pekko-http-cors dependency to your project:

sbt
libraryDependencies += "org.apache.pekko" %% "pekko-http-cors" % "2.0.0"
Maven
<properties>
  <scala.binary.version>2.13</scala.binary.version>
</properties>
<dependencies>
  <dependency>
    <groupId>org.apache.pekko</groupId>
    <artifactId>pekko-http-cors_${scala.binary.version}</artifactId>
    <version>2.0.0</version>
  </dependency>
</dependencies>
Gradle
def versions = [
  ScalaBinary: "2.13"
]
dependencies {
  implementation "org.apache.pekko:pekko-http-cors_${versions.ScalaBinary}:2.0.0"
}

And then serve the handlers with WebHandler.grpcWebHandlerWebHandler.grpcWebHandler like this:

Scala
sourceimport org.apache.pekko.grpc.scaladsl.WebHandler

val grpcWebServiceHandlers = WebHandler.grpcWebHandler(greeterService, echoService)

Http()
  .newServerAt("127.0.0.1", 8081)
  .bind(grpcWebServiceHandlers)
Java
sourceimport org.apache.pekko.grpc.javadsl.WebHandler;

Function<HttpRequest, CompletionStage<HttpResponse>> grpcWebServiceHandlers =
    WebHandler.grpcWebHandler(List.of(greeterService, echoService), sys, mat);

Http.get(sys)
    .newServerAt("127.0.0.1", 8090)
    .bind(grpcWebServiceHandlers)

CORS and credentials

WebHandler.defaultCorsSettings allows any origin. Allowing credentials as well would let a browser send cookies and HTTP authentication on a cross-origin call to your service, and let the calling page read the response. For a service authenticated that way, any web page your users visit could act as them — a CSRF vector.

So while the origins are unrestricted, the handler drops the credentials permission: it answers with Access-Control-Allow-Origin: * and no Access-Control-Allow-Credentials, and browsers withhold cookies on cross-origin calls.

If your gRPC-Web clients need credentials, restrict the origins that may use them. The credentials permission is kept for restricted origins:

Scala
```scala import org.apache.pekko.http.cors.scaladsl.model.HttpOriginMatcher import org.apache.pekko.http.scaladsl.model.headers.HttpOrigin

implicit val corsSettings: CorsSettings = WebHandler.defaultCorsSettings .withAllowedOrigins(HttpOriginMatcher(HttpOrigin("https://example.com"))) ```

Java
CorsSettings corsSettings = WebHandler.defaultCorsSettings()
    .withAllowedOrigins(HttpOriginMatcher.create(HttpOrigin.parse("https://example.com")));
Warning

Pekko gRPC 1.x allowed credentials from any origin. To keep that behaviour, set:

pekko.grpc.server.grpc-web {
  allow-credentials-from-any-origin = true
}

A warning is then logged for each handler created while the origins are unrestricted. Prefer restricting the origins instead.

reference.conf
sourcepekko.grpc.server.grpc-web {
  # Whether `WebHandler.defaultCorsSettings` may send `Access-Control-Allow-Credentials: true`
  # together with an origin the caller did not restrict.
  #
  # The default CORS settings allow any origin. Combined with credentials, that lets any web
  # page make credentialed cross-origin gRPC-Web calls to your service and read the responses,
  # which is a CSRF vector for anything authenticated by cookies or HTTP auth.
  #
  # false (the default) drops the credentials permission when the origins are unrestricted,
  # which makes browsers withhold cookies on cross-origin calls. Set it to true to keep the
  # 1.x behaviour; a warning is then logged while the unsafe combination is in effect.
  #
  # To use credentials safely, restrict the origins instead; the credentials permission is
  # kept, whatever this is set to, once the origins are restricted:
  #   WebHandler.defaultCorsSettings.withAllowedOrigins(HttpOriginMatcher(HttpOrigin("https://example.com")))
  allow-credentials-from-any-origin = false
}