rbac

package
v0.23.3 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 15, 2023 License: AGPL-3.0 Imports: 25 Imported by: 0

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.
  • id is included in the permission syntax, however only scopes may use id to specify a specific object.
  • action is create, read, modify, or delete.

Example Permissions

  • +site.*.*.read: allowed to perform the read action against all objects of type app 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

Scopes

Scopes can restrict a given set of permissions. The format of a scope matches a role with the addition of a list of resource ids. For a authorization call to be successful, the subject's roles and the subject's scopes must both allow the action. This means the resulting permissions is the intersection of the subject's roles and the subject's scopes.

An example to give a readonly token is to grant a readonly scope across all resources +site.*.*.read. The intersection with the user's permissions will be the readonly set of their permissions.

Resource IDs

There exists use cases that require specifying a specific resource. If resource IDs are allowed in the roles, then there is an unbounded set of resource IDs that be added to an "allow_list", as the number of roles a user can have is unbounded. This also adds a level of complexity to the role evaluation logic that has large costs at scale.

The use case for specifying this type of permission in a role is limited, and does not justify the extra cost. To solve this for the remaining cases (eg. workspace agent tokens), we can apply an allow_list on a scope. For most cases, the allow_list will just be ["*"] which means the scope is allowed to be applied to any resource. This adds negligible cost to the role evaluation logic and 0 cost to partial evaluations.

Example of a scope for a workspace agent token, using an allow_list containing a single resource id.

    "scope": {
      "name": "workspace_agent",
      "display_name": "Workspace_Agent",
      // The ID of the given workspace the agent token correlates to.
      "allow_list": ["10d03e62-7703-4df5-a358-4f76577d4e2f"],
      "site": [/* ... perms ... */],
      "org": {/* ... perms ... */},
      "user": [/* ... perms ... */]
    }

Testing

You can test outside of golang by using the opa cli.

Evaluation

opa eval --format=pretty 'false' -d policy.rego -i input.json

Partial Evaluation

opa eval --partial --format=pretty 'data.authz.allow' -d policy.rego --unknowns input.object.owner --unknowns input.object.org_owner --unknowns input.object.acl_user_list --unknowns input.object.acl_group_list -i input.json

Documentation

Overview

Code generated by rbacgen/main.go. DO NOT EDIT.

Index

Constants

View Source 
const WildcardSymbol = "*"

Variables

