Update Documentation for AuthMetadataProcessor (#28985)

* update documentation for auth metadata processor

doc/server_side_auth.md

@@ -2,8 +2,8 @@ Server-side API for Authenticating Clients
 ==========================================
 
 NOTE: This document describes how server-side authentication works in C-core based gRPC implementations only. In gRPC Java and Go, server side authentication is handled differently.
-NOTE2: `CallCredentials` class is only valid for secure channels in C-Core. So, for connections under insecure channels, features below might not be available.
 
+NOTE2: `CallCredentials` class is only valid if the security level it requires is less than or equal to the security level of the connection used to transfer it. See the [gRFC](https://github.com/grpc/proposal/blob/master/L62-core-call-credential-security-level.md) for more information.
 ## AuthContext
 
 To perform server-side authentication, gRPC exposes the *authentication context* for each call. The context exposes important authentication-related information about the RPC such as the type of security/authentication type being used and the peer identity.
@@ -12,6 +12,9 @@ The authentication context is structured as a multi-map of key-value pairs - the
 
 The contents of the *auth properties* are populated by an *auth interceptor*. The interceptor also chooses which property key will act as the peer identity (e.g. for client certificate authentication this property will be `"x509_common_name"` or `"x509_subject_alternative_name"`).
 
+Note that AuthContext is generally not modifiable, except when used via an AuthMetadataProcessor([reference](https://github.com/grpc/grpc/blob/master/include/grpcpp/impl/codegen/security/auth_context.h)). 
+However, because the AuthContext is a connection-level object, when it is modified via an AuthMetadataProcessor, the modifications will be visible on all subsequent calls on the same connection.
+
 WARNING: AuthContext is the only reliable source of truth when it comes to authenticating RPCs. Using any other call/context properties for authentication purposes is wrong and inherently unsafe.
 
 #### Example AuthContext contents

include/grpcpp/security/auth_metadata_processor.h

@@ -30,6 +30,8 @@ namespace grpc {
 /// Interface allowing custom server-side authorization based on credentials
 /// encoded in metadata.  Objects of this type can be passed to
 /// \a ServerCredentials::SetAuthMetadataProcessor().
+/// Please also check out \a grpc::experimental::Interceptor for another way to
+/// do customized operations on the information provided by a specific call.
 class AuthMetadataProcessor {
  public:
   typedef std::multimap<grpc::string_ref, grpc::string_ref> InputMetadata;
@@ -41,15 +43,25 @@ class AuthMetadataProcessor {
   /// a different thread from the one processing the call.
   virtual bool IsBlocking() const { return true; }
 
-  /// context is read/write: it contains the properties of the channel peer and
-  /// it is the job of the Process method to augment it with properties derived
-  /// from the passed-in auth_metadata.
-  /// consumed_auth_metadata needs to be filled with metadata that has been
-  /// consumed by the processor and will be removed from the call.
-  /// response_metadata is the metadata that will be sent as part of the
-  /// response.
-  /// If the return value is not Status::OK, the rpc call will be aborted with
-  /// the error code and error message sent back to the client.
+  /// Processes a Call associated with a connection.
+  /// auth_metadata: the authentication metadata associated with the particular
+  ///   call
+  /// context: contains the connection-level info, e.g. the peer identity. This
+  ///   parameter is readable and writable. Note that since the information is
+  ///   shared for all calls associated with the connection, if the
+  ///   implementation updates the info in a specific call, all the subsequent
+  ///   calls will see the updates. A typical usage of context is to use
+  ///   |auth_metadata| to infer the peer identity, and augment it with
+  ///   properties.
+  /// consumed_auth_metadata: contains the metadata that the implementation
+  ///   wants to remove from the current call, so that the server application is
+  ///   no longer able to see it anymore. A typical usage would be to do token
+  ///   authentication in the first call, and then remove the token information
+  ///   for all subsequent calls.
+  /// response_metadata(CURRENTLY NOT SUPPORTED): the metadata that will be sent
+  ///   as part of the response.
+  /// return: if the return value is not Status::OK, the rpc call will be
+  ///   aborted with the error code and error message sent back to the client.
   virtual grpc::Status Process(const InputMetadata& auth_metadata,
                                grpc::AuthContext* context,
                                OutputMetadata* consumed_auth_metadata,

src/core/lib/security/transport/server_auth_filter.cc

@@ -143,9 +143,9 @@ static void on_md_processing_done_inner(grpc_call_element* elem,
                                         grpc_error_handle error) {
   call_data* calld = static_cast<call_data*>(elem->call_data);
   grpc_transport_stream_op_batch* batch = calld->recv_initial_metadata_batch;
-  /* TODO(jboeuf): Implement support for response_md. */
+  /* TODO(ZhenLian): Implement support for response_md. */
   if (response_md != nullptr && num_response_md > 0) {
-    gpr_log(GPR_INFO,
+    gpr_log(GPR_ERROR,
             "response_md in auth metadata processing not supported for now. "
             "Ignoring...");
   }