iapl

Documentation

Overview

Package iapl contains functions and data for the Infratographer Authorization Policy Language, a domain-specific language for defining authorization policies based on resource relationships.

Index

• Constants
• Variables
• type Action
• type ActionBinding
• type Condition
• type ConditionRelationshipAction
• type ConditionRoleBinding
• type ConditionRoleBindingV2
• type Policy
  • func DefaultPolicy() Policy
  • func NewPolicy(p PolicyDocument) Policy
  • func NewPolicyFromDirectory(directoryPath string) (Policy, error)
  • func NewPolicyFromFile(filePath string) (Policy, error)
  • func NewPolicyFromFiles(filePaths []string) (Policy, error)
• type PolicyDocument
  • func DefaultPolicyDocument() PolicyDocument
  • func LoadPolicyDocumentFromDirectory(directoryPath string) (PolicyDocument, error)
  • func LoadPolicyDocumentFromFiles(filePaths ...string) (PolicyDocument, error)
  • func (p PolicyDocument) MergeWithPolicyDocument(other PolicyDocument) PolicyDocument
• type RBAC
  • func (r *RBAC) CreateRoleBindingActionsForResource(inheritFrom ...string) []types.Action
  • func (r *RBAC) CreateRoleBindingConditionsForAction(actionName string, inheritFrom ...string) []types.Condition
  • func (r *RBAC) RoleBindingActions() []Action
  • func (r *RBAC) RoleOwnersSet() map[string]struct{}
• type RBACResourceDefinition
• type Relationship
• type ResourceRoleBindingV2
• type ResourceType
• type RoleAction
• type RoleBindingAction
• type Union

Constants

const (
	// RoleOwnerRelation is the name of the relationship that connects a role to its owner.
	RoleOwnerRelation = "owner"
	// RoleOwnerMemberRoleRelation is the name of the relationship that connects a resource
	// to a role that it owns
	RoleOwnerMemberRoleRelation = "member_role"
	// AvailableRolesList is the name of the action in a resource that returns a list
	// of roles that are available for the resource
	AvailableRolesList = "avail_role"
	// RolebindingRoleRelation is the name of the relationship that connects a role binding to a role.
	RolebindingRoleRelation = "role"
	// RolebindingSubjectRelation is the name of the relationship that connects a role binding to a subject.
	RolebindingSubjectRelation = "subject"
	// RoleOwnerParentRelation is the name of the relationship that connects a role's owner to its parent.
	RoleOwnerParentRelation = "parent"
	// PermissionRelationSuffix is the suffix append to the name of the relationship
	// representing a permission in a role
	PermissionRelationSuffix = "_rel"
	// GrantRelationship is the name of the relationship that connects a role binding to a resource.
	GrantRelationship = "grant"
)

Variables

var (
	// ErrorTypeExists represents an error where a duplicate type or union was declared.
	ErrorTypeExists = errors.New("type already exists")
	// ErrorActionBindingExists represents an error where a duplicate binding between a type and action was declared.
	ErrorActionBindingExists = errors.New("action binding already exists")
	// ErrorUnknownType represents an error where a resource type is unknown in the authorization policy.
	ErrorUnknownType = errors.New("unknown resource type")
	// ErrorInvalidCondition represents an error where an action binding condition is invalid.
	ErrorInvalidCondition = errors.New("invalid condition")
	// ErrorUnknownRelation represents an error where a relation is not defined for a resource type.
	ErrorUnknownRelation = errors.New("unknown relation")
	// ErrorUnknownAction represents an error where an action is not defined.
	ErrorUnknownAction = errors.New("unknown action")
	// ErrorMissingRelationship represents an error where a mandatory relationship is missing.
	ErrorMissingRelationship = errors.New("missing relationship")
	// ErrorDuplicateRBACDefinition represents an error where a duplicate RBAC definition was declared.
	ErrorDuplicateRBACDefinition = errors.New("duplicated RBAC definition")
)

Types

type Action

type Action struct {
	Name string
}

Action represents an action that can be taken in an authorization policy.

type ActionBinding

type ActionBinding struct {
	ActionName    string
	TypeName      string
	Conditions    []Condition
	ConditionSets []types.ConditionSet
}

ActionBinding represents a binding of an action to a resource type or union.

type Condition

type Condition struct {
	RoleBinding        *ConditionRoleBinding
	RoleBindingV2      *ConditionRoleBindingV2
	RelationshipAction *ConditionRelationshipAction
}

Condition represents a necessary condition for performing an action.

type ConditionRelationshipAction

type ConditionRelationshipAction struct {
	Relation   string
	ActionName string
}

