token-server: Add protos for new API for generating service account tokens.

tokenserver/api/admin/v1/admin.proto

Index: tokenserver/api/admin/v1/admin.proto
diff --git a/tokenserver/api/admin/v1/admin.proto b/tokenserver/api/admin/v1/admin.proto
index d05dc82ab3390686d6e1e1a731091f1014f68026..99992f4f2e81394077c46e067a1f582f2bca6870 100644
--- a/tokenserver/api/admin/v1/admin.proto
+++ b/tokenserver/api/admin/v1/admin.proto
@@ -10,26 +10,20 @@ import "google/protobuf/empty.proto";
 
 import "github.com/luci/luci-go/server/auth/delegation/messages/delegation.proto";
 import "github.com/luci/luci-go/tokenserver/api/machine_token.proto";
+import "github.com/luci/luci-go/tokenserver/api/oauth_token_grant.proto";
 
 
 // Admin service is used by service administrators to manage the server.
 service Admin {
-  // ImportCAConfigs makes the server read CA configs from luci-config.
-  //
-  // This reads 'tokenserver.cfg' file.
-  //
-  // Note that regularly configs are read in background each 5 min.
-  // ImportCAConfigs can be used to force config reread immediately. It will
-  // block until the configs are read.
+  // ImportCAConfigs makes the server read 'tokenserver.cfg'.
   rpc ImportCAConfigs(google.protobuf.Empty) returns (ImportedConfigs);
 
-  // ImportDelegationConfigs makes the server read 'delegation.cfg' config.
-  //
-  // Note that regularly configs are read in background each 5 min.
-  // ImportDelegationConfigs can be used to force config reread immediately. It
-  // will block until the configs are read.
+  // ImportDelegationConfigs makes the server read 'delegation.cfg'.
   rpc ImportDelegationConfigs(google.protobuf.Empty) returns (ImportedConfigs);
 
+  // ImportServiceAccountsConfigs makes the server read 'service_accounts.cfg'.
+  rpc ImportServiceAccountsConfigs(google.protobuf.Empty) returns (ImportedConfigs);
+
   // InspectMachineToken decodes a machine token and verifies it is valid.
   //
   // It verifies the token was signed by a private key of the token server and
@@ -63,6 +57,23 @@ service Admin {
   //   grpc.InvalidArgument error for unsupported token kind.
   //   grpc.Internal error for transient errors.
   rpc InspectDelegationToken(InspectDelegationTokenRequest) returns (InspectDelegationTokenResponse);
+
+  // InspectOAuthTokenGrant decodes OAuth token grant and verifies it is valid.
+  //
+  // It verifies the token was signed by a private key of the token server and
+  // checks token's expiration time.
+  //
+  // It tries to give as much information about the token and its status as
+  // possible (e.g. attempts to decode the body even if the signing key has been
+  // rotated already).
+  //
+  // Administrators can use this call to debug issues with tokens.
+  //
+  // Returns:
+  //   InspectOAuthTokenGrantResponse for tokens of supported kind.
+  //   grpc.InvalidArgument error for unsupported token kind.
+  //   grpc.Internal error for transient errors.
+  rpc InspectOAuthTokenGrant(InspectOAuthTokenGrantRequest) returns (InspectOAuthTokenGrantResponse);
 }
 
 
@@ -200,3 +211,54 @@ message InspectDelegationTokenResponse {
   // May be empty if token was malformed and couldn't be deserialized.
   messages.Subtoken subtoken = 6;
 }
+
+
+// InspectOAuthTokenGrantRequest is body of InspectOAuthTokenGrant RPC call.
+message InspectOAuthTokenGrantRequest {
+  // The token body.
+  string token = 1;
+}
+
+
+// InspectOAuthTokenGrantResponse is return value of InspectOAuthTokenGrant RPC.
+message InspectOAuthTokenGrantResponse {
+  // True if the token is valid.
+  //
+  // A token is valid if its signature is correct and it hasn't expired yet.
+  bool valid = 1;
+
+  // Human readable summary of why token is invalid.
+  //
+  // Summarizes the rest of the fields of this struct. Set only if 'valid' is
+  // false.
+  string invalidity_reason = 2;
+
+  // True if the token signature was verified.
+  //
+  // It means the token was generated by the token server and its body is not
+  // a garbage. Note that a token can be correctly signed, but invalid (if it
+  // has expired).
+  //
+  // If 'signed' is false, the fields below may (or may not) be a garbage.
+  //
+  // The token server uses private keys managed by Google Cloud Platform, they
+  // are constantly being rotated and "old" signatures become invalid over time
+  // (when corresponding keys are rotated out of existence).
+  //
+  // If 'signed' is false, use the rest of the response only as FYI, possibly
+  // invalid or even maliciously constructed.
+  bool signed = 3;
+
+  // True if the token signature was verified and token hasn't expired yet.
+  //
+  // We use "non_" prefix to make default 'false' value safer.
+  bool non_expired = 4;
+
+  // ID of a token server private key used to sign the token.
+  string signing_key_id = 5;
+
+  // The deserialized token body.
+  //
+  // May be empty if token was malformed and couldn't be deserialized.
+  tokenserver.OAuthTokenGrantBody token_body = 6;
+}