bluesky_httpserver.authorization.BasicAPIAccessControl

class bluesky_httpserver.authorization.BasicAPIAccessControl(*, roles=None)

Basic API access policy. The policy is used by HTTP server by default. The basic policy supports two default users: UNAUTHENTICATED_SINGLE_USER (user authorized with single-user API key) and UNAUTHENTICATED_PUBLIC (unauthorized user, sending no token or API key with the request). The default users are assigned to unauthenticated_single_user and unauthenticated_public roles respectively. In additon, five roles are defined by the policy and available to subclassed policies: admin, expert, advanced, user and observer.

Each of the seven roles is assigned a reasonable set of default scopes, which may be customized for practical deployments. The parameter roles allows to replace or modify sets of scopes assigned to default roles or add new custom roles recognized by policies. Note, that the basic API access policy support only unauthenticated access and uses only two roles. The other default roles and custom roles are intended for use in subclasses that define more sophysticated policies.

The optional parameter roles accepts a dictionary, which maps role names to operations on the respective sets of scopes. The operations include scopes_set (replaces the existing scopes by the new scopes or sets scopes for a new custom role), scopes_add (adds scopes to the existing scopes) and scopes_remove (remove scopes from the set). Multiple operations for a given role are executed in the following order: scopes_set, scopes_add followed by scopes_remove.

The following examples illustrate how modify API access for the default user role. Access to API may be disabled by mapping the role name to None or setting scopes to the empty list:

# 'user' can not access any API.
{"user": None}
{"user": {"scopes_set": []}}
{"user": {"scopes_set": None}}

In the following examples, the scopes are not changed, since no operations are specified or the operations do not modify the scopes:

# Scopes are not changed
{"user": {}}
{"user": {"scopes_add": []}}
{"user": {"scopes_add": None}}
{"user": {"scopes_remove": []}}
{"user": {"scopes_remove": None}}
{"user": {"scopes_add": [], "scopes_remove": []}}
{"user": {"scopes_add": None, "scopes_remove": None}}

The scopes are replaces by specifying a list of scopes with scopes_set:

# Replace the scopes with the new set: 'user' can now only read status and the queue.
{"user": {"scopes_set": ["read:status", "read:queue"]}}

# Replace the scopes: 'user' can now only read status.
{"user": {"scopes_set": ["read:status"]}}
# A single scope may be specified as a string (more convenient in YML config file).
{"user": {"scopes_set": "read:status"}}

Additional scopes can be added to the default scopes:

# In addition to default scopes, 'user' can now upload and execute scripts.
{"user": {"scopes_add": ["write:scripts"]}}
{"user": {"scopes_add": "write:scripts"}}

Scopes can be removed from the default scopes:

# 'user' is assigned the default scopes except API for editing the queue.
{"user": {"scopes_remove": ["write:queue:edit"]}}
{"user": {"scopes_remove": "write:queue:edit"}}

Multiple operations may be specified:

# Now the 'user' can execute scripts, but not edit the queue.
{"user": {"scopes_add": ["write:scripts"], "remove": ["write:queue:edit"]}}
{"user": {"scopes_add": "write:scripts", "remove": "write:queue:edit"}}

In practical deployments, the policy arguments are defined in config YML files. The following is an example of configuration that modifies the scopes for the user role and creates a new test_role:

api_access:
  policy: bluesky_httpserver.authorization:BasicAPIAccessControl
  args:
    roles:
      user:
        scopes_add: write:scripts
        scopes_remove:
          - write:queue:edit
          - read:queue:edit
      test_role:
        scopes_add:
          - read:status
          - read:queue
          - read:history
          - read:resources
          - read:config
          - read:monitor
          - read:console
          - read:lock
          - read:testing

Parameters:

roles: dict, None

The dictionary that maps role names to operations that modify assigned role scopes. If None, then the default roles with default unmodified scopes are used.

__init__(*, roles=None)

Methods

__init__(*[, roles])
get_displayed_user_name(username)	Returns the displayed user name for the user. The displayed user name is assembled from username, full 'displayed' user name and user's email. The formatting depends on the available data, i.e. if no additional data is available, then username is returned. If the user is not found, then username is returned. The following output is possible for the user 'jdoe'::.
get_user_info(username)	Returns complete user information, including a set of roles, set of scopes and displayed user name.
get_user_roles(username)	Returns a set of roles assigned to the user.
get_user_scopes(username)	Returns a set of scopes assigned to the user.
is_user_known(username)	Performs quick check whether the user is known.