ConditionRelationshipAction represents a condition where another action must be allowed on a resource along a relation to perform an action.

type ConditionRoleBinding

type ConditionRoleBinding struct{}

ConditionRoleBinding represents a condition where a role binding is necessary to perform an action.

type ConditionRoleBindingV2

type ConditionRoleBindingV2 struct{}

ConditionRoleBindingV2 represents a condition where a role binding is necessary to perform an action. Using this condition type in the policy will instruct the policy engine to create all the necessary relationships in the schema to support RBAC V2

type Policy

type Policy interface {
	Validate() error
	Schema() []types.ResourceType
	RBAC() *RBAC
}

Policy represents an authorization policy as defined by IAPL.

func DefaultPolicy

func DefaultPolicy() Policy

DefaultPolicy generates the default policy for permissions-api.

func NewPolicy

func NewPolicy(p PolicyDocument) Policy

NewPolicy creates a policy from the given policy document.

func NewPolicyFromDirectory

func NewPolicyFromDirectory(directoryPath string) (Policy, error)

NewPolicyFromDirectory reads the provided directory path, reads all files in the directory, merges them, and returns a new Policy.

func NewPolicyFromFile

func NewPolicyFromFile(filePath string) (Policy, error)

NewPolicyFromFile reads the provided file path and returns a new Policy.

func NewPolicyFromFiles

func NewPolicyFromFiles(filePaths []string) (Policy, error)

NewPolicyFromFiles reads the provided file paths, merges them, and returns a new Policy.

type PolicyDocument

type PolicyDocument struct {
	ResourceTypes  []ResourceType
	Unions         []Union
	Actions        []Action
	ActionBindings []ActionBinding
	RBAC           *RBAC
}

PolicyDocument represents a partial authorization policy.

func DefaultPolicyDocument

func DefaultPolicyDocument() PolicyDocument

DefaultPolicyDocument returns the default policy document for permissions-api.

func LoadPolicyDocumentFromDirectory

func LoadPolicyDocumentFromDirectory(directoryPath string) (PolicyDocument, error)

LoadPolicyDocumentFromDirectory reads the provided directory path, reads all files in the directory, merges them, and returns a new merged PolicyDocument. Directories beginning with "." are skipped.

func LoadPolicyDocumentFromFiles

func LoadPolicyDocumentFromFiles(filePaths ...string) (PolicyDocument, error)

LoadPolicyDocumentFromFiles loads all policy documents in the order provided and returns a merged PolicyDocument.

func (PolicyDocument) MergeWithPolicyDocument

func (p PolicyDocument) MergeWithPolicyDocument(other PolicyDocument) PolicyDocument

MergeWithPolicyDocument merges this document with another, returning the new PolicyDocument.

type RBAC

type RBAC struct {
	// RoleResource is the name of the resource type that represents a role.
	RoleResource RBACResourceDefinition
	// RoleBindingResource is the name of the resource type that represents a role binding.
	RoleBindingResource RBACResourceDefinition
	// RoleSubjectTypes is a list of subject types that the relationships in a
	// role resource will contain, see the example above.
	RoleSubjectTypes []string
	// RoleOwners is the list of resource types that can own a role.
	// These resources should be (but not limited to) organizational resources
	// like tenant, organization, project, group, etc
	// When a role is owned by an entity, say a group, that means this role
	// will be available to perform role-bindings for resources that are owned
	// by this group and its subgroups.
	// The RoleOwners relationship is particularly useful to limit access to
	// custom roles.
	RoleOwners []string
	// RoleBindingSubjects is the names of the resource types that can be subjects in a role binding.
	// e.g. rolebinding_create, rolebinding_list, rolebinding_delete
	RoleBindingSubjects []types.TargetType
	// contains filtered or unexported fields
}

RBAC represents a role-based access control policy.

For example, consider the following spicedb schema: ```zed

definition user {}
definition client {}

definition group {
	relation member: user | client
}

definition organization {
	relation parent: organization
	relation member: user | client
	relation member_role: role
	relation grant: rolebinding

	permissions rolebinding_list: grant->rolebinding_list
	permissions rolebinding_create: grant->rolebinding_create
	permissions rolebinding_delete: grant->rolebinding_delete
}

definition role {
	relation owner: organization
	relation view_organization: user:* | client:*
	relation rolebinding_list_rel: user:* | client:*
	relation rolebinding_create_rel: user:* | client:*
	relation rolebinding_delete_rel: user:* | client:*
}

definition rolebinding {
	relation role: role
	relation subject: user | group#member
	permission view_organization = subject & role->view_organization
	permissions rolebinding_list: subject & role->rolebinding_list
	permissions rolebinding_create: subject & role->rolebinding_create
	permissions rolebinding_delete: subject & role->rolebinding_delete
}

``` in IAPL policy terms: - the RoleResource would be "{name: role, idprefix: someprefix}" - the RoleBindingResource would be "{name: rolebinding, idprefix: someprefix}", - the RoleRelationshipSubject would be `[user, client]`. - the RoleBindingSubjects would be `[{name: user}, {name: group, subjectrelation: member}]`.

