resolve comments

1 files changed, 51 insertions, 31 deletions

diff --git a/doc/interop-test-descriptions.md b/doc/interop-test-descriptions.md
index eca18f324d..7816991a7b 100644
--- a/doc/interop-test-descriptions.md
+++ b/doc/interop-test-descriptions.md
@@ -31,11 +31,13 @@ Clients should accept these arguments:
       [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 when running in GCE.
+    * Email of 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.
+    * 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.
@@ -271,17 +273,20 @@ 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 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```.
+
 Server features:
 * [UnaryCall][]
 * [Compressable Payload][]
-* Echoes authenticated username in SimpeResponse.username
-* Echoes OAuth scope in SimpleResponse.oauth_scope
+* [Echo Username][]
+* [Echo OAuth Scope][]
 
 Procedure:
- 1. Client sets --default_service_account with GCE service account email and
-    --oauth_scope with the OAuth scope to use. For testing against https://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:
+ 1. Client configures channel to use GCECredentials
+ 2. Client calls UnaryCall on the channel with:
 
     ```
     {
@@ -297,8 +302,8 @@ Procedure:
 
 Asserts:
 * call was successful
-* received SimpleResponse.username equals --default_service_account
-* received SimpleResponse.oauth_scope is in --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
@@ -310,16 +315,21 @@ 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 sets ```--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][]
-* Echoes authenticated username in SimpeResponse.username
-* Echoes OAuth scope in SimpleResponse.oauth_scope
+* [Echo Username][]
+* [Echo OAuth Scope][]
 
 Procedure:
- 1. Client sets --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 https://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:
+ 1. Client configures the channel to use ServiceAccountCredentials.
+ 2. Client calls UnaryCall with:
 
     ```
     {
@@ -336,8 +346,8 @@ Procedure:
 Asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file read from
-  --service_account_key_file
-* received SimpleResponse.oauth_scope is in --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
@@ -349,16 +359,18 @@ 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)
 
+Client sets 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 Username][]
+* [Echo OAuth Scope][]
 
 Procedure:
- 1. Client sets flags --service_account_key_file with the path to json key file downloaded from https://console.developers.google.com.
- 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:
 
     ```
     {
@@ -374,7 +386,7 @@ Procedure:
 Asserts:
 * call was successful
 * received SimpleResponse.username is in the json key file read from
-  --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
@@ -393,7 +405,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:
 
     ```
     {
@@ -618,11 +631,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
 
@@ -671,13 +679,26 @@ Interaction with flow control is unspecified.
 
 Status: Pending
 
+#### Echo authenticated user name
+[Echo Username]: #echo-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.
 
-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.
+#### 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:
 
@@ -685,4 +706,3 @@ 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 https://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".