Create AUTH.md

An overview auth document using c++ code exampoles. The code will be translated to other languages in subsequet pull requests.

AUTH.md

@@ -0,0 +1,88 @@
+#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.
+
+###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.
+
+###Code Examples
+
+####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 
+// 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. 
+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.
+
+```
+std::unique_ptr<Credentials> creds = CredentialsFactory::DefaultGoogleCredentials();
+// 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);
+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
+service account’s private keys are expected in file located at [TODO: well
+known file fath for service account keys] or in the file named in the environment
+variable [TODO: add the env var name here]. The keys are used at run-time 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.