diff options
| -rw-r--r-- | grpc-auth-support.md | 99 |
1 files changed, 40 insertions, 59 deletions
diff --git a/grpc-auth-support.md b/grpc-auth-support.md index 9cb9012e23..c8d2595c94 100644 --- a/grpc-auth-support.md +++ b/grpc-auth-support.md @@ -1,51 +1,51 @@ #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. +gRPC is designed to plug-in a number of authentication mechanisms. This document provides a quick overview +of the various auth mechanisms supported, discusses the API with some examples, and concludes with a discussion of extensibility. More documentation and examples are coming soon! + +## Supported auth mechanisms ###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 +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 +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 +##Authentication 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 +###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 +```cpp +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. +// 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 +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. @@ -53,7 +53,7 @@ passed to the factory method. gRPC applications can use a simple API to create a credential that works in various deployment scenarios. -``` +```cpp std::unique_ptr<Credentials> creds = CredentialsFactory::GoogleDefaultCredentials(); // 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); @@ -61,11 +61,11 @@ 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 +This credential works for applications using Service Accounts as well as for +applications running in [Google Compute Engine (GCE)](https://cloud.google.com/compute/). In the former case, the service account’s private keys are loaded from the file named in the environment variable `GOOGLE_APPLICATION_CREDENTIALS`. The -keys are used to generate bearer tokens that are attached to each outgoing RPC +keys are used 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 @@ -75,38 +75,40 @@ 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. +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 +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. -These authentication mechanisms will be available in all gRPC's supported languages. -The following sections demonstrate how authentication and authorization features described above appear in each language +## Examples -####SSL/TLS for server authentication and encryption (Ruby) +gRPC's supported authentication mechanisms will be available in _all gRPC's supported languages_. +The following sections show how authentication and authorization features described above appear in each language (more examples coming soon). + +###SSL/TLS for server authentication and encryption (Ruby) ```ruby -# Base case - No encryption +##### Base case - No encryption stub = Helloworld::Greeter::Stub.new('localhost:50051') ... -# With server authentication SSL/TLS +##### With server authentication SSL/TLS creds = GRPC::Core::Credentials.new(load_certs) # load_certs typically loads a CA roots file stub = Helloworld::Greeter::Stub.new('localhost:50051', creds: creds) ``` ###Authenticating with Google (Ruby) ```ruby -# Base case - No encryption/authorization +#### Base case - No encryption/authorization stub = Helloworld::Greeter::Stub.new('localhost:50051') ... -# Authenticating with Google +#### Authenticating with Google require 'googleauth' # from [googleauth](http://www.rubydoc.info/gems/googleauth/0.1.0) ... creds = GRPC::Core::Credentials.new(load_certs) # load_certs typically loads a CA roots file @@ -116,24 +118,3 @@ stub = Helloworld::Greeter::Stub.new('localhost:50051', creds: creds, update_metadata: authorization.updater_proc) ``` - -###Authenticating with Google (Node.js) - -```node -// Base case - No encryption/authorization -var stub = new helloworld.Greeter('localhost:50051'); -... -// Authenticating with Google -var GoogleAuth = require('google-auth-library'); // from https://www.npmjs.com/package/google-auth-library -... -var creds = grpc.Credentials.createSsl(load_certs); // load_certs typically loads a CA roots file -var scope = 'https://www.googleapis.com/auth/grpc-testing'; -(new GoogleAuth()).getApplicationDefault(function(err, auth) { - if (auth.createScopeRequired()) { - auth = auth.createScoped(scope); - } - var stub = new helloworld.Greeter('localhost:50051', - {credentials: creds}, - grpc.getGoogleAuthDelegate(auth)); -}); -``` |