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 owns this rule, to know who to contact.

[smut, 2017/08/02 23:04:16]

"own", not "owns", because "developers" is plural (subject-verb agreement)

[Vadim Sh., 2017/08/03 00:23:28]

Done.

   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, though some

[smut, 2017/08/02 23:04:16]

s/though/through/

[Vadim Sh., 2017/08/03 00:23:28]

Done.

+// "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.
   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.

[smut, 2017/08/02 23:04:16]

So when checking ServiceAccountsPermissions you will iterate over all
ServiceAccountRules and inspect each rule's service_accounts, and if you find
exactly one ServiceAccountRule that contains the service account being
requested, you will follow that rule. If you find zero or more than one it's an
error.

Am I understanding right?

[Vadim Sh., 2017/08/03 00:23:28]

Yes.

"More than one" check will happen when the config is being imported (and double
checked when it is loaded into memory for serving). The "in-memory"
representation of this config will be map[service account
email]ServiceAccountRule, to avoid scanning it linearly all the time.

+  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 during
+  // in MintOAuthTokenViaGrant RPC handler, right before generating the OAuth

[smut, 2017/08/02 23:04:16]

"during in" redundant, remove one.

[Vadim Sh., 2017/08/03 00:23:28]

Done.

+  // 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.
+  //
+  // This identities represent a "proxy" services that do something with service

[smut, 2017/08/02 23:04:16]

s/This/These/, s/services/service/

[Vadim Sh., 2017/08/03 00:23:28]

Done.

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