View Source 
var (
	// ResourceWildcard represents all resource types
	// Try to avoid using this where possible.
	ResourceWildcard = Object{
		Type: WildcardSymbol,
	}

	// ResourceWorkspace CRUD. Org + User owner
	//	create/delete = make or delete workspaces
	// 	read = access workspace
	//	update = edit workspace variables
	ResourceWorkspace = Object{
		Type: "workspace",
	}

	// ResourceWorkspaceProxy CRUD. Org
	//	create/delete = make or delete proxies
	// 	read = read proxy urls
	//	update = edit workspace proxy fields
	ResourceWorkspaceProxy = Object{
		Type: "workspace_proxy",
	}

	// ResourceWorkspaceExecution CRUD. Org + User owner
	//	create = workspace remote execution
	// 	read = ?
	//	update = ?
	// 	delete = ?
	ResourceWorkspaceExecution = Object{
		Type: "workspace_execution",
	}

	// ResourceWorkspaceApplicationConnect CRUD. Org + User owner
	//	create = connect to an application
	// 	read = ?
	//	update = ?
	// 	delete = ?
	ResourceWorkspaceApplicationConnect = Object{
		Type: "application_connect",
	}

	// ResourceAuditLog
	// read = access audit log
	ResourceAuditLog = Object{
		Type: "audit_log",
	}

	// ResourceTemplate CRUD. Org owner only.
	//	create/delete = Make or delete a new template
	//	update = Update the template, make new template versions
	//	read = read the template and all versions associated
	ResourceTemplate = Object{
		Type: "template",
	}

	// ResourceGroup CRUD. Org admins only.
	//	create/delete = Make or delete a new group.
	//	update = Update the name or members of a group.
	//	read = Read groups and their members.
	ResourceGroup = Object{
		Type: "group",
	}

	ResourceFile = Object{
		Type: "file",
	}

	ResourceProvisionerDaemon = Object{
		Type: "provisioner_daemon",
	}

	// ResourceOrganization CRUD. Has an org owner on all but 'create'.
	//	create/delete = make or delete organizations
	// 	read = view org information (Can add user owner for read)
	//	update = ??
	ResourceOrganization = Object{
		Type: "organization",
	}

	// ResourceRoleAssignment might be expanded later to allow more granular permissions
	// to modifying roles. For now, this covers all possible roles, so having this permission
	// allows granting/deleting **ALL** roles.
	// Never has an owner or org.
	//	create  = Assign roles
	//	update  = ??
	//	read	= View available roles to assign
	//	delete	= Remove role
	ResourceRoleAssignment = Object{
		Type: "assign_role",
	}

	// ResourceOrgRoleAssignment is just like ResourceRoleAssignment but for organization roles.
	ResourceOrgRoleAssignment = Object{
		Type: "assign_org_role",
	}

	// ResourceAPIKey is owned by a user.
	//	create  = Create a new api key for user
	//	update  = ??
	//	read	= View api key
	//	delete	= Delete api key
	ResourceAPIKey = Object{
		Type: "api_key",
	}

	// ResourceUser is the user in the 'users' table.
	// ResourceUser never has any owners or in an org, as it's site wide.
	// 	create/delete = make or delete a new user.
	// 	read = view all 'user' table data
	// 	update = update all 'user' table data
	ResourceUser = Object{
		Type: "user",
	}

	// ResourceUserData is any data associated with a user. A user has control
	// over their data (profile, password, etc). So this resource has an owner.
	ResourceUserData = Object{
		Type: "user_data",
	}

	// ResourceOrganizationMember is a user's membership in an organization.
	// Has ONLY an organization owner.
	//	create/delete  = Create/delete member from org.
	//	update  = Update organization member
	//	read	= View member
	ResourceOrganizationMember = Object{
		Type: "organization_member",
	}

	// ResourceLicense is the license in the 'licenses' table.
	// ResourceLicense is site wide.
	// 	create/delete = add or remove license from site.
	// 	read = view license claims
	// 	update = not applicable; licenses are immutable
	ResourceLicense = Object{
		Type: "license",
	}

	// ResourceDeploymentValues
	ResourceDeploymentValues = Object{
		Type: "deployment_config",
	}

	ResourceDeploymentStats = Object{
		Type: "deployment_stats",
	}

	ResourceReplicas = Object{
		Type: "replicas",
	}

	// ResourceDebugInfo controls access to the debug routes `/api/v2/debug/*`.
	ResourceDebugInfo = Object{
		Type: "debug_info",
	}

	// ResourceSystem is a pseudo-resource only used for system-level actions.
	ResourceSystem = Object{
		Type: "system",
	}
)

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

Functions

func CanAssignRole added in v0.8.5 

func CanAssignRole(expandable ExpandableRoles, assignedRole string) bool

CanAssignRole is a helper function that returns true if the user can assign the specified role. This also can be used for removing a role. This is a simple implementation for now.

func ChangeRoleSet added in v0.6.0 

func ChangeRoleSet(from []string, to []string) (added []string, removed []string)

ChangeRoleSet is a helper function that finds the difference of 2 sets of roles. When setting a user's new roles, it is equivalent to adding and removing roles. This set determines the changes, so that the appropriate RBAC checks can be applied using "ActionCreate" and "ActionDelete" for "added" and "removed" roles respectively.

func ConfigWithACL added in v0.13.0 

func ConfigWithACL() regosql.ConvertConfig

ConfigWithACL is the basic configuration for converting rego to SQL when the object has group and user ACL fields.

func ConfigWithoutACL added in v0.13.0 

func ConfigWithoutACL() regosql.ConvertConfig

ConfigWithoutACL is the basic configuration for converting rego to SQL when the object has no ACL fields.

func Filter added in v0.6.0 

func Filter[O Objecter](ctx context.Context, auth Authorizer, subject Subject, action Action, objects []O) ([]O, error)

