rbac

README

Authz

Package authz implements AuthoriZation for Coder.

Overview

Authorization defines what permission a subject has to perform actions to objects:

• Permission is binary: yes (allowed) or no (denied).
• Subject in this case is anything that implements interface authz.Subject.
• Action here is an enumerated list of actions, but we stick to Create, Read, Update, and Delete here.
• Object here is anything that implements authz.Object.

Permission Structure

A permission is a rule that grants or denies access for a subject to perform an action on a object. A permission is always applied at a given level:

• site level applies to all objects in a given Coder deployment.
• org level applies to all objects that have an organization owner (org_owner)
• user level applies to all objects that have an owner with the same ID as the subject.

Permissions at a higher level always override permissions at a lower level.

The effect of a permission can be:

• positive (allows)
• negative (denies)
• abstain (neither allows or denies, not applicable)

Negative permissions always override positive permissions at the same level. Both negative and positive permissions override abstain at the same level.

This can be represented by the following truth table, where Y represents positive, N represents negative, and _ represents abstain:

Action	Positive	Negative	Result
read	Y	_	Y
read	Y	N	N
read	_	_	_
read	_	N	Y

Permission Representation

Permissions are represented in string format as <sign>?<level>.<object>.<id>.<action>, where:

• negated can be either + or -. If it is omitted, sign is assumed to be +.
• level is either site, org, or user.
• object is any valid resource type.
• id is any valid UUID v4.
• action is create, read, modify, or delete.

Example Permissions

• +site.*.*.read: allowed to perform the read action against all objects of type devurl in a given Coder deployment.
• -user.workspace.*.create: user is not allowed to create workspaces.

Roles

A role is a set of permissions. When evaluating a role's permission to form an action, all the relevant permissions for the role are combined at each level. Permissions at a higher level override permissions at a lower level.

The following table shows the per-level role evaluation. Y indicates that the role provides positive permissions, N indicates the role provides negative permissions, and _ indicates the role does not provide positive or negative permissions. YN_ indicates that the value in the cell does not matter for the access result.

Role (example)	Site	Org	User	Result
site-admin	Y	YN_	YN_	Y
no-permission	N	YN_	YN_	N
org-admin	_	Y	YN_	Y
non-org-member	_	N	YN_	N
user	_	_	Y	Y
	_	_	N	N
unauthenticated	_	_	_	N

Documentation

Index

• Constants
• Variables
• func IsOrgRole(roleName string) (string, bool)
• func RoleAdmin() string
• func RoleMember() string
• func RoleOrgAdmin(organizationID uuid.UUID) string
• func RoleOrgMember(organizationID uuid.UUID) string
• type Action
• type Object
  • func (z Object) All() Object
  • func (z Object) InOrg(orgID uuid.UUID) Object
  • func (z Object) WithID(resourceID string) Object
  • func (z Object) WithOwner(ownerID string) Object
• type Permission
• type RegoAuthorizer
  • func NewAuthorizer() (*RegoAuthorizer, error)
  • func (a RegoAuthorizer) Authorize(ctx context.Context, subjectID string, roles []Role, action Action, ...) error
  • func (a RegoAuthorizer) AuthorizeByRoleName(ctx context.Context, subjectID string, roleNames []string, action Action, ...) error
• type Role
  • func RoleByName(name string) (Role, error)
• type UnauthorizedError
  • func ForbiddenWithInternal(internal error, input map[string]interface{}, output rego.ResultSet) *UnauthorizedError
  • func (UnauthorizedError) Error() string
  • func (e *UnauthorizedError) Input() map[string]interface{}
  • func (e *UnauthorizedError) Internal() error
  • func (e *UnauthorizedError) Output() rego.ResultSet

Constants

const (
	ActionCreate = "create"
	ActionRead   = "read"
	ActionUpdate = "update"
	ActionDelete = "delete"
)

const WildcardSymbol = "*"

Variables

var (
	ResourceWorkspace = Object{
		Type: "workspace",
	}

	ResourceTemplate = Object{
		Type: "template",
	}

	// ResourceWildcard represents all resource types
	ResourceWildcard = Object{
		Type: WildcardSymbol,
	}
)

