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, userId string, opt ...Option) (results ACLResults)
  • func (a ACL) ListPermissions(requestedScopes map[string]*scopes.ScopeInfo, requestedType resource.Type, ...) []Permission
• type ACLResults
• type AclGrant
  • func (a AclGrant) Actions() ([]action.Type, []string)
• type Grant
  • func Parse(ctx context.Context, scopeId, grantString string, opt ...Option) (Grant, error)
  • func (g Grant) Actions() ([]action.Type, []string)
  • func (g Grant) CanonicalString() string
  • func (g Grant) Id() string
  • func (g Grant) Ids() []string
  • func (g Grant) MarshalJSON(ctx context.Context) ([]byte, error)
  • func (g Grant) Type() resource.Type
• type GrantTuple
• type Option
  • func WithAccountId(accountId string) Option
  • func WithSkipAnonymousUserRestrictions(with bool) Option
  • func WithSkipFinalValidation(skipFinalValidation bool) Option
  • func WithUserId(userId string) Option
• type OutputFields
  • func (o *OutputFields) AddFields(input []string) *OutputFields
  • func (o *OutputFields) Fields() (fields []string, hasSetFields bool)
  • func (o *OutputFields) Has(in string) bool
  • func (o *OutputFields) SelfOrDefaults(userId string) *OutputFields
• type Permission
• type Resource
• type Scope
• type UserPermissions

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. Note that this converts the API-based Grants to AclGrants.

func (ACL) Allowed

func (a ACL) Allowed(r Resource, aType action.Type, userId string, opt ...Option) (results ACLResults)

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

func (ACL) ListPermissions

func (a ACL) ListPermissions(requestedScopes map[string]*scopes.ScopeInfo,
	requestedType resource.Type,
	idActions action.ActionSet,
	userId string,
) []Permission

ListPermissions builds a set of Permissions based on the grants in the ACL. Permissions are determined for the given resource for each of the provided scopes. There must be a grant for a given resource for one of the provided "id actions" or for action.All in order for a Permission to be created for the scope. The set of "id actions" is resource dependant, but will generally include all actions that can be taken on an individual resource.

type ACLResults

type ACLResults struct {
	AuthenticationFinished bool
	Authorized             bool
	OutputFields           *OutputFields
	// 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 AclGrant

type AclGrant struct {

	// The set of output fields granted
	OutputFields *OutputFields
	// contains filtered or unexported fields
}

AclGrant is used to decouple API-based grants from those we utilize for ACLs. Notably it uses a single ID per grant instead of multiple IDs.

func (AclGrant) Actions

func (a AclGrant) Actions() ([]action.Type, []string)

Actions returns the actions as a slice from the internal map, along with the string representations of those actions.

type Grant

type Grant struct {

	// The set of output fields granted
	OutputFields *OutputFields
	// contains filtered or unexported fields
}

Grant is a Go representation of a parsed grant

func Parse

func Parse(ctx context.Context, scopeId, grantString string, opt ...Option) (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() ([]action.Type, []string)

Actions returns the actions as a slice from the internal map, along with the string representations of those actions.

func (Grant) CanonicalString

func (g Grant) CanonicalString() string

CanonicalString returns the canonical representation of the grant

func (Grant) Id

func (g Grant) Id() string

Id returns the ID the grant refers to, if any

func (Grant) Ids

func (g Grant) Ids() []string

Ids returns the IDs the grant refers to, if any

func (Grant) MarshalJSON

func (g Grant) MarshalJSON(ctx context.Context) ([]byte, error)

MarshalJSON provides a custom marshaller for grants

func (Grant) Type

func (g Grant) Type() resource.Type

Type returns the type the grant refers to, or Unknown

type GrantTuple

type GrantTuple struct {
	RoleId  string
	ScopeId string
	Grant   string
}

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

type Option

type Option func(*options)

Option - how Options are passed as arguments

func WithAccountId

func WithAccountId(accountId string) Option

WithAccountId provides an account ID to be used for any templating in grant strings

func WithSkipAnonymousUserRestrictions

func WithSkipAnonymousUserRestrictions(with bool) Option

WithSkipAnonymousUserRestrictions allows skipping the restrictions on anonymous users, useful when e.g. validating parsed grants where we may not have a user ID yet.

func WithSkipFinalValidation

func WithSkipFinalValidation(skipFinalValidation bool) Option

WithSkipFinalValidation allows skipping the validity step where we ensure we can run a resource described by the grant successfully through the ACL check

func WithUserId

func WithUserId(userId string) Option

WithUserId provides a user ID to be used for any templating in grant strings

type OutputFields

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

OutputFields is used to store information about allowed output fields in grants

func (*OutputFields) AddFields

func (o *OutputFields) AddFields(input []string) *OutputFields

AddFields adds the given fields and returns the interface. It is safe to call this on a nil object, which will create a new object and add the fields to it; if relying on this make sure to assign to the output, e.g.:

outFields = outFields.AddFields([]string{"foo", "bar"})

Notes:

- Adding non-nil but empty input will be construed as "no fields"

- Fields compose, they do not overwrite; if you want to start over, create a new OutputFields struct

func (*OutputFields) Fields

func (o *OutputFields) Fields() (fields []string, hasSetFields bool)

Fields returns an alphabetical string slice of the fields in the map. The return value will be nil with hasSetFields false if fields are unset (e.g. we'd use the defaults in SelfOrDefaults), and non-nil (but empty if no fields are allowed) with hasSetFields true if fields have been configured. It is safe to call this on a nil object; it will return a nil slice and false for hasSetFields.

func (*OutputFields) Has

func (o *OutputFields) Has(in string) bool

Has returns true if the field should be allowed; that is, it is explicitly allowed, or the fields contains *. It is safe to call this on a nil object (it will always return false).

func (*OutputFields) SelfOrDefaults

func (o *OutputFields) SelfOrDefaults(userId string) *OutputFields

SelfOrDefaults returns either the output fields itself or the defaults for the given user. It is safe to call this on a nil object (it will always return defaults for the given user ID); if relying on this make sure to assign to the output, e.g.:

outFields = outFields.SelfOrDefaults("foo")

type Permission

type Permission struct {
	ScopeId  string // The scope id for which the permission applies.
	Resource resource.Type
	Action   action.Type

	ResourceIds []string // Any specific resource ids that have been referred in the grant's `id` field, if applicable.
	OnlySelf    bool     // The grant only allows actions against the user's own resources.
	All         bool     // We got a wildcard in the grant string's `id` field.
}

Permission provides information about the specific resources that a user has been granted access to for a given scope, resource, and action.

type Resource

type Resource struct {
	// ScopeId is the scope that contains the Resource.
	ScopeId string `json:"scope_id,omitempty"`

	// Id is the public id of the resource.
	Id string `json:"id,omitempty"`

	// Type of resource.
	Type resource.Type `json:"type,omitempty"`

	// Pin if defined would constrain the resource within the collection of the
	// pin id.
	Pin string `json:"pin,omitempty"`
}

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.

type UserPermissions

type UserPermissions struct {
	UserId      string
	Permissions []Permission
}

UserPermissions is a set of Permissions for a User.