Filter takes in a list of objects, and will filter the list removing all the elements the subject does not have permission for. All objects must be of the same type.

Ideally the 'CompileToSQL' is used instead for large sets. This cost scales linearly with the number of objects passed in.

func IsOrgRole added in v0.5.2 

func IsOrgRole(roleName string) (string, bool)

func IsUnauthorizedError added in v0.17.2 

func IsUnauthorizedError(err error) bool

IsUnauthorizedError is a convenience function to check if err is UnauthorizedError. It is equivalent to errors.As(err, &UnauthorizedError{}).

func ReloadBuiltinRoles added in v0.22.1 

func ReloadBuiltinRoles(opts *RoleOptions)

ReloadBuiltinRoles loads the static roles into the builtInRoles map. This can be called again with a different config to change the behavior.

TODO: @emyrk This would be great if it was instanced to a coderd rather than a global. But that is a much larger refactor right now. Essentially we did not foresee different deployments needing slightly different role permissions.

func RoleMember 

func RoleMember() string

func RoleOrgAdmin 

func RoleOrgAdmin(organizationID uuid.UUID) string

func RoleOrgMember 

func RoleOrgMember(organizationID uuid.UUID) string

func RoleOwner added in v0.8.6 

func RoleOwner() string

func RoleTemplateAdmin added in v0.8.6 

func RoleTemplateAdmin() string

func RoleUserAdmin added in v0.8.6 

func RoleUserAdmin() string

Types

type Action 

type Action string

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

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

func AllActions added in v0.17.2 

func AllActions() []Action

AllActions is a helper function to return all the possible actions types.

type AuthCall added in v0.17.2 

type AuthCall struct {
	Actor  Subject
	Action Action
	Object Object
}

type AuthorizeFilter added in v0.9.3 

type AuthorizeFilter interface {
	SQLString() string
}

AuthorizeFilter is a compiled partial query that can be converted to SQL. This allows enforcing the policy on the database side in a WHERE clause.

func Compile added in v0.9.3 

func Compile(cfg regosql.ConvertConfig, pa *PartialAuthorizer) (AuthorizeFilter, error)

type Authorizer added in v0.5.10 

type Authorizer interface {
	// Authorize will authorize the given subject to perform the given action
	// on the given object. Authorize is pure and deterministic with respect to
	// its arguments and the surrounding object.
	Authorize(ctx context.Context, subject Subject, action Action, object Object) error
	Prepare(ctx context.Context, subject Subject, action Action, objectType string) (PreparedAuthorized, error)
}

func Cacher added in v0.17.2 

func Cacher(authz Authorizer) Authorizer

Cacher returns an Authorizer that can use a cache stored on a context to short circuit duplicate calls to the Authorizer. This is useful when multiple calls are made to the Authorizer for the same subject, action, and object. The cache is on each `ctx` and is not shared between requests. If no cache is found on the context, the Authorizer is called as normal.

Cacher is safe for multiple actors.

func NewCachingAuthorizer added in v0.17.4 

func NewCachingAuthorizer(registry prometheus.Registerer) Authorizer

NewCachingAuthorizer returns a new RegoAuthorizer that supports context based caching. To utilize the caching, the context passed to Authorize() must be created with 'WithCacheCtx(ctx)'.

type ExpandableRoles added in v0.15.3 

type ExpandableRoles interface {
	Expand() ([]Role, error)
	// Names is for logging and tracing purposes, we want to know the human
	// names of the expanded roles.
	Names() []string
}

ExpandableRoles is any type that can be expanded into a []Role. This is implemented as an interface so we can have RoleNames for user defined roles, and implement custom ExpandableRoles for system type users (eg autostart/autostop system role). We want a clear divide between the two types of roles so users have no codepath to interact or assign system roles.

Note: We may also want to do the same thing with scopes to allow custom scope support unavailable to the user. Eg: Scope to a single resource.

type ExpandableScope added in v0.15.3 

type ExpandableScope interface {
	Expand() (Scope, error)
	// Name is for logging and tracing purposes, we want to know the human
	// name of the scope.
	Name() string
}