Resources are just typed objects. Making resources this way allows directly passing them into an Authorize function and use the chaining api.

Functions

func IsOrgRole

func IsOrgRole(roleName string) (string, bool)

func RoleAdmin

func RoleAdmin() string

func RoleMember

func RoleMember() string

func RoleOrgAdmin

func RoleOrgAdmin(organizationID uuid.UUID) string

func RoleOrgMember

func RoleOrgMember(organizationID uuid.UUID) string

Types

type Action

type Action string

Action represents the allowed actions to be done on an object.

type Object

type Object struct {
	ResourceID string `json:"id"`
	Owner      string `json:"owner"`
	// OrgID specifies which org the object is a part of.
	OrgID string `json:"org_owner"`

	// Type is "workspace", "project", "devurl", etc
	Type string `json:"type"`
}

Object is used to create objects for authz checks when you have none in hand to run the check on. An example is if you want to list all workspaces, you can create a Object that represents the set of workspaces you are trying to get access too. Do not export this type, as it can be created from a resource type constant.

func (Object) All

func (z Object) All() Object

All returns an object matching all resources of the same type.

func (Object) InOrg

func (z Object) InOrg(orgID uuid.UUID) Object

InOrg adds an org OwnerID to the resource

func (Object) WithID

func (z Object) WithID(resourceID string) Object

WithID adds a ResourceID to the resource

func (Object) WithOwner

func (z Object) WithOwner(ownerID string) Object

WithOwner adds an OwnerID to the resource

type Permission

type Permission struct {
	// Negate makes this a negative permission
	Negate       bool   `json:"negate"`
	ResourceType string `json:"resource_type"`
	ResourceID   string `json:"resource_id"`
	Action       Action `json:"action"`
}

Permission is the format passed into the rego.

type RegoAuthorizer

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

RegoAuthorizer will use a prepared rego query for performing authorize()

func NewAuthorizer

func NewAuthorizer() (*RegoAuthorizer, error)

func (RegoAuthorizer) Authorize

func (a RegoAuthorizer) Authorize(ctx context.Context, subjectID string, roles []Role, action Action, object Object) error

Authorize allows passing in custom Roles. This is really helpful for unit testing, as we can create custom roles to exercise edge cases.

func (RegoAuthorizer) AuthorizeByRoleName

func (a RegoAuthorizer) AuthorizeByRoleName(ctx context.Context, subjectID string, roleNames []string, action Action, object Object) error

AuthorizeByRoleName will expand all roleNames into roles before calling Authorize(). This is the function intended to be used outside this package. The role is fetched from the builtin map located in memory.

type Role

type Role struct {
	Name string       `json:"name"`
	Site []Permission `json:"site"`
	// Org is a map of orgid to permissions. We represent orgid as a string.
	// We scope the organizations in the role so we can easily combine all the
	// roles.
	Org  map[string][]Permission `json:"org"`
	User []Permission            `json:"user"`
}

Role is a set of permissions at multiple levels: - Site level permissions apply EVERYWHERE - Org level permissions apply to EVERYTHING in a given ORG - User level permissions are the lowest This is the type passed into the rego as a json payload. Users of this package should instead **only** use the role names, and this package will expand the role names into their json payloads.

func RoleByName

func RoleByName(name string) (Role, error)

RoleByName returns the permissions associated with a given role name. This allows just the role names to be stored and expanded when required.

type UnauthorizedError

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

UnauthorizedError is the error type for authorization errors

func ForbiddenWithInternal

func ForbiddenWithInternal(internal error, input map[string]interface{}, output rego.ResultSet) *UnauthorizedError

ForbiddenWithInternal creates a new error that will return a simple "forbidden" to the client, logging internally the more detailed message provided.

func (UnauthorizedError) Error

func (UnauthorizedError) Error() string

Error implements the error interface.

func (*UnauthorizedError) Input

func (e *UnauthorizedError) Input() map[string]interface{}

func (*UnauthorizedError) Internal

func (e *UnauthorizedError) Internal() error

Internal allows the internal error message to be logged.

func (*UnauthorizedError) Output

func (e *UnauthorizedError) Output() rego.ResultSet

Output contains the results of the Rego query for debugging.