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

tokenserver/api/minter/v1/token_minter.proto

Index: tokenserver/api/minter/v1/token_minter.proto
diff --git a/tokenserver/api/minter/v1/token_minter.proto b/tokenserver/api/minter/v1/token_minter.proto
index 71150ffebeb77a1f924dc56e7bdf78fa38fb06b7..d8abd680ae02e2364a20eb3032304fe014baa47c 100644
--- a/tokenserver/api/minter/v1/token_minter.proto
+++ b/tokenserver/api/minter/v1/token_minter.proto
@@ -37,26 +37,25 @@ enum ErrorCode {
 
 // TokenMinter implements main API of the token server.
 //
-// It provides an interface for generating and inspecting of:
+// It provides an interface for generating:
 //
 //  * Machine tokens: short lived stateless tokens used in Swarming bot
 //    authentication protocol. They are derived from PKI keys deployed on bots,
-//    and consumed primarily by Swarming.
+//    and consumed primarily by Swarming. See MintMachineToken.
 //
-//  * Delegation tokens: these are involved whenever something wants to act on
-//    behalf of something else. In particular, whenever a service calls other
-//    service on behalf of a user, or when a user posts a Swarming task that
-//    runs in a context of some service account. There are multiple kinds of
-//    delegation tokens:
-//      - Bearer delegation tokens: they passed via 'X-Delegation-Token-V1'
-//        HTTP header and can be used to "impersonate" the identity of a caller.
-//      - OAuth2 token grants: they are signed assertions that particular
-//        services are allowed to grab service account OAuth2 tokens. They are
-//        used in Swarming service accounts implementation. This is TODO.
+//  * Delegation tokens: these are involved whenever a service calls other
+//    service on behalf of a user. They are passed via 'X-Delegation-Token-V1'
+//    HTTP header along with a credentials of the impersonating user.
+//    See MintDelegationToken.
 //
-//  * OAuth2 tokens: these are regular Google OAuth2 access tokens associated
-//    with various service accounts (that the token server has
-//    serviceAccountActor role in). This is TODO.
+//  * OAuth2 token grants: they are signed assertions that particular
+//    services are allowed to grab service account OAuth2 tokens on behalf
+//    of particular end users. They are used in Swarming service accounts
+//    implementation. See MintOAuthTokenGrant and MintOAuthTokenViaGrant.
+//
+//  * OAuth2 access tokens: these are regular Google OAuth2 access tokens

[smut, 2017/07/28 23:07:37]

Is "Google OAuth2" actually different than "OAuth2"?

[Vadim Sh., 2017/07/28 23:11:09]

Yeah, only Google servers accept them :) Support for a generic OAuth2 would mean
support for multiple OAuth2 identity providers.

+//    associated with various service accounts. See MintOAuthTokenGrant
+//    and MintOAuthTokenViaGrant.
 service TokenMinter {
   // MintMachineToken generates a new token for an authenticated machine.
   //
@@ -89,11 +88,48 @@ service TokenMinter {
   // combinations of (caller identity, delegated identity, audience, service)
   // tuples. See DelegationRule in config.proto.
   rpc MintDelegationToken(MintDelegationTokenRequest) returns (MintDelegationTokenResponse);
+
+  // MintOAuthTokenGrant generates a new grant for getting an OAuth2 token.
+  //
+  // This is a special (opaque for clients) token that asserts that the caller
+  // at the time of the call was allowed to act as a particular service account
+  // to perform a task authorized by an end-user.
+  //
+  // The returned grant can be used later (when the end-user is no longer
+  // present) to get a real OAuth2 access token via MintOAuthTokenViaGrant call.
+  //
+  // This pair of RPCs is used to "delay" generation of service account OAuth
+  // token until some later time, when it is actually needed. This is used by
+  // Swarming:
+  //   1. When the task is posted, Swarming calls MintOAuthTokenGrant to verify
+  //      that the end-user is allowed to act as the requested service account
+  //      on Swarming. On success, Swarming stores the grant in the task
+  //      metadata.
+  //   2. At a later time, when the task is executing and it needs an access
+  //      token, Swarming calls MintOAuthTokenViaGrant to convert the grant into
+  //      a real OAuth2 token.
+  //
+  // The returned grant can be used multiple times (as long as its validity
+  // duration and the token server policy allows).
+  //
+  // The token server must be configured in advance with all expected
+  // combinations of (caller identity, service account name, end users) tuples.
+  // See ServiceAccountRule in config.proto.
+  //
+  // MintOAuthTokenGrant will check that the requested usage is allowed by the
+  // rules. Later, MintOAuthTokenViaGrant will recheck this too.
+  rpc MintOAuthTokenGrant(MintOAuthTokenGrantRequest) returns (MintOAuthTokenGrantResponse);
+
+  // MintOAuthTokenViaGrant converts an OAuth2 token grant into an access token.
+  //
+  // The grant must be previously generated by MintOAuthTokenGrant function, see
+  // its docs for more details.
+  rpc MintOAuthTokenViaGrant(MintOAuthTokenViaGrantRequest) returns (MintOAuthTokenViaGrantResponse);
 }
 
 
 ////////////////////////////////////////////////////////////////////////////////
-// Machine Tokens messages
+// Machine tokens.
 
 
 // MintMachineTokenRequest wraps a serialized and signed MachineTokenRequest
@@ -138,7 +174,7 @@ message MachineTokenRequest {
 }
 
 
-// MintMachineTokenResponse is returned by 'MintMachineToken' if the server
+// MintMachineTokenResponse is returned by MintMachineToken if the server
 // processed the request.
 //
 // It's returned even if server refuses to mint a token. It contains the error
@@ -201,7 +237,7 @@ message LuciMachineToken {
 
 
 ////////////////////////////////////////////////////////////////////////////////
-// Delegation Tokens messages
+// Delegation tokens.
 
 
 // MintDelegationTokenRequest is passed to MintDelegationToken.
@@ -252,7 +288,7 @@ message MintDelegationTokenRequest {
 }
 
 
-// MintDelegationTokenResponse is returned by 'MintDelegationToken' on success.
+// MintDelegationTokenResponse is returned by MintDelegationToken on success.
 //
 // Errors are returned via standard gRPC codes.
 message MintDelegationTokenResponse {
@@ -268,5 +304,101 @@ message MintDelegationTokenResponse {
   // Identifier of the service and its version that produced the token.
   //
   // Has the form "<app-id>/<module-version>". This is _not_ part of the token.
+  // Used only for logging and monitoring.
+  string service_version = 3;
+}
+
+
+////////////////////////////////////////////////////////////////////////////////
+// OAuth2 access token grants and OAuth2 service account access tokens.
+
+
+// MintOAuthTokenGrantRequest is passed to MintOAuthTokenGrant.
+//
+// Additional implicit field is the identity of whoever makes this call. It
+// becomes 'wielder_identity' of the generated token.
+message MintOAuthTokenGrantRequest {
+  // Service account identity the end user wants to act as.
+  //
+  // A string of the form "user:<email>".
+  //
+  // Required.
+  string service_account = 1;
+
+  // How long the generated grant should be considered valid (in seconds).
+  //
+  // Default is 3600 sec.
+  int64 validity_duration = 2;
+
+  // An end user that wants to act as the service account (perhaps indirectly).
+  //
+  // A string of the form "user:<email>". On Swarming, this is an identity of
+  // a user that posted the task.
+  //
+  // TODO(vadimsh): Verify that this user is present during MintOAuthTokenGrant
+  // RPC by requiring the end user's credentials, e.g make Swarming forward
+  // user's OAuth token to the token server, where it can be validated.
+  //
+  // Required.
+  string end_user_identity = 3;
+
+  // Optional reason why the grant is created.
+  //
+  // Used only for logging and auditing purposes. Doesn't become part of the
+  // grant.
+  string intent = 4;
+}
+
+
+// MintOAuthTokenGrantResponse is returned by MintOAuthTokenGrant.
+message MintOAuthTokenGrantResponse {
+  string grant_token               = 1; // an opaque urlsafe token
+  google.protobuf.Timestamp expiry = 2; // when this token expires
+
+  // Identifier of the service and its version that produced the token.
+  //
+  // Has the form "<app-id>/<module-version>". This is _not_ part of the token.
+  // Used only for logging and monitoring.
+  string service_version = 3;
+}
+
+
+// MintOAuthTokenViaGrantRequest is passed to MintOAuthTokenViaGrant.
+//
+// Additional implicit field is the identity of whoever makes this call. It is
+// compared against 'wielder_identity' inside the token.
+message MintOAuthTokenViaGrantRequest {
+  // A previously generated grant, as returned by MintOAuthTokenGrant.
+  string grant_token = 1;
+
+  // The list of OAuth scopes the access token should have.
+  //
+  // The server may reject the request if some scopes are not allowed.
+  repeated string oauth_scopes = 2;
+
+  // Minimally accepted validity duration of the returned OAuth token (seconds).
+  //
+  // The server may return a token that lives longer than this. The maximum is
+  // 1h. An attempt to get a token that lives longer than 1h will result in
+  // an error.
+  //
+  // The returned token validity duration doesn't depend on the lifetime of
+  // the grant: it's possible to use a grant that expires in 1 sec to get an
+  // access token that lives for 1h.
+  //
+  // Default is 300 sec.
+  int64 min_validity_duration = 3;
+}
+
+
+// MintOAuthTokenViaGrantResponse is returned by MintOAuthTokenViaGrant.
+message MintOAuthTokenViaGrantResponse {
+  string access_token = 1;              // service account OAuth2 access token
+  google.protobuf.Timestamp expiry = 2; // when this token expires
+
+  // Identifier of the service and its version that produced the token.
+  //
+  // Has the form "<app-id>/<module-version>". Used only for logging and
+  // monitoring.
   string service_version = 3;
 }