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

tokenserver/api/minter/v1/token_minter.proto

 // Copyright 2016 The LUCI Authors. All rights reserved.
 // Use of this source code is governed under the Apache License, Version 2.0
 // that can be found in the LICENSE file.
 
 syntax = "proto3";
 
 package tokenserver.minter;
 
 import "google/protobuf/timestamp.proto";
 
@@ skipping 19 matching lines @@
   BAD_CERTIFICATE_FORMAT      = 4; // malformed or unsupported certificate
   BAD_SIGNATURE               = 5; // signature doesn't match or can't be verified
   UNTRUSTED_CERTIFICATE       = 6; // invalid certificate or can't verify it yet
   BAD_TOKEN_ARGUMENTS         = 7; // FQDN or Scopes are invalid or not whitelisted
   MACHINE_TOKEN_MINTING_ERROR = 8; // unspecified fatal error when minting a machine token
 }
 
 
 // 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

[Vadim Sh., 2017/03/30 06:04:48]

After long consideration I decided to make "oauth2 token grants" separate
first-class objects since they end up having sufficiently different semantics
from delegation tokens. Trying to unify them results in a weird non-obvious
reuse of delegation token fields.

I'll try to extract as much of shared functionality as possible into reusable
functions though. For example, policy rules evaluation will probably be very
similar, so I'll try to reuse existing code.

-//        services are allowed to grab service account OAuth2 tokens. They are
-//        used in Swarming service accounts implementation. This is TODO.
+//    runs in a context of some service account. They passed via
+//    'X-Delegation-Token-V1' HTTP header and can be used to "impersonate"
+//    a caller. 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
+//    associated with various service accounts. See MintOAuthTokenGrant
+//    and MintOAuthTokenViaGrant.
 service TokenMinter {
   // MintMachineToken generates a new token for an authenticated machine.
   //
   // It checks that provided certificate was signed by some trusted CA, and it
   // is still valid (non-expired and hasn't been revoked). It then checks that
   // the request was signed by the corresponding private key. Finally it checks
   // that the caller is authorized to generate requested kind of token.
   //
   // If everything checks out, it generates and returns a new machine token.
   //
@@ skipping 12 matching lines @@
   // the token):
   //   * They have expiration time.
   //   * They are usable only if presented with a credential of someone from
   //     the 'audience' list.
   //   * They are usable only on services specified in the 'services' list.
   //
   // The token server must be configured in advance with all expected
   // 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.

[Vadim Sh., 2017/03/30 06:04:48]

This is the most important comment in this CL. It describes in a nut shell the
new protocol.

+  //
+  // 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
 // message.
 message MintMachineTokenRequest {
   // The protobuf-serialized MachineTokenRequest message, signed by the private
   // key that matches MachineTokenRequest.certificate.
   //
   // We have to send it as a byte blob to avoid dealing with possible protobuf
   // serialization inconsistencies when checking the signature.
@@ skipping 24 matching lines @@
   // Timestamp when this request was created, by the issuer clock.
   google.protobuf.Timestamp issued_at = 3;
 
   // The token type being requested.
   //
   // Defines what fields of the response are set.
   MachineTokenType token_type = 4;
 }
 
 
-// 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
 // details in that case.
 message MintMachineTokenResponse {
   // Possible kinds of fatal errors.
   //
   // Non fatal errors are returned as grpc.Internal errors instead.
   ErrorCode error_code = 1;
 
@@ skipping 42 matching lines @@
 // The token here is supposed to be treated as an opaque base64-encoded blob,
 // but in reality it is serialized MachineTokenEnvelope, see machine_token.proto
 // and read the comment there for more info about the token format.
 message LuciMachineToken {
   string machine_token = 1;             // the actual token
   google.protobuf.Timestamp expiry = 2; // when the token expires
 }
 
 
 ////////////////////////////////////////////////////////////////////////////////
-// Delegation Tokens messages
+// Delegation tokens.
 
 
 // MintDelegationTokenRequest is passed to MintDelegationToken.
 message MintDelegationTokenRequest {
   // Identity whose authority is delegated.
   //
   // A string of the form "user:<email>" or a special token "REQUESTOR" that
   // means to delegate caller's own identity. The token server will check its
   // ACLs to make sure the caller is authorized to impersonate this identity.
   //
@@ skipping 30 matching lines @@
   repeated string services = 4;
 
   // Optional reason why the token is created.
   //
   // Used only for logging and auditing purposes. Doesn't become part of the
   // token.
   string intent = 5;
 }
 
 
-// MintDelegationTokenResponse is returned by 'MintDelegationToken' on success.
+// MintDelegationTokenResponse is returned by MintDelegationToken on success.
 //
 // Errors are returned via standard gRPC codes.
 message MintDelegationTokenResponse {
   // The actual base64-encoded signed token.
   string token = 1;
 
   // Same data as in 'token' in deserialized form, just for convenience.
   //
   // Mostly for JSON encoding users, since they may not understand proto-encoded
   // tokens.
   messages.Subtoken delegation_subtoken = 2;
 
   // 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; // base64-encoded token with the grant
+  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 will result in a error.
+  //
+  // The returned token validity duration doesn't not 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 3600 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;
+}