appengine/cr-buildbucket/access/access.proto

// Copyright (c) 2017 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.

// This file defines a common protocol to check what actions a given
// impersonated user can do on a given resource.
// For example, it can be used by one app against another.

syntax = "proto3";

package access;

import "google/protobuf/duration.proto";
import "google/protobuf/empty.proto";

// Access service can be used to check what actions a given user can perform
// on a given resource.
service Access {
  // PermittedActions returns a list of actions the requester can perform
  // on a given resource.
  rpc PermittedActions(PermittedActionsRequest) returns (PermittedActionsResponse) {};
  // Description returns types of resources and actions that this service
  // supports.
  // It is intended to be used as self-documentation, for humans that play
  // with the API.
  // If the concepts returned by this RPC are internal, it should be restricted.
  rpc Description(google.protobuf.Empty) returns (DescriptionResponse) {};
}

// DescriptionResponse is the response message from Access.Description.
message DescriptionResponse {

  // ResourceDescription is one resource type, e.g. buildbucket bucket
  // or swarming pool.
  message ResourceDescription {

    // Action describes what a user can do with a resource.
    message Action {
      // Comment provides more human-readable info about the action.
      string comment = 1;
    }

    // Role is a named set of allowed actions.
    message Role {
      // AllowedActions is a set of action IDs.
      // It defines what a role bearer can do with the resource.
      repeated string allowed_actions = 1;
      // Comment provides more info about the role.
      string comment = 2;
    }

    // Kind identifies the resource type presented on the service.
    // Access.PermittedActions accepts one of resource kinds.
    // Example: "bucket" for buildbucket bucket, "package" for CIPD package.
    //
    // For implementers:
    // Kind must match regexp `^[a-z\-/]+$`.
    string kind = 1;

    // Comment provides more info about the resource.
    string comment = 2;

    // Actions defines all possible actions that can be performed on this type
    // of resource.
    //
    // Map key is an action ID, unique within the resource.
    // It is referenced from Role.allowed_actions.
    //
    // For implementers:
    // ActionId must match regexp `^[A-Z\_]+$`.
    // Recommendations:
    // - "READ", not "GET"
    // - "DELETE", not "REMOVE"
    // - prefer concrete actions ("ADD_BUILD", "CHANGE_ACL", "INCREMENT") to
    //   abstract ones ("MODIFY", "WRITE", "UPDATE").
    map<string, Action> actions = 3;

    // Roles maps a role id to a set of actions.
    // Access configurations are typically expressed with roles, not actions.
    //
    // For implementers:
    // Role IDs must match regexp `^[A-Z\_]+$`.
    // Recommendataion: if it makes sense, make role ID close to the action
    // names, e.g. READER can READ, SCHEDULER can SCHEDULE.
    map<string, Role> roles = 4;
  }

  // Resources is a list of resource types presented on the given service.
  repeated ResourceDescription resources = 1;
}

// PermittedActionsRequest is a request message to Access.PermittedActions.
//
// Besides explicit fields in the message, there is an implicit parameter: the
// current identity which is defined by the "Authorization" OAuth 2.0 HTTP
// header and, optionally, LUCI-specific delegation token header.
message PermittedActionsRequest {
  // ResourceKind is one of Resource.kind values returned by Access.Description.
  // It identifies the type of the resource being checked.
  string resource_kind = 1;

  // ResourceIds identifies the resources presented on this service.
  // For example, for a buildbucket bucket it would be a bucket name
  // ("luci.chromium.try").
  // For a CIPD package it would be a full package name,
  // "infra/git/linux-amd64".
  repeated string resource_ids = 2;
}


// PermittedActionsResponse is the response message of the
// Accses.PermittedActions.
message PermittedActionsResponse {

  // ResourcePermissions describes what is permitted on a single resource.
  message ResourcePermissions {
    // Actions is a list of action ids that the user can do on the resource.
    // For resources that do not exist, this list must be empty.
    repeated string actions = 1;
  }

  // Permitted maps a resource id to resource permissions.
  map<string, ResourcePermissions> permitted = 1;

  // ValiditiyDuration specifies for how long clients may cache this
  // information.
  google.protobuf.Duration validity_duration = 2;
}