mirror of https://github.com/grpc/grpc.git
Craig Tiller
9 years ago
commit
9efdc128ab
947 changed files with 22609 additions and 10690 deletions
@ -1,289 +0,0 @@ |
||||
#gRPC Authentication support |
||||
|
||||
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 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. |
||||
|
||||
###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. |
||||
|
||||
```cpp |
||||
SslCredentialsOptions ssl_opts; // Options to override SSL params, empty by default |
||||
// Create the credentials object by providing service account key in constructor |
||||
std::shared_ptr<ChannelCredentials> creds = SslCredentials(ssl_opts); |
||||
// Create a channel using the credentials created in the previous step |
||||
std::shared_ptr<Channel> channel = CreateChannel(server_name, creds); |
||||
// 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. |
||||
|
||||
```cpp |
||||
std::shared_ptr<ChannelCredentials> creds = GoogleDefaultCredentials(); |
||||
// Create a channel, stub and make RPC calls (same as in the previous example) |
||||
std::shared_ptr<Channel> channel = CreateChannel(server_name, creds); |
||||
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)](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 |
||||
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. |
||||
|
||||
## Examples |
||||
|
||||
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: more languages are coming soon. |
||||
|
||||
###SSL/TLS for server authentication and encryption (Ruby) |
||||
```ruby |
||||
# Base case - No encryption |
||||
stub = Helloworld::Greeter::Stub.new('localhost:50051') |
||||
... |
||||
|
||||
# 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) |
||||
``` |
||||
|
||||
###SSL/TLS for server authentication and encryption (C#) |
||||
```csharp |
||||
// Base case - No encryption |
||||
var channel = new Channel("localhost:50051"); |
||||
var client = new Greeter.GreeterClient(channel); |
||||
... |
||||
|
||||
// With server authentication SSL/TLS |
||||
var credentials = new SslCredentials(File.ReadAllText("ca.pem")); // Load a CA file |
||||
var channel = new Channel("localhost:50051", credentials); |
||||
var client = new Greeter.GreeterClient(channel); |
||||
``` |
||||
|
||||
###SSL/TLS for server authentication and encryption (Objective-C) |
||||
|
||||
The default for Objective-C is to use SSL/TLS, as that's the most common use case when accessing |
||||
remote APIs. |
||||
|
||||
```objective-c |
||||
// Base case - With server authentication SSL/TLS |
||||
HLWGreeter *client = [[HLWGreeter alloc] initWithHost:@"localhost:50051"]; |
||||
// Same as using @"https://localhost:50051". |
||||
... |
||||
|
||||
// No encryption |
||||
HLWGreeter *client = [[HLWGreeter alloc] initWithHost:@"http://localhost:50051"]; |
||||
// Specifying the HTTP scheme explicitly forces no encryption. |
||||
``` |
||||
|
||||
###SSL/TLS for server authentication and encryption (Python) |
||||
```python |
||||
# Base case - No encryption |
||||
stub = early_adopter_create_GreeterService_stub('localhost', 50051) |
||||
... |
||||
|
||||
# With server authentication SSL/TLS |
||||
stub = early_adopter_create_GreeterService_stub( |
||||
'localhost', 50051, secure=True, root_certificates=open('ca.pem').read()) |
||||
... |
||||
``` |
||||
n.b.: the beta API will look different |
||||
|
||||
###Authenticating with Google (Ruby) |
||||
```ruby |
||||
# Base case - No encryption/authorization |
||||
stub = Helloworld::Greeter::Stub.new('localhost:50051') |
||||
... |
||||
|
||||
# Authenticating with Google |
||||
require 'googleauth' # from http://www.rubydoc.info/gems/googleauth/0.1.0 |
||||
... |
||||
creds = GRPC::Core::Credentials.new(load_certs) # load_certs typically loads a CA roots file |
||||
scope = 'https://www.googleapis.com/auth/grpc-testing' |
||||
authorization = Google::Auth.get_application_default(scope) |
||||
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)); |
||||
}); |
||||
``` |
||||
|
||||
###Authenticating with Google (C#) |
||||
```csharp |
||||
// Base case - No encryption/authorization |
||||
var channel = new Channel("localhost:50051"); |
||||
var client = new Greeter.GreeterClient(channel); |
||||
... |
||||
|
||||
// Authenticating with Google |
||||
using Grpc.Auth; // from Grpc.Auth NuGet package |
||||
... |
||||
var credentials = new SslCredentials(File.ReadAllText("ca.pem")); // Load a CA file |
||||
var channel = new Channel("localhost:50051", credentials); |
||||
|
||||
string scope = "https://www.googleapis.com/auth/grpc-testing"; |
||||
var authorization = GoogleCredential.GetApplicationDefault(); |
||||
if (authorization.IsCreateScopedRequired) |
||||
{ |
||||
authorization = credential.CreateScoped(new[] { scope }); |
||||
} |
||||
var client = new Greeter.GreeterClient(channel, |
||||
new StubConfiguration(OAuth2InterceptorFactory.Create(credential))); |
||||
``` |
||||
|
||||
###Authenticating with Google (PHP) |
||||
```php |
||||
// Base case - No encryption/authorization |
||||
$client = new helloworld\GreeterClient( |
||||
new Grpc\BaseStub('localhost:50051', [])); |
||||
... |
||||
|
||||
// Authenticating with Google |
||||
// the environment variable "GOOGLE_APPLICATION_CREDENTIALS" needs to be set |
||||
$scope = "https://www.googleapis.com/auth/grpc-testing"; |
||||
$auth = Google\Auth\ApplicationDefaultCredentials::getCredentials($scope); |
||||
$opts = [ |
||||
'credentials' => Grpc\Credentials::createSsl(file_get_contents('ca.pem')); |
||||
'update_metadata' => $auth->getUpdateMetadataFunc(), |
||||
]; |
||||
|
||||
$client = new helloworld\GreeterClient( |
||||
new Grpc\BaseStub('localhost:50051', $opts)); |
||||
|
||||
``` |
||||
|
||||
###Authenticating with Google (Objective-C) |
||||
|
||||
This example uses the [Google iOS Sign-In library](https://developers.google.com/identity/sign-in/ios/), |
||||
but it's easily extrapolated to any other OAuth2 library. |
||||
|
||||
```objective-c |
||||
// Base case - No authentication |
||||
[client sayHelloWithRequest:request handler:^(HLWHelloReply *response, NSError *error) { |
||||
... |
||||
}]; |
||||
|
||||
... |
||||
|
||||
// Authenticating with Google |
||||
|
||||
// When signing the user in, ask her for the relevant scopes. |
||||
GIDSignIn.sharedInstance.scopes = @[@"https://www.googleapis.com/auth/grpc-testing"]; |
||||
|
||||
... |
||||
|
||||
#import <ProtoRPC/ProtoRPC.h> |
||||
|
||||
// Create a not-yet-started RPC. We want to set the request headers on this object before starting |
||||
// it. |
||||
ProtoRPC *call = |
||||
[client RPCToSayHelloWithRequest:request handler:^(HLWHelloReply *response, NSError *error) { |
||||
... |
||||
}]; |
||||
|
||||
// Set the access token to be used. |
||||
NSString *accessToken = GIDSignIn.sharedInstance.currentUser.authentication.accessToken; |
||||
call.requestMetadata[@"Authorization"] = [@"Bearer " stringByAppendingString:accessToken]}]; |
||||
|
||||
// Start the RPC. |
||||
[call start]; |
||||
``` |
||||
|
||||
You can see a working example app, with a more detailed explanation, [here](examples/objective-c/auth_sample). |
||||
|
||||
### Authenticating with Google (Python) |
||||
```python |
||||
# Base case - No encryption |
||||
stub = early_adopter_create_GreeterService_stub('localhost', 50051) |
||||
... |
||||
|
||||
# With server authentication SSL/TLS |
||||
import oauth2client.client |
||||
credentials = oauth2client.GoogleCredentials.get_application_default() |
||||
scope = 'https://www.googleapis.com/auth/grpc-testing' |
||||
scoped_credentials = credentials.create_scoped([scope]) |
||||
access_token = scoped_credentials.get_access_token().access_token |
||||
metadata_transformer = ( |
||||
lambda x: [('Authorization', 'Bearer {}'.format(access_token))]) |
||||
|
||||
stub = early_adopter_create_GreeterService_stub( |
||||
'localhost', 50051, secure=True, root_certificates=open('ca.pem').read(), |
||||
metadata_transformer=metadata_transformer) |
||||
... |
||||
``` |
||||
n.b.: the beta API will look different |
||||
@ -0,0 +1,51 @@ |
||||
/*
|
||||
* |
||||
* Copyright 2015, Google Inc. |
||||
* All rights reserved. |
||||
* |
||||
* Redistribution and use in source and binary forms, with or without |
||||
* modification, are permitted provided that the following conditions are |
||||
* met: |
||||
* |
||||
* * Redistributions of source code must retain the above copyright |
||||
* notice, this list of conditions and the following disclaimer. |
||||
* * Redistributions in binary form must reproduce the above |
||||
* copyright notice, this list of conditions and the following disclaimer |
||||
* in the documentation and/or other materials provided with the |
||||
* distribution. |
||||
* * Neither the name of Google Inc. nor the names of its |
||||
* contributors may be used to endorse or promote products derived from |
||||
* this software without specific prior written permission. |
||||
* |
||||
* THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
||||
* "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
||||
* LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
||||
* A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
||||
* OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
||||
* SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
||||
* LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
||||
* DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
||||
* THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
||||
* (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
||||
* OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||||
* |
||||
*/ |
||||
|
||||
#ifndef GRPCXX_IMPL_SERVER_BUILDER_OPTION_H |
||||
#define GRPCXX_IMPL_SERVER_BUILDER_OPTION_H |
||||
|
||||
#include <grpc++/support/channel_arguments.h> |
||||
|
||||
namespace grpc { |
||||
|
||||
/// Interface to pass an option to a \a ServerBuilder.
|
||||
class ServerBuilderOption { |
||||
public: |
||||
virtual ~ServerBuilderOption() {} |
||||
/// Alter the \a ChannelArguments used to create the gRPC server.
|
||||
virtual void UpdateArguments(ChannelArguments* args) = 0; |
||||
}; |
||||
|
||||
} // namespace grpc
|
||||
|
||||
#endif // GRPCXX_IMPL_SERVER_BUILDER_OPTION_H
|
||||
@ -0,0 +1,33 @@ |
||||
package http2interop |
||||
|
||||
import ( |
||||
"time" |
||||
) |
||||
|
||||
// Section 6.5 says the minimum SETTINGS_MAX_FRAME_SIZE is 16,384
|
||||
func testSmallMaxFrameSize(ctx *HTTP2InteropCtx) error { |
||||
conn, err := connect(ctx) |
||||
if err != nil { |
||||
return err |
||||
} |
||||
defer conn.Close() |
||||
conn.Log = ctx.T.Log |
||||
conn.SetDeadline(time.Now().Add(defaultTimeout)) |
||||
|
||||
sf := &SettingsFrame{ |
||||
Params: []SettingsParameter{{ |
||||
Identifier: SettingsMaxFrameSize, |
||||
Value: 1<<14 - 1, // 1 less than the smallest maximum
|
||||
}}, |
||||
} |
||||
|
||||
if err := http2Connect(conn, sf); err != nil { |
||||
return err |
||||
} |
||||
|
||||
if _, err := expectGoAwaySoon(conn); err != nil { |
||||
return err |
||||
} |
||||
|
||||
return nil |
||||
} |
||||
@ -0,0 +1,14 @@ |
||||
package http2interop |
||||
|
||||
import ( |
||||
"testing" |
||||
) |
||||
|
||||
func TestSmallMaxFrameSize(t *testing.T) { |
||||
if *testCase != "experimental" { |
||||
t.SkipNow() |
||||
} |
||||
ctx := InteropCtx(t) |
||||
err := testSmallMaxFrameSize(ctx) |
||||
matchError(t, err, "Got goaway frame") |
||||
} |
||||
@ -0,0 +1,46 @@ |
||||
#!/bin/bash |
||||
# Copyright 2015, Google Inc. |
||||
# All rights reserved. |
||||
# |
||||
# Redistribution and use in source and binary forms, with or without |
||||
# modification, are permitted provided that the following conditions are |
||||
# met: |
||||
# |
||||
# * Redistributions of source code must retain the above copyright |
||||
# notice, this list of conditions and the following disclaimer. |
||||
# * Redistributions in binary form must reproduce the above |
||||
# copyright notice, this list of conditions and the following disclaimer |
||||
# in the documentation and/or other materials provided with the |
||||
# distribution. |
||||
# * Neither the name of Google Inc. nor the names of its |
||||
# contributors may be used to endorse or promote products derived from |
||||
# this software without specific prior written permission. |
||||
# |
||||
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
||||
# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
||||
# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
||||
# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
||||
# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
||||
# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT |
||||
# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, |
||||
# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY |
||||
# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT |
||||
# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE |
||||
# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
||||
|
||||
set -ex |
||||
|
||||
if [ "$CONFIG" != "gcov" ] ; then exit ; fi |
||||
|
||||
root=$(readlink -f $(dirname $0)/../..) |
||||
out=$root/reports/ruby_ext_coverage |
||||
tmp1=$(mktemp) |
||||
tmp2=$(mktemp) |
||||
cd $root |
||||
lcov --capture --directory . --output-file $tmp1 |
||||
lcov --extract $tmp1 "$root/src/ruby/*" --output-file $tmp2 |
||||
genhtml $tmp2 --output-directory $out |
||||
rm $tmp2 |
||||
rm $tmp1 |
||||
|
||||
cp -rv $root/src/ruby/coverage $root/reports/ruby |
||||
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue