Package realms contains functionality related to LUCI Realms.



    View Source
    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"


    This section is empty.


    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.


              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"