examples: add an example for OAuth (grpc#10560)

examples/README.md

@@ -205,6 +205,8 @@ $ bazel-bin/hello-world-client
 
 - [JWT-based Authentication](example-jwt-auth)
 
+- [OAuth2-based Authentication](example-oauth)
+
 - [Pre-serialized messages](src/main/java/io/grpc/examples/preserialized)
 
 ## Unit test examples

examples/example-oauth/README.md

@@ -0,0 +1,73 @@
+Authentication Example
+==============================================
+
+This example illustrates a simple OAuth2-based authentication implementation in gRPC using
+ server interceptor. It uses the Google OAuth2 library since it already has the OAuth2
+semantics which makes it easy to illustrate the OAuth2 flow. The example creates an OAuth2
+credentials using the library and converts it to gRPC CallCredentials. However, you may
+use your own OAuth2 implementation, so use of Google OAuth2 library is not necessary.
+
+The example requires grpc-java to be pre-built. Using a release tag will download the relevant binaries
+from a maven repository. But if you need the latest SNAPSHOT binaries you will need to follow
+[COMPILING](../../COMPILING.md) to build these.
+
+The source code is [here](src/main/java/io/grpc/examples/oauth). 
+To build the example, run in this directory:
+```
+$ ../gradlew installDist
+```
+The build creates scripts `auth-server` and `auth-client` in the `build/install/example-oauth/bin/` directory
+which can be used to run this example. The example requires the server to be running before starting the
+client.
+
+Running auth-server is similar to the normal hello world example and there are no arguments to supply:
+
+**auth-server**:
+
+The auth-server accepts optional argument for port on which the server should run:
+
+```text
+USAGE: auth-server [port]
+```
+
+The auth-client accepts optional arguments for server-host, server-port, user-name and client-id:
+
+**auth-client**:
+
+```text
+USAGE: auth-client [server-host [server-port [user-name [client-id]]]]
+```
+
+The `user-name` value is simply passed in the `HelloRequest` message as payload and the value of
+`client-id` is included in the OAuth2 access token passed in the metadata header.
+
+
+#### How to run the example:
+
+```bash
+# Run the server:
+./build/install/example-oauth/bin/auth-server 50051
+# In another terminal run the client
+./build/install/example-oauth/bin/auth-client localhost 50051 userA clientB
+```
+
+That's it! The client will show the user-name reflected back in the message from the server as follows:
+```
+INFO: Greeting: Hello, userA
+```
+
+And on the server side you will see the message with the client's identifier:
+```
+Processing request from clientB
+```
+
+## Maven
+
+If you prefer to use Maven follow these [steps](../README.md#maven). You can run the example as follows:
+
+```
+$ # Run the server
+$ mvn exec:java -Dexec.mainClass=io.grpc.examples.oauth.AuthServer -Dexec.args="50051"
+$ # In another terminal run the client
+$ mvn exec:java -Dexec.mainClass=io.grpc.examples.oauth.AuthClient -Dexec.args="localhost 50051 userA clientB"
+```

examples/example-oauth/build.gradle

@@ -0,0 +1,87 @@
+plugins {
+    // Provide convenience executables for trying out the examples.
+    id 'application'
+    id 'com.google.protobuf' version '0.9.4'
+    // Generate IntelliJ IDEA's .idea & .iml project files
+    id 'idea'
+}
+
+repositories {
+    maven { // The google mirror is less flaky than mavenCentral()
+        url "https://maven-central.storage-download.googleapis.com/maven2/"
+    }
+    mavenLocal()
+}
+
+java {
+    sourceCompatibility = JavaVersion.VERSION_1_8
+    targetCompatibility = JavaVersion.VERSION_1_8
+}
+
+// IMPORTANT: You probably want the non-SNAPSHOT version of gRPC. Make sure you
+// are looking at a tagged version of the example and not "master"!
+
+// Feel free to delete the comment at the next line. It is just for safely
+// updating the version in our release process.
+def grpcVersion = '1.59.0-SNAPSHOT' // CURRENT_GRPC_VERSION
+def protobufVersion = '3.24.0'
+def protocVersion = protobufVersion
+
+dependencies {
+    implementation "io.grpc:grpc-protobuf:${grpcVersion}"
+    implementation "io.grpc:grpc-stub:${grpcVersion}"
+    implementation "io.grpc:grpc-auth:${grpcVersion}"
+    implementation "com.google.auth:google-auth-library-oauth2-http:1.18.0"
+
+    compileOnly "org.apache.tomcat:annotations-api:6.0.53"
+
+    runtimeOnly "io.grpc:grpc-netty-shaded:${grpcVersion}"
+
+    testImplementation "io.grpc:grpc-testing:${grpcVersion}"
+    testImplementation "junit:junit:4.13.2"
+    testImplementation "org.mockito:mockito-core:3.4.0"
+}
+
+protobuf {
+    protoc { artifact = "com.google.protobuf:protoc:${protocVersion}" }
+    plugins {
+        grpc { artifact = "io.grpc:protoc-gen-grpc-java:${grpcVersion}" }
+    }
+    generateProtoTasks {
+        all()*.plugins { grpc {} }
+    }
+}
+
+// Inform IDEs like IntelliJ IDEA, Eclipse or NetBeans about the generated code.
+sourceSets {
+    main {
+        java {
+            srcDirs 'build/generated/source/proto/main/grpc'
+            srcDirs 'build/generated/source/proto/main/java'
+        }
+    }
+}
+
+startScripts.enabled = false
+
+task hellowWorldOauthServer(type: CreateStartScripts) {
+    mainClass = 'io.grpc.examples.oauth.AuthServer'
+    applicationName = 'auth-server'
+    outputDir = new File(project.buildDir, 'tmp/scripts/' + name)
+    classpath = startScripts.classpath
+}
+
+task hellowWorldOauthClient(type: CreateStartScripts) {
+    mainClass = 'io.grpc.examples.oauth.AuthClient'
+    applicationName = 'auth-client'
+    outputDir = new File(project.buildDir, 'tmp/scripts/' + name)
+    classpath = startScripts.classpath
+}
+
+application {
+    applicationDistribution.into('bin') {
+        from(hellowWorldOauthServer)
+        from(hellowWorldOauthClient)
+        fileMode = 0755
+    }
+}

examples/example-oauth/gradle/wrapper/gradle-wrapper.properties

@@ -0,0 +1,5 @@
+distributionBase=GRADLE_USER_HOME
+distributionPath=wrapper/dists
+distributionUrl=https\://services.gradle.org/distributions/gradle-7.5.1-bin.zip
+zipStoreBase=GRADLE_USER_HOME
+zipStorePath=wrapper/dists