token-server: Delegation config import, validation and evaluation.

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 48 matching lines @@
   // request to allow the operation. If none rules or more than one rule match,
   // the request will be denied.
   //
   // See DelegationRule comments for more details.
   repeated DelegationRule rules = 1;
 }
 
 
 // DelegationRule describes a single allowed case of using delegation tokens.
 //
-// An incoming MintDelegationToken request is basically a tuple of:
+// An incoming MintDelegationTokenRequest is basically a tuple of:
 //  * 'requestor_id' - an identity of whoever makes the request.
 //  * 'delegated_identity' - an identity to delegate.
 //  * 'audience' - a set of identities that will be able to use the token.
 //  * 'services' - a set of services that should accept the token.
 //
 // A request matches a rule iff:
 //  * 'requestor_id' is in 'requestor' set.
 //  * 'delegated_identity' is in 'allowed_to_impersonate' set.
 //  * '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.
   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>").
+  //
+  // The groups specified here are expanded when MintDelegationTokenRequest is
+  // evaluated.
   repeated string requestor = 3;
 
   // Identities that are allowed to be delegated/impersonated by the requestor.
   //
+  // Matched against 'delegated_identity' field of MintDelegationTokenRequest.
+  //
   // Each element is either:
   //  * An identity string ("user:<email>").
   //  * A group reference ("group:<name>").
   //  * A special identifier "REQUESTOR" that is substituted by the requestor
   //    identity when evaluating the rule.
   //
   // "REQUESTOR" allows one to generate tokens that delegate their own identity
   // to some target audience.
+  //
+  // The groups specified here are expanded when MintDelegationTokenRequest is
+  // evaluated.
   repeated string allowed_to_impersonate = 4;
 
   // A set of identities that should be able to use the new token.
   //
+  // Matched against 'audience' field of MintDelegationTokenRequest.
+  //
   // Each element is either:
   //  * An identity string ("user:<email>").
   //  * A group reference ("group:<name>").
   //  * A special identifier "REQUESTOR" that is substituted by the requestor
   //    identity when evaluating the rule.
+  //  * A special token "*" that means "any bearer can use the new token,
+  //    including anonymous".
   //
   // "REQUESTOR" is typically used here for rules that allow requestors to
   // impersonate someone else. The corresponding tokens have the requestor as
   // the only allowed audience.
+  //
+  // The groups specified here are NOT expanded when MintDelegationTokenRequest
+  // is evaluated. To match the rule, MintDelegationTokenRequest must specify
+  // subset of 'allowed_audience' groups explicitly in 'audience' field.
   repeated string allowed_audience = 5;
 
   // A set of services that should be able to accept the new token.
   //
-  // Each element is a service identity string ("service:<id>").
+  // Matched against 'services' field of MintDelegationTokenRequest.
+  //
+  // Each element is either:
+  //  * A service identity string ("service:<id>").
+  //  * A special token "*" that mean "any LUCI service should accept the
+  //    token".
   repeated string target_service = 6;
 
   // Maximum allowed validity duration (sec) of minted delegation tokens.
   //
   // Default is 12 hours.
   int64 max_validity_duration = 7;
 }