tokenserver: Protos for service account rules.

tokenserver/api/admin/v1/config.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.admin;
 
 
 // TokenServerConfig is read from tokenserver.cfg in luci-config.
@@ skipping 73 matching lines @@
 //  * 'audience' is a subset of 'allowed_audience' set.
 //  * 'services' is a subset of 'target_service' set.
 //
 // The presence of a matching rule permits to mint the token. The rule also
 // provides an upper bound on allowed validity_duration, and the rule's name
 // is logged in the audit trail.
 message DelegationRule {
   // A descriptive name of this rule, for the audit log.
   string name = 1;
 
-  // Email of developers that added this rule, to know who to contact.
+  // Email of developers that own this rule, to know who to contact.
   repeated string owner = 2;
 
   // A set of callers to which this rule applies.
   //
   // Matched against verified credentials of a caller of MintDelegationToken.
   //
   // Each element is either:
   //  * An identity string ("user:<email>").
   //  * A group reference ("group:<name>").
   //
@@ skipping 53 matching lines @@
   //
   // Default is 12 hours.
   int64 max_validity_duration = 7;
 }
 
 
 // ServiceAccountsPermissions is read from service_accounts.cfg in luci-config.
 message ServiceAccountsPermissions {
   // Rules specify how MintOAuthTokenViaGrant can be used.
   //
-  // Rules are evaluated independently. One and only one rule should match the
-  // request to allow the operation. If none rules or more than one rule match,
-  // the request will be denied.
+  // Rules define a mapping {service account email -> authorization config},
+  // where 'service account email' is matched to 'service_account' field of
+  // ServiceAccountRule, and 'authorization config' is the rest of fields in
+  // ServiceAccountRule that define how exactly the given service account is
+  // allowed to be used.
   //
   // See ServiceAccountRule comments for more details.
   repeated ServiceAccountRule rules = 1;
 }
 
 
 // ServiceAccountRule describes a single allowed case of using service accounts.
 //
-// TODO(vadimsh): Implement.
+// The usage of a service account is initiated by an end user, through some
+// "proxy" service. For example, when a user posts a Swarming task that uses
+// a service account, the end user is whoever posts the task, and the proxy is
+// Swarming service itself.
+//
+// This rule specifies which end users are allowed to act as an account, and
+// through which proxies.
 message ServiceAccountRule {
   // A descriptive name of this rule, for the audit log.
   string name = 1;
 
-  // Email of developers that owns this rule, to know who to contact.
+  // Email of developers that own this rule, to know who to contact.
   repeated string owner = 2;
+
+  // Email of service accounts that this rule applies to.
+  //
+  // This is the "primary key" in the rules table: there can be only one rule
+  // that applies to a given service account.
+  repeated string service_account = 3;
+
+  // OAuth scopes we allow to be granted to the OAuth token.
+  //
+  // Any subset of given scopes is allowed. This field is evaluated in
+  // MintOAuthTokenViaGrant RPC handler, right before generating the OAuth
+  // token.
+  repeated string allowed_scope = 4;
+
+  // A set of identities that are allowed to act as the service account (perhaps
+  // indirectly through some other intermediary "proxy" service like Swarming).
+  //
+  // Users listed here are ultimately able to grab an OAuth token belonging to
+  // the service account.
+  //
+  // Each element is either:
+  //  * An identity string ("user:<email>").
+  //  * A group reference ("group:<name>").
+  repeated string end_user = 5;
+
+  // A set of identities that are allowed to act on behalf of end users when
+  // grabbing an OAuth token for the service account.
+  //
+  // These identities represent "proxy" services that do something with service
+  // accounts on behalf of end users. Only identities in this set are allowed
+  // to perform MintOAuthTokenGrant RPC.
+  //
+  // Each element is either:
+  //  * An identity string ("user:<email>").
+  //  * A group reference ("group:<name>").
+  repeated string proxy = 6;
+
+  // Maximum allowed validity duration (sec) of OAuth token grants.
+  //
+  // The grant is minted by MintOAuthTokenGrant RPC (called, for example, when
+  // Swarming task is posted), and checked by MintOAuthTokenViaGrant RPC (called
+  // when the task actually runs). So the allowed validity duration should
+  // account for possible queuing delays.
+  //
+  // This duration has no relation to the OAuth token lifetime. The OAuth token
+  // produced by MintOAuthTokenViaGrant can always live up to 1h regardless of
+  // validity duration of the grant.
+  //
+  // Default is 24 hours.
+  int64 max_grant_validity_duration = 7;
 }