diff options
| -rw-r--r-- | AUTH.md | 88 |
1 files changed, 88 insertions, 0 deletions
diff --git a/AUTH.md b/AUTH.md new file mode 100644 index 0000000000..9850b8b24e --- /dev/null +++ b/AUTH.md @@ -0,0 +1,88 @@ +#gRPC Authentication support + +gRPC is designed to plug-in a number of authentication mechanisms. We provide an overview +of the various auth mechanisms supported, discuss the API and demonstrate usage through +code examples, and conclude with a discussion of extensibility. + +###SSL/TLS +gRPC has SSL/TLS integration and promotes the use of SSL/TLS to authenticate the server, +and encrypt all the data exchanged between the client and the server. Optional +mechanisms are available for clients to provide certificates to accomplish mutual +authentication. + +###OAuth 2.0 +gRPC provides a generic mechanism (described below) to attach metadata to requests +and responses. This mechanism can be used to attach OAuth 2.0 Access Tokens to +RPCs being made at a client. Additional support for acquiring Access Tokens while +accessing Google APIs through gRPC is provided for certain auth flows, demonstrated +through code examples below. + +###API +To reduce complexity and minimize API clutter, gRPC works with a unified concept of +a Credentials object. Users construct gRPC credentials using corresponding bootstrap +credentials (e.g., SSL client certs or Service Account Keys), and use the +credentials while creating a gRPC channel to any server. Depending on the type of +credential supplied, the channel uses the credentials during the initial SSL/TLS +handshake with the server, or uses the credential to generate and attach Access +Tokens to each request being made on the channel. + +###Code Examples + +####SSL/TLS for server authentication and encryption +This is the simplest authentication scenario, where a client just wants to +authenticate the server and encrypt all data. + +``` +SslCredentialsOptions ssl_opts; // Options to override SSL params, empty by default +// Create the credentials object by providing service account key in constructor +std::unique_ptr<Credentials> creds = CredentialsFactory::SslCredentials(ssl_opts); +// Create a channel using the credentials created in the previous step +std::shared_ptr<ChannelInterface> channel = CreateChannel(server_name, creds, channel_args); +// Create a stub on the channel +std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel)); +// Make actual RPC calls on the stub. +grpc::Status s = stub->sayHello(&context, *request, response); +``` + +For advanced use cases such as modifying the root CA or using client certs, +the corresponding options can be set in the SslCredentialsOptions parameter +passed to the factory method. + + +###Authenticating with Google + +gRPC applications can use a simple API to create a credential that works in various deployment scenarios. + +``` +std::unique_ptr<Credentials> creds = CredentialsFactory::DefaultGoogleCredentials(); +// Create a channel, stub and make RPC calls (same as in the previous example) +std::shared_ptr<ChannelInterface> channel = CreateChannel(server_name, creds, channel_args); +std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel)); +grpc::Status s = stub->sayHello(&context, *request, response); +``` + +This credential works for applications using Service Accounts as well as for +applications running in Google Compute Engine (GCE). In the former case, the +service account’s private keys are expected in file located at [TODO: well +known file fath for service account keys] or in the file named in the environment +variable [TODO: add the env var name here]. The keys are used at run-time to +generate bearer tokens that are attached to each outgoing RPC on the +corresponding channel. + +For applications running in GCE, a default service account and corresponding +OAuth scopes can be configured during VM setup. At run-time, this credential +handles communication with the authentication systems to obtain OAuth2 access +tokens and attaches them to each outgoing RPC on the corresponding channel. +Extending gRPC to support other authentication mechanisms +The gRPC protocol is designed with a general mechanism for sending metadata +associated with RPC. Clients can send metadata at the beginning of an RPC and +servers can send back metadata at the beginning and end of the RPC. This +provides a natural mechanism to support OAuth2 and other authentication +mechanisms that need attach bearer tokens to individual request. + +In the simplest case, there is a single line of code required on the client +to add a specific token as metadata to an RPC and a corresponding access on +the server to retrieve this piece of metadata. The generation of the token +on the client side and its verification at the server can be done separately. + +A deeper integration can be achieved by plugging in a gRPC credentials implementation for any custom authentication mechanism that needs to attach per-request tokens. gRPC internals also allow switching out SSL/TLS with other encryption mechanisms. |