luci: go.chromium.org/luci/server/auth/realms Index | Files

package realms

import "go.chromium.org/luci/server/auth/realms"

Package realms contains functionality related to LUCI Realms.

Index

Package Files

doc.go permissions.go realms.go

Constants

const (
    // Root 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.
    Root = "@root"

    // Legacy 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.
    Legacy = "@legacy"
)

func Join Uses

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 Uses

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 Uses

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 Uses

func ValidateProjectName(project string) error

ValidateProjectName returns an error if the project name is not valid.

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

func ValidateRealmName Uses

func ValidateRealmName(realm string, scope RealmNameScope) error

ValidateRealmName returns an error if a realm name is not valid.

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 against `^[a-z0-9\-_]{1,100}$` (via ValidateProjectName).

type Permission Uses

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 Uses

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 Uses

func RegisteredPermissions() []Permission

RegisteredPermissions returns a snapshot of all registered permissions.

Permissions in the slice are ordered by their name.

func (Permission) Name Uses

func (p Permission) Name() string

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

func (Permission) String Uses

func (p Permission) String() string

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

type RealmNameScope Uses

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

Package realms imports 7 packages (graph) and is imported by 7 packages. Updated 2020-05-30. Refresh now. Tools for package owners.