blob: ba4971399830644aee115a7bf2a1b0247c812d02 [file] [log] [blame] [view]
Anar Sultanovb7859e72020-03-18 01:43:31 +01001Authentication Example
2==============================================
3
4This example illustrates a simple JWT-based authentication implementation in gRPC using
5 server interceptor. It uses the JJWT library to create and verify JSON Web Tokens (JWTs).
6
7The example requires grpc-java to be pre-built. Using a release tag will download the relevant binaries
8from a maven repository. But if you need the latest SNAPSHOT binaries you will need to follow
9[COMPILING](../../COMPILING.md) to build these.
10
11The source code is [here](src/main/java/io/grpc/examples/jwtauth).
12To build the example, run in this directory:
13```
14$ ../gradlew installDist
15```
16The build creates scripts `auth-server` and `auth-client` in the `build/install/example-jwt-auth/bin/` directory
17which can be used to run this example. The example requires the server to be running before starting the
18client.
19
20Running auth-server is similar to the normal hello world example and there are no arguments to supply:
21
22**auth-server**:
23
24The auth-server accepts optional argument for port on which the server should run:
25
26```text
27USAGE: auth-server [port]
28```
29
30The auth-client accepts optional arguments for server-host, server-port, user-name and client-id:
31
32**auth-client**:
33
34```text
35USAGE: auth-client [server-host [server-port [user-name [client-id]]]]
36```
37
38The `user-name` value is simply passed in the `HelloRequest` message as payload and the value of
39`client-id` is included in the JWT claims passed in the metadata header.
40
41
42#### How to run the example:
43
44```bash
45# Run the server:
46./build/install/example-jwt-auth/bin/auth-server 50051
47# In another terminal run the client
48./build/install/example-jwt-auth/bin/auth-client localhost 50051 userA clientB
49```
50
51That's it! The client will show the user-name reflected back in the message from the server as follows:
52```
53INFO: Greeting: Hello, userA
54```
55
56And on the server side you will see the message with the client's identifier:
57```
58Processing request from clientB
59```
60
61## Maven
62
63If you prefer to use Maven follow these [steps](../README.md#maven). You can run the example as follows:
64
65```
66$ # Run the server
67$ mvn exec:java -Dexec.mainClass=io.grpc.examples.authentication.AuthServer -Dexec.args="50051"
68$ # In another terminal run the client
69$ mvn exec:java -Dexec.mainClass=io.grpc.examples.authentication.AuthClient -Dexec.args="localhost 50051 userA clientB"
70```