realms

package
v0.0.0-...-add0f8d Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Nov 22, 2024 License: Apache-2.0 Imports: 5 Imported by: 1

Documentation

Overview

Package realms contains LUCI Realms protobuf definitions.

Copied from:

Repo: https://chromium.googlesource.com/infra/luci/luci-py/ Revision: ce8d5d5b7bf677374051555ab67832d46531330d 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"`
	// A list of conditions ANDed together that define when the binding is active.
	//
	// If empty, the binding is active all the time.
	Conditions []*Condition `protobuf:"bytes,3,rep,name=conditions,proto3" json:"conditions,omitempty"`
	// contains filtered or unexported fields
}

Binding assigns a role to all specified principals.

func (*Binding) Descriptor deprecated 

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

Deprecated: Use Binding.ProtoReflect.Descriptor instead.

func (*Binding) GetConditions 

func (x *Binding) GetConditions() []*Condition

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 Condition 

type Condition struct {

	// Types that are assignable to Op:
	//
	//	*Condition_Restrict
	Op isCondition_Op `protobuf_oneof:"op"`
	// contains filtered or unexported fields
}

Condition defines a predicate that takes a set of `attribute = value` pairs with a context of a particular permission check and returns True if the binding guarded by this conditions should be respected.

When a service checks a permission, it passes to the authorization library a string-valued dictionary of attributes that describes the context of the permission check. It contains things like the name of the resource being accessed, or parameters of the incoming RPC request that triggered the check.

A list of available attributes and meaning of their values depends on the permission being checked and is documented in the corresponding service documentation.

func (*Condition) Descriptor deprecated 

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

Deprecated: Use Condition.ProtoReflect.Descriptor instead.

func (*Condition) GetOp 

func (m *Condition) GetOp() isCondition_Op

func (*Condition) GetRestrict 

func (x *Condition) GetRestrict() *Condition_AttributeRestriction

func (*Condition) ProtoMessage 

func (*Condition) ProtoMessage()

func (*Condition) ProtoReflect 

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

func (*Condition) Reset 

func (x *Condition) Reset()

func (*Condition) String 

func (x *Condition) String() string

type Condition_AttributeRestriction 

type Condition_AttributeRestriction struct {
	Attribute string   `protobuf:"bytes,1,opt,name=attribute,proto3" json:"attribute,omitempty"`
	Values    []string `protobuf:"bytes,2,rep,name=values,proto3" json:"values,omitempty"`
	// contains filtered or unexported fields
}

AttributeRestriction checks that the attributes set (as a set of key-value pairs) contains a particular (attribute, value) pair. Checked values are given as a list. The check succeeds if ANY of (attribute, value) pairs are present: `any((attribute, value) in attrs for value in values)`.

func (*Condition_AttributeRestriction) Descriptor deprecated 

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

Deprecated: Use Condition_AttributeRestriction.ProtoReflect.Descriptor instead.

func (*Condition_AttributeRestriction) GetAttribute 

func (x *Condition_AttributeRestriction) GetAttribute() string

func (*Condition_AttributeRestriction) GetValues 

func (x *Condition_AttributeRestriction) GetValues() []string

func (*Condition_AttributeRestriction) ProtoMessage 

func (*Condition_AttributeRestriction) ProtoMessage()

func (*Condition_AttributeRestriction) ProtoReflect 

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

func (*Condition_AttributeRestriction) Reset 

func (x *Condition_AttributeRestriction) Reset()

func (*Condition_AttributeRestriction) String 

func (x *Condition_AttributeRestriction) String() string

type Condition_Restrict 

type Condition_Restrict struct {
	Restrict *Condition_AttributeRestriction `protobuf:"bytes,1,opt,name=restrict,proto3,oneof"`
}

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 deprecated 

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 deprecated 

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 deprecated 

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

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.