grpc
/
grpc-experiments
mirror of https://github.com/grpc/grpc-experiments.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #110 from murgatroid99/node_auth_info 

Added Node auth example
This commit is contained in:
Abhishek Kumar 2015-02-26 08:53:00 -08:00
parent ad232444df 537dadbc0d
commit a2da916923
1 changed files with 46 additions and 25 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

71
grpc-auth-support.md
View File

@ -1,28 +1,28 @@
#gRPC Authentication support #gRPC Authentication support
gRPC is designed to plug-in a number of authentication mechanisms. We provide an overview 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 of the various auth mechanisms supported, discuss the API and demonstrate usage through
code examples, and conclude with a discussion of extensibility. code examples, and conclude with a discussion of extensibility.
###SSL/TLS ###SSL/TLS
gRPC has SSL/TLS integration and promotes the use of SSL/TLS to authenticate the server, 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 and encrypt all the data exchanged between the client and the server. Optional
mechanisms are available for clients to provide certificates to accomplish mutual mechanisms are available for clients to provide certificates to accomplish mutual
authentication. authentication.
###OAuth 2.0 ###OAuth 2.0
gRPC provides a generic mechanism (described below) to attach metadata to requests 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 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 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 accessing Google APIs through gRPC is provided for certain auth flows, demonstrated
through code examples below. through code examples below.
###API ###API
To reduce complexity and minimize API clutter, gRPC works with a unified concept of To reduce complexity and minimize API clutter, gRPC works with a unified concept of
a Credentials object. Users construct gRPC credentials using corresponding bootstrap a Credentials object. Users construct gRPC credentials using corresponding bootstrap
credentials (e.g., SSL client certs or Service Account Keys), and use the 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 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 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 handshake with the server, or uses the credential to generate and attach Access
Tokens to each request being made on the channel. 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. 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 // Create the credentials object by providing service account key in constructor
std::unique_ptr<Credentials> creds = CredentialsFactory::SslCredentials(ssl_opts); std::unique_ptr<Credentials> creds = CredentialsFactory::SslCredentials(ssl_opts);
// Create a channel using the credentials created in the previous step // Create a channel using the credentials created in the previous step
std::shared_ptr<ChannelInterface> channel = CreateChannel(server_name, creds, channel_args); std::shared_ptr<ChannelInterface> channel = CreateChannel(server_name, creds, channel_args);
// Create a stub on the channel // Create a stub on the channel
std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(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); grpc::Status s = stub->sayHello(&context, *request, response);
``` ```
For advanced use cases such as modifying the root CA or using client certs, For advanced use cases such as modifying the root CA or using client certs,
the corresponding options can be set in the SslCredentialsOptions parameter the corresponding options can be set in the SslCredentialsOptions parameter
passed to the factory method. passed to the factory method.
@ -61,11 +61,11 @@ std::unique_ptr<Greeter::Stub> stub(Greeter::NewStub(channel));
grpc::Status s = stub->sayHello(&context, *request, response); 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 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 service account’s private keys are loaded from the file named in the environment
variable `GOOGLE_APPLICATION_CREDENTIALS`. The 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. on the corresponding channel.
For applications running in GCE, a default service account and corresponding 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 Extending gRPC to support other authentication mechanisms
The gRPC protocol is designed with a general mechanism for sending metadata 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 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 servers can send back metadata at the beginning and end of the RPC. This
provides a natural mechanism to support OAuth2 and other authentication provides a natural mechanism to support OAuth2 and other authentication
mechanisms that need attach bearer tokens to individual request. mechanisms that need attach bearer tokens to individual request.
In the simplest case, there is a single line of code required on the client 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 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 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. 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. 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 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, creds: creds,
update_metadata: authorization.updater_proc) 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));
});
```