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;

option go_package = "go.chromium.org/luci/tokenserver/api/admin/v1;admin";


// TokenServerConfig is read from tokenserver.cfg in luci-config.
message TokenServerConfig {
  // List of CAs we trust.
  repeated CertificateAuthorityConfig certificate_authority = 1;
}


// CertificateAuthorityConfig defines a single CA we trust.
//
// Such CA issues certificates for nodes that use The Token Service. Each node
// has a private key and certificate with Common Name set to the FQDN of this
// node, e.g. "CN=slave43-c1.c.chromecompute.google.com.internal".
//
// The Token Server uses this CN to derive an identity string for a machine. It
// splits FQDN into a hostname ("slave43-c1") and a domain name
// ("c.chromecompute.google.com.internal"), searches for a domain name in
// "known_domains" set, and, if it is present, uses parameters described there
// for generating a token that contains machine's FQDN and certificate serial
// number (among other things, see MachineTokenBody in machine_token.proto).
message CertificateAuthorityConfig {
  int64  unique_id = 6; // ID of this CA, will be embedded into tokens.
  string cn = 1;        // CA Common Name, must match Subject CN in the cert
  string cert_path = 2; // path to the root certificate file in luci-config
  string crl_url = 3;   // where to fetch CRL from
  bool   use_oauth = 4; // true to send Authorization header when fetching CRL
  repeated string oauth_scopes = 7; // OAuth scopes to use when fetching CRL

  // KnownDomains describes parameters to use for each particular domain.
  repeated DomainConfig known_domains = 5;
}


// DomainConfig is used inside CertificateAuthorityConfig.
message DomainConfig {
  reserved 2, 3, 4, 6; // deleted fields, do not reuse.

  // Domain is domain names of hosts this config applies to.
  //
  // Machines that reside in a subdomain of given domain are also considered
  // part of it, e.g. both FQDNs "host.example.com" and "host.abc.example.com"
  // match domain "example.com".
  repeated string domain = 1;

  // MachineTokenLifetime is how long generated machine tokens live, in seconds.
  //
  // If 0, machine tokens are not allowed.
  int64 machine_token_lifetime = 5;
}


// DelegationPermissions is read from delegation.cfg in luci-config.
message DelegationPermissions {
  // Rules specify what calls to MintDelegationToken are allowed.
  //
  // 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.
  //
  // See DelegationRule comments for more details.
  repeated DelegationRule rules = 1;
}


// DelegationRule describes a single allowed case of using delegation tokens.
//
// 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 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>").
  //
  // 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.
  //
  // 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;
}


// ServiceAccountsProjectMapping defines what service accounts belong to what
// LUCI projects.
//
// Used by MintServiceAccountToken RPC as a final authorization step, after
// checking that the usage of the service account is allowed by Realms ACLs.
//
// This is a stop gap solution until the Token Server learns to use
// project-scoped accounts when calling Cloud IAM. Once this happens, we can
// move information contained in ServiceAccountsProjectMapping into Cloud IAM
// permissions.
//
// This message is stored as project_owned_accounts.cfg in luci-config.
message ServiceAccountsProjectMapping {
  message Mapping {
    // Names of LUCI projects.
    repeated string project = 1;
    // Emails of service accounts allowed to be used by all these projects.
    repeated string service_account = 2;
  }

  // Each entry maps a bunch of service accounts to one or more projects.
  repeated Mapping mapping = 1;

  // A list of LUCI project names for which service account impersonation should
  // be done using LUCI project-scoped account as a delegate. This allows to
  // move "LUCI project => allowed service account" mapping into IAM policies,
  // making `mapping` above obsolete.
  //
  // If a LUCI project belongs to this list, it must not have any entries in
  // the `mapping` field above.
  repeated string use_project_scoped_account = 2;
}