Documentation

Overview

    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

    Constants

    This section is empty.

    Variables

    View Source
    var File_go_chromium_org_luci_common_proto_realms_realms_config_proto protoreflect.FileDescriptor

    Functions

    This section is empty.

    Types

    type Binding

    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

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

        Deprecated: Use Binding.ProtoReflect.Descriptor instead.

        func (*Binding) GetPrincipals

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

        func (*Binding) GetRole

        func (x *Binding) GetRole() string

        func (*Binding) ProtoMessage

        func (*Binding) ProtoMessage()

        func (*Binding) ProtoReflect

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

        func (*Binding) Reset

        func (x *Binding) Reset()

        func (*Binding) String

        func (x *Binding) String() string

        type CustomRole

        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

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

            Deprecated: Use CustomRole.ProtoReflect.Descriptor instead.

            func (*CustomRole) GetExtends

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

            func (*CustomRole) GetName

            func (x *CustomRole) GetName() string

            func (*CustomRole) GetPermissions

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

            func (*CustomRole) ProtoMessage

            func (*CustomRole) ProtoMessage()

            func (*CustomRole) ProtoReflect

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

            func (*CustomRole) Reset

            func (x *CustomRole) Reset()

            func (*CustomRole) String

            func (x *CustomRole) String() string

            type Realm

            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

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

                Deprecated: Use Realm.ProtoReflect.Descriptor instead.

                func (*Realm) GetBindings

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

                func (*Realm) GetEnforceInService

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

                func (*Realm) GetExtends

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

                func (*Realm) GetName

                func (x *Realm) GetName() string

                func (*Realm) ProtoMessage

                func (*Realm) ProtoMessage()

                func (*Realm) ProtoReflect

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

                func (*Realm) Reset

                func (x *Realm) Reset()

                func (*Realm) String

                func (x *Realm) String() string

                type RealmsCfg

                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

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

                    Deprecated: Use RealmsCfg.ProtoReflect.Descriptor instead.

                    func (*RealmsCfg) GetCustomRoles

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

                    func (*RealmsCfg) GetRealms

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

                    func (*RealmsCfg) ProtoMessage

                    func (*RealmsCfg) ProtoMessage()

                    func (*RealmsCfg) ProtoReflect

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

                    func (*RealmsCfg) Reset

                    func (x *RealmsCfg) Reset()

                    func (*RealmsCfg) String

                    func (x *RealmsCfg) String() string