type Object 

type Object struct {
	// ID is the resource's uuid
	ID    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", "app", etc
	Type string `json:"type"`

	ACLUserList  map[string][]Action ` json:"acl_user_list"`
	ACLGroupList map[string][]Action ` json:"acl_group_list"`
}

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 AllResources added in v0.22.1 

func AllResources() []Object

func (Object) All 

func (z Object) All() Object

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

func (Object) Equal added in v0.17.0 

func (z Object) Equal(b Object) bool

func (Object) InOrg 

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

InOrg adds an org OwnerID to the resource

func (Object) RBACObject added in v0.6.0 

func (z Object) RBACObject() Object

func (Object) WithACLUserList added in v0.9.9 

func (z Object) WithACLUserList(acl map[string][]Action) Object

WithACLUserList adds an ACL list to a given object

func (Object) WithGroupACL added in v0.9.9 

func (z Object) WithGroupACL(groups map[string][]Action) Object

func (Object) WithID 

func (z Object) WithID(id uuid.UUID) Object

func (Object) WithIDString added in v0.15.1 

func (z Object) WithIDString(id string) Object

func (Object) WithOwner 

func (z Object) WithOwner(ownerID string) Object

WithOwner adds an OwnerID to the resource

type Objecter added in v0.6.0 

type Objecter interface {
	RBACObject() Object
}

Objecter returns the RBAC object for itself.

type PartialAuthorizer added in v0.8.6 

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

PartialAuthorizer is a prepared authorizer with the subject, action, and resource type fields already filled in. This speeds up authorization when authorizing the same type of object numerous times. See rbac.Filter for example usage.

func (*PartialAuthorizer) Authorize added in v0.8.6 

func (pa *PartialAuthorizer) Authorize(ctx context.Context, object Object) error

func (*PartialAuthorizer) CompileToSQL added in v0.13.0 

func (pa *PartialAuthorizer) CompileToSQL(ctx context.Context, cfg regosql.ConvertConfig) (string, error)

CompileToSQL converts the remaining rego queries into SQL WHERE clauses.

type Permission 

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

Permission is the format passed into the rego.

func Permissions added in v0.17.4 

func Permissions(perms map[string][]Action) []Permission

Permissions is just a helper function to make building roles that list out resources and actions a bit easier.

type PreparedAuthorized added in v0.8.6 

type PreparedAuthorized interface {
	Authorize(ctx context.Context, object Object) error
	CompileToSQL(ctx context.Context, cfg regosql.ConvertConfig) (string, error)
}

type RegoAuthorizer 

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

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

func NewAuthorizer 

func NewAuthorizer(registry prometheus.Registerer) *RegoAuthorizer

func (RegoAuthorizer) Authorize 

func (a RegoAuthorizer) Authorize(ctx context.Context, subject Subject, action Action, object Object) error

Authorize is the intended function to be used outside this package. It returns `nil` if the subject is authorized to perform the action on the object. If an error is returned, the authorization is denied.

func (RegoAuthorizer) Prepare added in v0.8.6 

func (a RegoAuthorizer) Prepare(ctx context.Context, subject Subject, action Action, objectType string) (PreparedAuthorized, error)

Prepare will partially execute the rego policy leaving the object fields unknown (except for the type). This will vastly speed up performance if batch authorization on the same type of objects is needed.

type Role 

type Role struct {
	Name string `json:"name"`
	// DisplayName is used for UI purposes. If the role has no display name,
	// that means the UI should never display it.
	DisplayName string       `json:"display_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"`
	// contains filtered or unexported fields
}

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 OrganizationRoles added in v0.5.4 

func OrganizationRoles(organizationID uuid.UUID) []Role

OrganizationRoles lists all roles that can be applied to an organization user in the given organization. This is the list of available roles, and specific to an organization.

This should be a list in a database, but until then we build the list from the builtins.

func RoleByName added in v0.5.2 

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.

This function is exported so that the Display name can be returned to the api. We should maybe make an exported function that returns just the human-readable content of the Role struct (name + display name).

func SiteRoles added in v0.5.4 

func SiteRoles() []Role

