Craig Tiller
9 years ago
commit
2c23ad57ed
941 changed files with 22588 additions and 10671 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 |
||||
File diff suppressed because it is too large
Load Diff
File diff suppressed because it is too large
Load Diff
Some files were not shown because too many files have changed in this diff Show More
Loading…
Reference in new issue