luci: go.chromium.org/luci/common/proto/realms Index | Files

package realms

import "go.chromium.org/luci/common/proto/realms"

Package realms contains LUCI Realms protobuf definitions.

Copied from:

Repo: https://chromium.googlesource.com/infra/luci/luci-py/ Revision: d5e72d070990966aea8d0d8d405b32fb3fdbbb4d Path: appengine/auth_service/proto/realms_config.proto

Modification: added luci.file_metadata annotation.

Index

Package Files

generate.go realms_config.pb.go

Variables

var File_go_chromium_org_luci_common_proto_realms_realms_config_proto protoreflect.FileDescriptor

type Binding Uses

type Binding struct {

    // Name of the role to assign.
    //
    // Can either be a predefined role (if starts with "role/") or a custom role
    // (if starts with "customRole/"). See TODO for a list of predefined roles
    // and their meanings.
    //
    // A custom role must be defined somewhere in this realms.cfg file.
    Role string `protobuf:"bytes,1,opt,name=role,proto3" json:"role,omitempty"`
    // A set of principals to assign the role to.
    //
    // Each entry can either be an identity string (like "user:<email>") or a
    // LUCI group reference "group:<name>".
    Principals []string `protobuf:"bytes,2,rep,name=principals,proto3" json:"principals,omitempty"`
    // contains filtered or unexported fields
}

Binding assigns a role to all specified principals.

func (*Binding) Descriptor Uses

func (*Binding) Descriptor() ([]byte, []int)

Deprecated: Use Binding.ProtoReflect.Descriptor instead.

func (*Binding) GetPrincipals Uses

func (x *Binding) GetPrincipals() []string

func (*Binding) GetRole Uses

func (x *Binding) GetRole() string

func (*Binding) ProtoMessage Uses

func (*Binding) ProtoMessage()

func (*Binding) ProtoReflect Uses

func (x *Binding) ProtoReflect() protoreflect.Message

func (*Binding) Reset Uses

func (x *Binding) Reset()

func (*Binding) String Uses

func (x *Binding) String() string

type CustomRole Uses

type CustomRole struct {

    // Name of this custom role, must start with "customRole/".
    Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
    // Optional list of roles whose permissions will be included in this role.
    //
    // Each entry can either be a predefined role (if starts with "role/") or
    // another custom role defined in this realms.cfg (if starts with
    // "customRole/").
    //
    // To keep the mental model simple, cycles aren't allowed (i.e. a custom role
    // is not allowed to directly or indirectly extend itself). The LUCI Config
    // service will reject realms.cfg that contains cycles during the config
    // validation phase.
    Extends []string `protobuf:"bytes,2,rep,name=extends,proto3" json:"extends,omitempty"`
    // Optional list of permissions to include in the role.
    //
    // Each permission is a symbol that has form "<service>.<subject>.<verb>",
    // which describes some elementary action ("<verb>") that can be done to some
    // category of resources ("<subject>"), managed by some particular kind of
    // LUCI service ("<service>").
    //
    // Examples of permissions:
    //   * buildbucket.build.create
    //   * swarming.pool.listBots
    //   * swarming.task.cancel
    //
    // See TODO for a list of all possible permissions.
    Permissions []string `protobuf:"bytes,3,rep,name=permissions,proto3" json:"permissions,omitempty"`
    // contains filtered or unexported fields
}

Custom role defines a custom named set of permissions.

Can be used in bindings if predefined roles are too broad or do not map well to the desired set of permissions.

Custom roles are scoped to the project (i.e. different projects may have identically named, but semantically different custom roles).

func (*CustomRole) Descriptor Uses

func (*CustomRole) Descriptor() ([]byte, []int)

Deprecated: Use CustomRole.ProtoReflect.Descriptor instead.

func (*CustomRole) GetExtends Uses

func (x *CustomRole) GetExtends() []string

func (*CustomRole) GetName Uses

func (x *CustomRole) GetName() string

func (*CustomRole) GetPermissions Uses

func (x *CustomRole) GetPermissions() []string

func (*CustomRole) ProtoMessage Uses

func (*CustomRole) ProtoMessage()

func (*CustomRole) ProtoReflect Uses

func (x *CustomRole) ProtoReflect() protoreflect.Message

func (*CustomRole) Reset Uses

func (x *CustomRole) Reset()

func (*CustomRole) String Uses

func (x *CustomRole) String() string

type Realm Uses

type Realm struct {

    // Name of the realm.
    //
    // Must match `^[a-z0-9_\.\-/]{1,400}$` or be literals "@root" or "@legacy".
    //
    // Realm names must be unique within a project.
    Name string `protobuf:"bytes,1,opt,name=name,proto3" json:"name,omitempty"`
    // Optional list of realms whose permissions will be included in this realm.
    //
    // All realms implicitly extend "@root" realm (if it is defined), i.e. all
    // permissions specified in the "@root" realm are propagated to all realms in
    // the project.
    //
    // To keep the mental model simple, cycles aren't allowed (i.e. a realm is not
    // allowed to directly or indirectly extend itself). The LUCI Config service
    // will reject realms.cfg that contains cycles during the config validation
    // phase.
    Extends []string `protobuf:"bytes,2,rep,name=extends,proto3" json:"extends,omitempty"`
    // List of bindings that define who can do what to resources in this realm.
    Bindings []*Binding `protobuf:"bytes,3,rep,name=bindings,proto3" json:"bindings,omitempty"`
    // A list of LUCI service IDs that should enforce this realm's permissions.
    //
    // Children realms inherit and extend this list.
    //
    // Used only during Realms migration to gradually roll out the enforcement
    // realm by realm, service by service.
    EnforceInService []string `protobuf:"bytes,4,rep,name=enforce_in_service,json=enforceInService,proto3" json:"enforce_in_service,omitempty"`
    // contains filtered or unexported fields
}

