realms

Documentation

Overview

Package realms contains functionality related to LUCI Realms.

Index

• Constants
• func Join(project, realm string) (global string)
• func Split(global string) (project, realm string)
• func ValidatePermissionName(name string) error
• func ValidateProjectName(project string) error
• func ValidateRealmName(realm string, scope RealmNameScope) error
• type Permission
  • func RegisterPermission(name string) Permission
  • func RegisteredPermissions() []Permission
  • func (p Permission) Name() string
  • func (p Permission) String() string
• type RealmNameScope

Constants

const (
	// InternalProject is an alias for "@internal".
	//
	// There's a special set of realms (called internal realms or, sometimes,
	// global realms) that are defined in realms.cfg in the LUCI Auth service
	// config set. They are not part of any particular LUCI project. Their full
	// name have form "@internal:<realm>".
	InternalProject = "@internal"

	// RootRealm is an alias for "@root".
	//
	// 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.
	//
	// HasPermission() automatically falls back to corresponding root realms if
	// any of the realms it receives do not exist. You still can pass a root realm
	// to HasPermission() if you specifically want to check the root realm
	// permissions.
	RootRealm = "@root"

	// LegacyRealm is an alias for "@legacy".
	//
	// The legacy realm should be used for legacy resources created before the
	// realms mechanism was introduced in case the service can't figure out a more
	// appropriate realm based on resource's properties. The service must clearly
	// document when and how it uses the legacy realm (if it uses it at all).
	//
	// Unlike the situation with root realms, HasPermission() has no special
	// handling of legacy realms. You should always pass them to HasPermission()
	// explicitly when checking permissions of legacy resources.
	LegacyRealm = "@legacy"
)

Functions

func Join

func Join(project, realm string) (global string)

Join returns "<project>:<realm>".

Doesn't validate the result. If this is a concern, use ValidateRealmName explicitly.

func Split

func Split(global string) (project, realm string)

Split splits a global realm name "<project>:<realm>" into its components.

Panics if `global` doesn't have ":". Doesn't validate the resulting components. If this is a concern, use ValidateRealmName explicitly.

func ValidatePermissionName

func ValidatePermissionName(name string) error

ValidatePermissionName returns an error if the permission name is invalid.

It checks the name looks like "<service>.<subject>.<verb>".

func ValidateProjectName

func ValidateProjectName(project string) error

ValidateProjectName validates a project portion of a full realm name.

It should match `^[a-z0-9\-_]{1,100}$` or be "@internal".

func ValidateRealmName

func ValidateRealmName(realm string, scope RealmNameScope) error

ValidateRealmName validates a realm name (either full or project-scoped).

If `scope` is GlobalScope, `realm` is expected to have the form "<project>:<realm>". If `scope` is ProjectScope, `realm` is expected to have the form "<realm>". Any other values of `scope` cause panics.

In either case "<realm>" is tested against `^[a-z0-9_\.\-/]{1,400}$` and compared to literals "@root" and "@legacy".

When validating globally scoped names, "<project>" is tested using ValidateProjectName.

Types

type Permission

type Permission struct {
	// contains filtered or unexported fields
}

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>").

Each individual LUCI service should document what permissions it checks and when. It becomes a part of service's public API. Usually services should check only permissions of resources they own (e.g. "<service>.<subject>.*"), but in exceptional cases they may also check permissions intended for other services. This is primarily useful for services that somehow "proxy" access to resources.

func RegisterPermission

func RegisterPermission(name string) Permission

RegisterPermission adds a new permission with the given name to the process registry or returns an existing one.

Panics if the permission name doesn't look like "<service>.<subject>.<verb>".

Intended to be called during init() time, but may be called later too.

func RegisteredPermissions

func RegisteredPermissions() []Permission

RegisteredPermissions returns a snapshot of all registered permissions.

Permissions in the slice are ordered by their name.

func (Permission) Name

func (p Permission) Name() string

Name is "<service>.<subject>.<verb>" string.

func (Permission) String

func (p Permission) String() string

String allows permissions to be used as "%s" in format strings.

type RealmNameScope

type RealmNameScope string

RealmNameScope specifies how realm names are scoped for ValidateRealmName.

const (
	// GlobalScope indicates the realm name is not scoped to a project.
	//
	// E.g. it is "<project>:<realm>".
	GlobalScope RealmNameScope = "global"

	// ProjectScope indicates the realm name is scoped to some project.
	//
	// E.g. it is just "<realm>" (instead of "<project>:<realm>").
	ProjectScope RealmNameScope = "project-scoped"
)