Inside a Role

Overview

A Role identifies who's making a call, and what they're allowed to do. What they're allowed to do is given by a list of Policys (more details here). Some Policys can be configured - have parameters given to them. These are stored in the Role.

A Role can also have parents. When parents are provided, they provide the starting point for the Role's Policys. This allows, for example, a Role to be created with restricted access to somebody else's resources - a bit like setuid.

Each User must have a default Role. The default Role is used for api access from web pages by that user. A Role named '' is treated as a default Role. It is recommended any non-default Role should have the same Users default Role as an ancenstor (a parent or a parent's parent, ...).

A Role can do everything the Policys allow it - if one Policy allows it, the Role can do it.

A Policy starts with the premission given by all the Role's parents, and then trims that back to just what is needed. When there are no parents, this is effectively 'do anything as the Role's User.

Policys can have parameters - these are set by the Role. These can be constants, or python expressions, with a few limits to avoid security leaks, or DOS attacks.

Tips, Tricks & Recommendations

We recommended that other Roles owned by the same user have the Users default Role as a parent. When you do this, the default Role becomes a gate keeper for that Users access through the api. Changing the Policys attached to the default Role allow you to regulate what that User can do. For example, a newly registered User might only being allowed to delete their account, and only once they've verified their email address, say, is the rest of your api permitted.

Role

Fields

user

Who it is / the Role's owner.

role_policies

The policies making up this Role. You must add at least one Policy, otherwise the role can do nothing.

name

The name of the Role. Use '' for User's default Roles - and require a name for any other Roles.

created

When the Role was created.

parents

The parent Roles of this Role. Default Roles don't need parents, other ones do.

parameters

The parameters this Role sets for evaluating Policies.

Other fields

are internal, and should be left alone.

Properties

parameters_loaded

parameters as a self-saving dictionary

display_name

a name to use for display

last_used

when the Role was last used (by an api call)

Methods

deep_update_parameters(update)->None

deep update parameters using the update dictionary

check_parameters(params)->None static

check if parameters are ok. raises exceptions if necessary.

role_allows_api(action, kwargs, resources, user_check, context, policies, ignore_resource_policies)->Bool

Check if the action is allowed by thie Role.

action

string, eg 'home/describe_site'

kwargs

Dict[str, *] all arguments to the call. If you have unnamed args, you will need to name them and combine them with the named arguments.

resources

list of (path, resource, access) from the call where the path is the path to the resource in the arguments, resource is the resource itself, and access is a ResourceAccess for how the method will use the resource.

user_check = lambda user: True

callable to check the user is ok. Useful, for example, to check if the use is the site user for calls between instances on a site.

context

the PolicyContext for this check. context.context is the context for evaluating substitutions - it defines the values available.

policies

policies(ctx:PolicyContext) returns an iterable of ResourceUsesPolicy(models.Model) giving the policies for this method.

ignore_resource_policies

whether the resources' policies should be ignored. Only in exceptional circumstances should this be set to True. For example, for the method which adjusts a resource's policies - if the policies weren't ignored for this particular method then it would be very easy to adjust a resource's policies so that it would no longer be possible to adjust a resource's policies, and so that resource would be stuck.

for_context()

Role overrides this to provide:

.api_id, .urn, .owning_user

The default properties exposed by resources

.created_roles

The list of Roles which have been created using this Role

PolicyContext

role

The Role being checked

action

The name of the api call, eg 'home/describe_site'

resources

A list of (path, resource, access) of all resources used in the call

access

ResourceAccess of how the method will use the resource

context

A dictionary of values giving the values available for {} substitutions.

kwargs

The kwargs of the method call

enum ResourceAccess

This enum specifies how a resource is being accessed by a method.

.Public

The lowest level of access, often indicating, some sort of read access by the general public describe_user_brief, for example.

.Read

A read access. The resource is not being modified, but sensitive information may be read describe_user, for example.

.Full

A modifying access modify_user for example.