SiteRoles lists all roles that can be applied to a user. This is the list of available roles, and not specific to a user

This should be a list in a database, but until then we build the list from the builtins.

type RoleNames added in v0.15.3 

type RoleNames []string

RoleNames is a list of user assignable role names. The role names must be in the builtInRoles map. Any non-user assignable roles will generate an error on Expand.

func (RoleNames) Expand added in v0.15.3 

func (names RoleNames) Expand() ([]Role, error)

func (RoleNames) Names added in v0.15.3 

func (names RoleNames) Names() []string

type RoleOptions added in v0.22.1 

type RoleOptions struct {
	NoOwnerWorkspaceExec bool
}

type Roles added in v0.15.3 

type Roles []Role

func (Roles) Expand added in v0.15.3 

func (roles Roles) Expand() ([]Role, error)

func (Roles) Names added in v0.15.3 

func (roles Roles) Names() []string

type Scope added in v0.9.0 

type Scope struct {
	Role
	AllowIDList []string `json:"allow_list"`
}

Scope acts the exact same as a Role with the addition that is can also apply an AllowIDList. Any resource being checked against a Scope will reject any resource that is not in the AllowIDList. To not use an AllowIDList to reject authorization, use a wildcard for the AllowIDList. Eg: 'AllowIDList: []string{WildcardSymbol}'

func ExpandScope added in v0.15.1 

func ExpandScope(scope ScopeName) (Scope, error)

func WorkspaceAgentScope added in v0.17.2 

func WorkspaceAgentScope(workspaceID, ownerID uuid.UUID) Scope

WorkspaceAgentScope returns a scope that is the same as ScopeAll but can only affect resources in the allow list. Only a scope is returned as the roles should come from the workspace owner.

func (Scope) Expand added in v0.15.3 

func (s Scope) Expand() (Scope, error)

func (Scope) Name added in v0.15.3 

func (s Scope) Name() string

type ScopeName added in v0.15.1 

type ScopeName string
const (
	ScopeAll                ScopeName = "all"
	ScopeApplicationConnect ScopeName = "application_connect"
)

func (ScopeName) Expand added in v0.15.3 

func (name ScopeName) Expand() (Scope, error)

func (ScopeName) Name added in v0.15.3 

func (name ScopeName) Name() string

type Subject added in v0.15.3 

type Subject struct {
	ID     string
	Roles  ExpandableRoles
	Groups []string
	Scope  ExpandableScope
	// contains filtered or unexported fields
}

Subject is a struct that contains all the elements of a subject in an rbac authorize.

func (Subject) Equal added in v0.17.0 

func (s Subject) Equal(b Subject) bool

func (Subject) SafeRoleNames added in v0.15.3 

func (s Subject) SafeRoleNames() []string

SafeRoleNames prevent nil pointer dereference.

func (Subject) SafeScopeName added in v0.15.3 

func (s Subject) SafeScopeName() string

SafeScopeName prevent nil pointer dereference.

func (Subject) WithCachedASTValue added in v0.23.2 

func (s Subject) WithCachedASTValue() Subject

WithCachedASTValue can be called if the subject is static. This will compute the ast value once and cache it for future calls.

type UnauthorizedError 

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

UnauthorizedError is the error type for authorization errors

func ForbiddenWithInternal 

func ForbiddenWithInternal(internal error, subject Subject, action Action, object Object, 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) As added in v0.17.2 

func (*UnauthorizedError) As(target interface{}) bool

As implements the errors.As interface.

func (UnauthorizedError) Error 

func (e 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.

func (*UnauthorizedError) SetInternal added in v0.17.2 

func (e *UnauthorizedError) SetInternal(err error)

func (UnauthorizedError) Unwrap added in v0.17.2 

func (e UnauthorizedError) Unwrap() error

Source Files

View all Source files

Directories

Path Synopsis
Package regosql converts rego queries into SQL WHERE clauses.
 Package regosql converts rego queries into SQL WHERE clauses.
sqltypes
Package sqltypes contains the types used to convert rego queries into SQL.
 Package sqltypes contains the types used to convert rego queries into SQL.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.