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
-//        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.
   //
   // 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.
+  //
+  // 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; // 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;
+}