Realm is a named container for (<principal>, <permission>) pairs.

A LUCI resource can point to exactly one realm by referring to its full name ("<project>:<realm>"). We say that such resource "belongs to the realm" or "lives in the realm" or is just "in the realm". We also say that such resource belongs to the project "<project>". The corresponding Realm message then describes who can do what to the resource.

The logic of how resources get assigned to realms is a part of the public API of the service that owns resources. Some services may use a static realm assignment via project configuration files, others may do it dynamically by accepting a realm when a resource is created via an RPC.

A realm can "extend" one or more other realms. If a realm `A` extends `B`, then all permissions defined in `B` are also in `A`. Remembering that a realm is just a set of (<principal>, <permission>) pairs, the "extend" relation is just a set inclusion.

The primary way of populating the permission set of a realm is via bindings. Each binding assigns a role to a set of principals. Since each role is essentially just a set of permissions, each binding adds to the realm a Cartesian product of a set of permissions (defined via the role) and a set of principals (defined via a direct listing or via groups).

There are two special realms (both optional) that a project can have: "@root" and "@legacy".

The root realm is implicitly included into all other realms (including "@legacy"), and it is also used as a fallback when a resource points to a realm that no longer exists. Without the root realm, such resources become effectively inaccessible and this may be undesirable. Permissions in the root realm apply to all realms in the project (current, past and future), and thus the root realm should contain only administrative-level bindings. If you are not sure whether you should use the root realm or not, err on the side of not using it.

The legacy realm is used for existing resources created before the realms mechanism was introduced. Such resources usually are not associated with any realm at all. They are implicitly placed into the legacy realm to allow reusing realms' machinery for them.

Note that the details of how resources are placed in the legacy realm are up to a particular service implementation. Some services may be able to figure out an appropriate realm for a legacy resource based on resource's existing attributes. Some services may not have legacy resources at all. The legacy realm is not used in these case. Refer to the service documentation.

A realm can also carry some small amount of data (usually auth related) that LUCI services use when dealing with this realm. It should be something that all (or at least more than one) LUCI services use. Configuration specific to a single service should be in this service's project config instead.

func (*Realm) Descriptor Uses

func (*Realm) Descriptor() ([]byte, []int)

Deprecated: Use Realm.ProtoReflect.Descriptor instead.

func (*Realm) GetBindings Uses

func (x *Realm) GetBindings() []*Binding

func (*Realm) GetEnforceInService Uses

func (x *Realm) GetEnforceInService() []string

func (*Realm) GetExtends Uses

func (x *Realm) GetExtends() []string

func (*Realm) GetName Uses

func (x *Realm) GetName() string

func (*Realm) ProtoMessage Uses

func (*Realm) ProtoMessage()

func (*Realm) ProtoReflect Uses

func (x *Realm) ProtoReflect() protoreflect.Message

func (*Realm) Reset Uses

func (x *Realm) Reset()

func (*Realm) String Uses

func (x *Realm) String() string

type RealmsCfg Uses

type RealmsCfg struct {

    // List of all realms in the project in arbitrary order.
    Realms []*Realm `protobuf:"bytes,1,rep,name=realms,proto3" json:"realms,omitempty"`
    // Optional list of custom roles that can be referenced from Bindings in this
    // project.
    CustomRoles []*CustomRole `protobuf:"bytes,2,rep,name=custom_roles,json=customRoles,proto3" json:"custom_roles,omitempty"`
    // contains filtered or unexported fields
}

RealmsCfg defines a schema for realms.cfg project configuration file.

func (*RealmsCfg) Descriptor Uses

func (*RealmsCfg) Descriptor() ([]byte, []int)

Deprecated: Use RealmsCfg.ProtoReflect.Descriptor instead.

func (*RealmsCfg) GetCustomRoles Uses

func (x *RealmsCfg) GetCustomRoles() []*CustomRole

func (*RealmsCfg) GetRealms Uses

func (x *RealmsCfg) GetRealms() []*Realm

func (*RealmsCfg) ProtoMessage Uses

func (*RealmsCfg) ProtoMessage()

func (*RealmsCfg) ProtoReflect Uses

func (x *RealmsCfg) ProtoReflect() protoreflect.Message

func (*RealmsCfg) Reset Uses

func (x *RealmsCfg) Reset()

func (*RealmsCfg) String Uses

func (x *RealmsCfg) String() string

Package realms imports 6 packages (graph) and is imported by 2 packages. Updated 2020-10-28. Refresh now. Tools for package owners.