func (*RBAC) CreateRoleBindingActionsForResource

func (r *RBAC) CreateRoleBindingActionsForResource(inheritFrom ...string) []types.Action

CreateRoleBindingActionsForResource should be used when an RBAC V2 condition is created for an action, the resource that the action is belong to must support role binding V2. This function creates the list of actions that can be performed on a role binding resource. e.g. If action `read_doc` is created with RBAC V2 condition, then the resource, in this example `doc`, must also support actions like `rolebinding_create`.

func (*RBAC) CreateRoleBindingConditionsForAction

func (r *RBAC) CreateRoleBindingConditionsForAction(actionName string, inheritFrom ...string) []types.Condition

CreateRoleBindingConditionsForAction creates the conditions that is used for role binding v2, for a given action name. e.g. for a doc_read action, it will create the following conditions: doc_read = grant->doc_read + from[0]->doc_read + ... from[n]->doc_read

func (*RBAC) RoleBindingActions

func (r *RBAC) RoleBindingActions() []Action

RoleBindingActions returns the list of actions that can be performed on a role resource plus the AvailableRoleRelation action that is used to decide whether or not a role is available for a resource

func (*RBAC) RoleOwnersSet

func (r *RBAC) RoleOwnersSet() map[string]struct{}

RoleOwnersSet returns the set of role owners for easy role owner lookups

type RBACResourceDefinition

type RBACResourceDefinition struct {
	Name     string
	IDPrefix string
}

RBACResourceDefinition is a struct to define a resource type for a role and role-bindings

type Relationship

type Relationship struct {
	Relation    string
	TargetTypes []types.TargetType
}

Relationship represents a named relation between two resources.

type ResourceRoleBindingV2

type ResourceRoleBindingV2 struct {
	// InheritPermissionsFrom is the list of resource types that can provide roles
	// and grants to this resource
	// Note that not all roles are available to all resources. This relationship is used to
	// determine which roles are available to a resource.
	// Before creating a role binding for a resource, one should check whether or
	// not the role is available for the resource.
	//
	// Also see the RoleOwners field in the RBAC struct
	InheritPermissionsFrom []string

	// InheritAllActions adds relationship action lookups for all actions, not just role binding actions.
	InheritAllActions bool
}

ResourceRoleBindingV2 describes the relationships that will be created for a resource to support role-binding V2

type ResourceType

type ResourceType struct {
	Name          string
	IDPrefix      string
	RoleBindingV2 *ResourceRoleBindingV2
	Relationships []Relationship
}

ResourceType represents a resource type in the authorization policy.

type RoleAction

type RoleAction string

RoleAction is the list of actions that can be performed on a role resource

const (
	// RoleActionCreate is the action name to create a role
	RoleActionCreate RoleAction = "role_create"
	// RoleActionGet is the action name to get a role
	RoleActionGet RoleAction = "role_get"
	// RoleActionList is the action name to list roles
	RoleActionList RoleAction = "role_list"
	// RoleActionUpdate is the action name to update a role
	RoleActionUpdate RoleAction = "role_update"
	// RoleActionDelete is the action name to delete a role
	RoleActionDelete RoleAction = "role_delete"
)

type RoleBindingAction

type RoleBindingAction string

RoleBindingAction is the list of actions that can be performed on a role-binding resource

const (
	// RoleBindingActionCreate is the action name to create a role binding
	RoleBindingActionCreate RoleBindingAction = "iam_rolebinding_create"
	// RoleBindingActionUpdate is the action name to update a role binding
	RoleBindingActionUpdate RoleBindingAction = "iam_rolebinding_update"
	// RoleBindingActionDelete is the action name to delete a role binding
	RoleBindingActionDelete RoleBindingAction = "iam_rolebinding_delete"
	// RoleBindingActionGet is the action name to get a role binding
	RoleBindingActionGet RoleBindingAction = "iam_rolebinding_get"
	// RoleBindingActionList is the action name to list role bindings
	RoleBindingActionList RoleBindingAction = "iam_rolebinding_list"
)

type Union

type Union struct {
	Name          string
	ResourceTypes []types.TargetType
}

Union represents a named union of multiple concrete resource types.