Clarify auth test definitions

1 files changed, 26 insertions, 23 deletions

diff --git a/doc/interop-test-descriptions.md b/doc/interop-test-descriptions.md
index 3f5ce37e1e..f37b1a2275 100644
--- a/doc/interop-test-descriptions.md
+++ b/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,12 @@ 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 in the GCE default service account. Only applicable when running in GCE.
+* --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,8 +265,6 @@ 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
@@ -270,12 +274,12 @@ with desired oauth scope.
 Server features:
 * [UnaryCall][]
 * [Compressable Payload][]
-* SimpeResponse.username
-* SimpleResponse.oauth_scope
+* Echo authenticated username in SimpeResponse.username
+* Echo OAuth scope SimpleResponse.oauth_scope
 
 Procedure:
- 1. Client sets flags default_service_account with GCE service account name and
-    oauth_scope with the oauth scope to use.
+ 1. Client sets --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.
  2. Client configures channel to use GCECredentials
  3. Client calls UnaryCall on the channel with:
 
@@ -293,16 +297,14 @@ 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 --default_service_account
+* 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
@@ -310,13 +312,12 @@ signing keys (redeemed for OAuth2 access tokens by the auth implementation)
 
 Server features:
 * [UnaryCall][]
-* [Compressable Payload][]
-* SimpleResponse.username
-* SimpleResponse.oauth_scope
+* [Compressable Payload][
+* Echo authenticated username in SimpeResponse.username
+* Echo OAuth scope SimpleResponse.oauth_scope
 
 Procedure:
- 1. Client sets flags service_account_key_file with the path to json key file,
-    oauth_scope to the oauth scope.
+ 1. Client sets --service_account_key_file with the path to a json key file downloaded from 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.
  2. Client configures the channel to use ServiceAccountCredentials.
  3. Client calls UnaryCall with:
 
@@ -335,16 +336,14 @@ 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
@@ -357,7 +356,7 @@ Server features:
 * SimpleResponse.oauth_scope
 
 Procedure:
- 1. Client sets flags service_account_key_file with the path to json key file
+ 1. Client sets flags --service_account_key_file with the path to json key file downloaded from console.developers.google.com.
  2. Client configures the channel to use JWTTokenCredentials.
  3. Client calls UnaryCall with:
 
@@ -375,7 +374,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
@@ -621,7 +620,7 @@ 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"
+the server should return the oauth scope of the rpc in the form of "xapi.zoo"
 in field SimpleResponse.oauth_scope.
 
 ### StreamingInputCall
@@ -678,8 +677,12 @@ 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.
 
+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.
+
 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.
+
+The server side auth echoing is only implemented in the server sitting behind grpc-test.sandbox.google.com and is enabled only for UnaryCall. In this case the expected OAuth scope is "https://www.googleapis.com/auth/xapi.zoo".