Merge pull request #1311 from yang-g/codegen

Clarify some auth test definitions

doc/interop-test-descriptions.md

@@ -2,7 +2,7 @@ Interoperability Test Case Descriptions
 =======================================
 
 Client and server use
-[test.proto](https://github.com/grpc/grpc/blob/master/test/cpp/interop/test.proto)
+[test.proto](https://github.com/grpc/grpc/blob/master/test/proto/test.proto)
 and the [gRPC over HTTP/2 v2
 protocol](https://github.com/grpc/grpc-common/blob/master/PROTOCOL-HTTP2.md).
 
@@ -30,6 +30,14 @@ Clients should accept these arguments:
     * Whether to replace platform root CAs with
       [ca.pem](https://github.com/grpc/grpc/blob/master/src/core/tsi/test_creds/ca.pem)
       as the CA root
+* --default_service_account=ACCOUNT_EMAIL
+    * Email of the GCE default service account. Only applicable
+      for compute_engine_creds test.
+* --oauth_scope=SCOPE
+    * OAuth scope. For example, "https://www.googleapis.com/auth/xapi.zoo"
+* --service_account_key_file=PATH
+    * The path to the service account JSON key file generated from GCE developer
+    console.
 
 Clients must support TLS with ALPN. Clients must not disable certificate
 checking.
@@ -259,25 +267,26 @@ Asserts:
 
 ### compute_engine_creds
 
-Status: Not yet implementable
-
 This test is only for cloud-to-prod path.
 
 This test verifies unary calls succeed in sending messages while using Service
 Credentials from GCE metadata server. The client instance needs to be created
 with desired oauth scope.
 
+The test uses `--default_service_account` with GCE service account email and
+`--oauth_scope` with the OAuth scope to use. For testing against
+grpc-test.sandbox.google.com, "https://www.googleapis.com/auth/xapi.zoo" should
+be passed in as `--oauth_scope`.
+
 Server features:
 * [UnaryCall][]
 * [Compressable Payload][]
-* SimpeResponse.username
-* SimpleResponse.oauth_scope
+* [Echo Authenticated Username][]
+* [Echo OAuth Scope][]
 
 Procedure:
- 1. Client sets flags default_service_account with GCE service account name and
-    oauth_scope with the oauth scope to use.
- 2. Client configures channel to use GCECredentials
- 3. Client calls UnaryCall on the channel with:
+ 1. Client configures channel to use GCECredentials
+ 2. Client calls UnaryCall on the channel with:
 
     ```
     {
@@ -293,32 +302,34 @@ Procedure:
 
 Asserts:
 * call was successful
-* received SimpleResponse.username equals FLAGS_default_service_account
-* received SimpleResponse.oauth_scope is in FLAGS_oauth_scope
+* received SimpleResponse.username equals the value of `--default_service_account` flag
+* received SimpleResponse.oauth_scope is in `--oauth_scope`
 * response payload body is 314159 bytes in size
 * clients are free to assert that the response payload body contents are zero
   and comparing the entire response message against a golden response
 
 ### service_account_creds
 
-Status: Not yet implementable
-
 This test is only for cloud-to-prod path.
 
 This test verifies unary calls succeed in sending messages while using JWT
 signing keys (redeemed for OAuth2 access tokens by the auth implementation)
 
+The test uses `--service_account_key_file` with the path to a json key file
+downloaded from https://console.developers.google.com, and `--oauth_scope`
+to the oauth scope. For testing against grpc-test.sandbox.google.com,
+"https://www.googleapis.com/auth/xapi.zoo" should be passed in
+as `--oauth_scope`.
+
 Server features:
 * [UnaryCall][]
 * [Compressable Payload][]
-* SimpleResponse.username
-* SimpleResponse.oauth_scope
+* [Echo Authenticated Username][]
+* [Echo OAuth Scope][]
 
 Procedure:
- 1. Client sets flags service_account_key_file with the path to json key file,
-    oauth_scope to the oauth scope.
- 2. Client configures the channel to use ServiceAccountCredentials.
- 3. Client calls UnaryCall with:
+ 1. Client configures the channel to use ServiceAccountCredentials.
+ 2. Client calls UnaryCall with:
 
     ```
     {
@@ -335,31 +346,32 @@ Procedure:
 Asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file read from
-  FLAGS_service_account_key_file
-* received SimpleResponse.oauth_scope is in FLAGS_oauth_scope
+   `--service_account_key_file`
+* received SimpleResponse.oauth_scope is in `--oauth_scope`
 * response payload body is 314159 bytes in size
 * clients are free to assert that the response payload body contents are zero
   and comparing the entire response message against a golden response
 
 ### jwt_token_creds
 
-Status: Not yet implementable
-
 This test is only for cloud-to-prod path.
 
 This test verifies unary calls succeed in sending messages while using JWT
 token (created by the project's key file)
 
+Test caller should set flag `--service_account_key_file` with the
+path to json key file downloaded from
+https://console.developers.google.com.
+
 Server features:
 * [UnaryCall][]
 * [Compressable Payload][]
-* SimpleResponse.username
-* SimpleResponse.oauth_scope
+* [Echo Authenticated Username][]
+* [Echo OAuth Scope][]
 
 Procedure:
- 1. Client sets flags service_account_key_file with the path to json key file
- 2. Client configures the channel to use JWTTokenCredentials.
- 3. Client calls UnaryCall with:
+ 1. Client configures the channel to use JWTTokenCredentials.
+ 2. Client calls UnaryCall with:
 
     ```
     {
@@ -375,7 +387,7 @@ Procedure:
 Asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file read from
-  FLAGS_service_account_key_file
+  `--service_account_key_file`
 * response payload body is 314159 bytes in size
 * clients are free to assert that the response payload body contents are zero
   and comparing the entire response message against a golden response
@@ -394,7 +406,8 @@ Server features:
   back to client in both header and trailer. (TODO: this is not defined)
 
 Procedure:
- 1. While sending custom metadata (ascii + binary) in the header, client calls UnaryCall with:
+ 1. While sending custom metadata (ascii + binary) in the header, client calls
+ UnaryCall with:
 
     ```
     {
@@ -619,11 +632,6 @@ payload body of size SimpleRequest.response_size bytes and type as appropriate
 for the SimpleRequest.response_type. If the server does not support the
 response_type, then it should fail the RPC with INVALID_ARGUMENT.
 
-If the request sets fill_username, the server should return the client username
-it sees in field SimpleResponse.username. If the request sets fill_oauth_scope,
-the server should return the oauth scope of the rpc in the form of "xapi_zoo"
-in field SimpleResponse.oauth_scope.
-
 ### StreamingInputCall
 [StreamingInputCall]: #streaminginputcall
 
@@ -672,14 +680,30 @@ Interaction with flow control is unspecified.
 
 Status: Pending
 
+#### Echo Authenticated Username
+[Echo Authenticated Username]: #echo-authenticated-username
+
 If a SimpleRequest has fill_username=true and that request was successfully
 authenticated, then the SimpleResponse should have username filled with the
 canonical form of the authenticated source. The canonical form is dependent on
 the authentication method, but is likely to be a base 10 integer identifier or
 an email address.
 
+#### Echo OAuth scope
+[Echo OAuth Scope]: #echo-oauth-scope
+
+If a SimpleRequest has fill_oauth_scope=true and that request was successfully
+authenticated via OAuth, then the SimpleResponse should have oauth_scope filled
+with the scope of the method being invoked.
+
+Although a general server-side feature, most test servers won't implement this
+feature. The TLS server grpc-test.sandbox.google.com:443 supports this feature.
+It requires at least the OAuth scope
+`https://www.googleapis.com/auth/xapi.zoo` for authentication to succeed.
+
 Discussion:
 
 Ideally, this would be communicated via metadata and not in the
 request/response, but we want to use this test in code paths that don't yet
 fully communicate metadata.
+