auth_service/api/rpcpb/groups.proto

// Copyright 2021 The LUCI Authors.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//      http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

syntax = "proto3";

package auth.service;

option go_package = "go.chromium.org/luci/auth_service/api/rpcpb";

import "google/api/field_behavior.proto";
import "google/protobuf/empty.proto";
import "google/protobuf/field_mask.proto";
import "google/protobuf/timestamp.proto";

// Groups service contains methods to examine groups.
service Groups {
  // ListGroups returns all the groups in the AuthDB.
  // The groups will be returned in alphabetical order based on their
  // ID.
  rpc ListGroups(ListGroupsRequest) returns (ListGroupsResponse);

  // GetGroup returns information about an individual group, given the name.
  rpc GetGroup(GetGroupRequest) returns (AuthGroup);

  // CreateGroup creates a new group.
  rpc CreateGroup(CreateGroupRequest) returns (AuthGroup);

  // UpdateGroup updates an existing group.
  rpc UpdateGroup(UpdateGroupRequest) returns (AuthGroup);

  // DeleteGroup deletes a group.
  rpc DeleteGroup(DeleteGroupRequest) returns (google.protobuf.Empty);

  // GetSubgraph returns a Subgraph without information about groups that
  // include a principal (perhaps indirectly or via globs). Here a principal is
  // either an identity, a group or a glob (see PrincipalKind enum).
  rpc GetSubgraph(GetSubgraphRequest) returns (Subgraph);

  // GetExpandedGroup returns the requested AuthGroup, with subgroups fully
  // expanded, i.e.
  // - `members` will include direct and indirect members;
  // - `globs` will include direct and indirect globs; and
  // - `nested` will include direct and indirect subgroups.
  rpc GetExpandedGroup(GetGroupRequest) returns (AuthGroup);
}

message ListGroupsRequest {
  // Setting this flag will ensure the returned groups will be from a fresh
  // snapshot of all groups. Otherwise, a cached result may be returned.
  bool fresh = 1;
}

// ListGroupsResponse is all the groups listed in LUCI Auth Service.
message ListGroupsResponse {
  // List of all groups. In order to keep the response lightweight, each
  // AuthGroup will contain only metadata, i.e. the membership list fields will
  // be left empty.
  repeated AuthGroup groups = 1;
}

// GetGroupRequest is to specify an individual group.
message GetGroupRequest {
  string name = 1;  // e.g: "administrators"
}

// CreateGroupRequest requests the creation of a new group.
message CreateGroupRequest {
  // Details of the group to create. Not all fields will be written to the new
  // group: if the request specifies fields that should be automatically
  // generated (e.g. created/modified timestamps), these will be ignored.
  AuthGroup group = 1 [ (google.api.field_behavior) = REQUIRED ];
}

// UpdateGroupRequest requests an update to an existing group.
message UpdateGroupRequest {
  // Details of the group to update. The group's 'name' field is used to
  // identify the group to update.
  AuthGroup group = 1 [ (google.api.field_behavior) = REQUIRED ];

  // The list of fields to be updated.
  google.protobuf.FieldMask update_mask = 2;
}

// DeleteGroupRequest requests the deletion of a group.
message DeleteGroupRequest {
  // Name of the group to delete.
  string name = 1 [ (google.api.field_behavior) = REQUIRED ];

  // The current etag of the group.
  // If an etag is provided and does not match the current etag of the group,
  // deletion will be blocked and an ABORTED error will be returned.
  string etag = 2;
}

// AuthGroup defines an individual group.
message AuthGroup {
  string name = 1;              // e.g: "auth-service-access"
  repeated string members = 2;  // e.g: ["user:t@example.com"]
  repeated string globs = 3;    // e.g: ["user:*@example.com"
  repeated string nested = 4;   // e.g: ["another-group-0", "another-group-1"]
  string description = 5;       // e.g: "This group is used for ..."
  string owners = 6;            // e.g: "administrators"
  google.protobuf.Timestamp created_ts = 7;  // e.g: "1972-01-01T10:00:20.021Z"
  string created_by = 8;                     // e.g: "user:test@example.com"

  // Output only. Whether the caller can modify this group.
  bool caller_can_modify = 9 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Output only. Whether the caller can view member emails.
  bool caller_can_view_members = 10 [(google.api.field_behavior) = OUTPUT_ONLY];

  // Number of member emails redacted, if any.
  int32 num_redacted = 11;

  // An opaque string that indicates the version of the group being edited.
  // This will be sent to the client in responses, and should be sent back
  // to the server for update and delete requests in order to protect against
  // concurrent modification errors. See https://google.aip.dev/154.
  // Technically this is a "weak etag", meaning that if two AuthGroups have the
  // same etag, they are not guaranteed to be byte-for-byte identical. This is
  // because under the hood we generate it based on the last-modified time
  // (though this should not be relied on as it may change in future).
  string etag = 99;
}

// GetSubgraphRequest contains the Principal that is the basis of the search
// for inclusion and is the root of the output subgraph.
message GetSubgraphRequest {
  Principal principal = 1;
}

// The Subgraph returned by GetSubgraph RPC.
//
// The node representing a principal passed to GetSubgraph is always the
// first in the list.
message Subgraph {
  repeated Node nodes = 1;
}

// PrincipalKind denotes the type of principal of a specific entity.
enum PrincipalKind {
  PRINCIPAL_KIND_UNSPECIFIED = 0;
  // A single individual identity, e.g. "user:someone@example.com".
  IDENTITY = 1;
  // A group name, e.g. "some-group".
  GROUP = 2;
  // An identity glob, e.g. "user*@example.com".
  GLOB = 3;
}

// Principal is an entity that can be found in the Subgraph. A Principal can
// represent a group, identity, or glob. See PrincipalKind for clarification on
// how each Principal kind is represented.
message Principal {
  PrincipalKind kind = 1;  // e.g. IDENTITY, GROUP, GLOB
  string name = 2;  // e.g. "user*@example.com", "some-group", "user:m0@example.com"
}

// Each Node is a representation of a Principal.
// Each subgraph will only contain one Node per principal; in other words,
// a principal uniquely identifies a Node.
message Node {
  // The principal represented by this node.
  Principal principal = 1;
  // Nodes that directly include this principal.
  //
  // Each item is an index of a Node in Subgraph's `nodes` list.
  repeated int32 included_by = 2;
}