diff --git a/grpc-auth-support.md b/grpc-auth-support.md index 129fb3045fb..9cb9012e23e 100644 --- a/grpc-auth-support.md +++ b/grpc-auth-support.md @@ -1,28 +1,28 @@ #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 +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 +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 +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. @@ -33,19 +33,19 @@ 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 +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 creds = CredentialsFactory::SslCredentials(ssl_opts); // Create a channel using the credentials created in the previous step std::shared_ptr channel = CreateChannel(server_name, creds, channel_args); // Create a stub on the channel std::unique_ptr 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. @@ -61,11 +61,11 @@ std::unique_ptr stub(Greeter::NewStub(channel)); grpc::Status s = stub->sayHello(&context, *request, response); ``` -This credential works for applications using Service Accounts as well as for +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 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,16 +75,16 @@ 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. +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 @@ -116,3 +116,24 @@ 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)); +}); +```