perms

Documentation

Overview

Package perms provides the boundary permissions engine using grants which are tied to IAM Roles within a Scope.

A really useful page to be aware of when looking at ACLs is https://hashicorp.atlassian.net/wiki/spaces/ICU/pages/866976600/API+Actions+and+Permissions speaking of which: TODO: put that chart in public docs.

Anyways, from that page you can see that there are really only a few patterns of ACLs that are ever allowed:

* type=<resource.type>;actions=<action> * id=<resource.id>;actions=<action> * id=<pin>;type=<resource.type>;actions=<action>

and of course a matching scope.

This makes it actually quite simple to perform the ACL checking. Much of ACL construction is thus synthesizing something reasonable from a set of Grants.

Index

• type ACL
  • func NewACL(grants ...Grant) ACL
  • func (a ACL) Allowed(r Resource, aType action.Type) (results ACLResults)
• type ACLResults
• type Grant
  • func Parse(scopeId, userId, grantString string) (Grant, error)
  • func (g Grant) Actions() (typs []action.Type, strs []string)
  • func (g Grant) CanonicalString() string
  • func (g Grant) Id() string
  • func (g Grant) MarshalJSON() ([]byte, error)
  • func (g Grant) Type() resource.Type
• type GrantPair
• type Resource
• type Scope

Types

type ACL

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

ACL provides an entry point into the permissions engine for determining if an action is allowed on a resource based on a principal's (user or group) grants.

func NewACL

func NewACL(grants ...Grant) ACL

NewACL creates an ACL from the grants provided.

func (ACL) Allowed

func (a ACL) Allowed(r Resource, aType action.Type) (results ACLResults)

Allowed determines if the grants for an ACL allow an action for a resource.

type ACLResults

type ACLResults struct {
	Allowed bool
	// contains filtered or unexported fields
}

ACLResults provides a type for the permission's engine results so that we can pass more detailed information along in the future if we want. It was useful in Vault, may be useful here.

type Grant

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

Grant is a Go representation of a parsed grant

func Parse

func Parse(scopeId, userId, grantString string) (Grant, error)

Parse parses a grant string. Note that this does not do checking of the validity of IDs and such; that's left for other parts of the system. We may not check at all (e.g. let it be an authz-time failure) or could check after submission to catch errors.

The scope must be the org and project where this grant originated, not the request.

func (Grant) Actions

func (g Grant) Actions() (typs []action.Type, strs []string)

func (Grant) CanonicalString

func (g Grant) CanonicalString() string

CanonicalString returns the canonical representation of the grant

func (Grant) Id

func (g Grant) Id() string

func (Grant) MarshalJSON

func (g Grant) MarshalJSON() ([]byte, error)

MarshalJSON provides a custom marshaller for grants

func (Grant) Type

func (g Grant) Type() resource.Type

type GrantPair

type GrantPair struct {
	ScopeId string
	Grant   string
}

GrantPair is simply a struct that can be reference from other code to return a set of scopes and grants to parse

type Resource

type Resource struct {
	// ScopeId is the scope that contains the Resource.
	ScopeId string

	// Id is the public id of the resource.
	Id string

	// Type of resource.
	Type resource.Type

	// Pin if defined would constrain the resource within the collection of the
	// pin id.
	Pin string
}

Resource defines something within boundary that requires authorization capabilities. Resources must have a ScopeId.

type Scope

type Scope struct {
	// Id is the public id of the iam.Scope
	Id string

	// Type is the scope's type (org or project)
	Type scope.Type
}

Scope provides an in-memory representation of iam.Scope without the underlying storage references or capabilities.