AARC Entitlement Library

This package provides python classes to create, parse and compare entitlements according to the AARC recommendations G002 and G069.

Installation

Install using pip:

pip install aarc-entitlement

Documentation

The documentation is available at https://aarcentitlement.readthedocs.io.

The G069 recommendation can be found at https://aarc-community.org/guidelines/aarc-g069. (Its deprecated predecessor, G002, is available at https://aarc-community.org/guidelines/aarc-g002)

Examples

Check if a user entitlement permits usage of a service

import aarc_entitlement

# This entitlement is needed to use a service
required = aarc_entitlement.G002("urn:geant:h-df.de:group:aai-admin")

# This entitlement is held by a user who wants to use the service
actual =   aarc_entitlement.G002("urn:geant:h-df.de:group:aai-admin:role=member")

# Is the user permitted to use the service, because of its entitlement `actual`?
permitted = actual.satisfies(required)
# -> True here

# Are the two entitlements the same?
equals = required == actual
# -> False here

G069 Entitlement Normalization

Starting with recommendation G069 the specification requires normalization of entitlements. When using AarcEntitlementG069 the library produces normalized representations.

import aarc_entitlement

not_normalized = "UrN:NiD:ExAmPlE.oRg:group:Minun%20Ryhm%c3%a4ni"

normalized = repr(aarc_entitlement.G069(not_normalized))
# -> "urn:nid:example.org:group:Minun%20Ryhm%C3%A4ni"

Tests, Linting and Documentation

Run tests for all supported python versions:

# run tests, coverage and linter
tox

# build docs
tox -e docs

# After this, the documentation should be located at `doc/build/index.html`.

Packaging

To upload a new package version to pypi use the Makefile:

# build the package
make dist

# upload the package to pypi
make upload

Funding Notice

The AARC project has received funding from the European Union’s Horizon 2020 research and innovation programme under grant agreement No 653965 and 730941.

API

Check entitlements according to the AARC recommendations G002 and G069.

The documentation is available at https://aarcentitlement.readthedocs.io.

The G002 is available at https://aarc-community.org/guidelines/aarc-g002. The G069 is available at https://aarc-community.org/guidelines/aarc-g069.

This code is distributed under the MIT License.

exception Error

Bases: Exception

A generic error for this module

exception ParseError

Bases: Error

Error during parsing an entitlement

KEYS_ALL = ['namespace_id', 'delegated_namespace', 'subnamespaces', 'group', 'subgroups', 'role', 'group_authority']: All possible keys of entitlement parts

KEYS_OPTIONAL = ['subnamespaces', 'role', 'subgroups', 'group_authority']: parts with these keys are optional

KEYS_TUPLES = ['subnamespaces', 'subgroups']: parts with these keys must be tuples or lists

class Base(entitlement, parse_opts=None)

Bases: object

Base is the parent class of the actual entitlements. Use G069 or G002 directly.

Instances can be tested for equality and less-than-or-equality. satisfies() can be used to check if a user with an entitlement user_has is permitted to use a resource which requires a certain entitlement service_wants using: user_has.satisfies(resource_wants)

Parameters

entitlement (Union[str,dict]) – Usually a raw string representation of the entitlement. Alternatively a dict with the needed parts may be provided.

Raises

ParseError – If the raw entitlement is not following the respective AARC recommendation and cannnot be parsed.
Error – If the attributes extracted from the entitlement could not be assigned to this instance.

satisfies(required)

Check if self satisfies the demands of required. self satisfies the requirement if it is equal to or more permissive than required.

Parameters: required – An entitlement which is required e.g. for using a service.
Returns: True, if the requirement is satisfied. Otherwise, False is returned.

is_contained_in(other): self is contained in other if other is equal or more permissive than `self

property parts: dict

Return type: dict
Returns: A copy of the parts of the entitlement. This cannot be used to modify the entitlement. Use set_part() instead.

get_part(key)

Return type: Union[tuple, str, None]
Returns: Entitlement part indicated by key

set_part(key, value)

set_part can be used to modify this entitlement. Values will be properly normalized.

Parameters

key (str) – Key of the entitlement part. Valid values can be found in aarc_entitlement.ALL_KEYS
value (Union[tuple, list, str, None]) – The value to be set. If None and the part indicated by key is optional, then the part is deleted.

class G002(entitlement, strict=False)

Bases: Base

Create, parse and compare AARC Entitlements G002

Reference specification: https://aarc-community.org/guidelines/aarc-g002

The entitlement is always ‘%xx’ decoded before parsing.

In addition to the parameters from :class:`` the strict parametr is available:

Parameters: strict (bool,optional) – If set to true, only entitlements with a group_authority part are valid. If raw does not contain a group_authority part, a ParseError will be raised.

class G069(entitlement)

Bases: Base

In contrast to G002 this entitlement spec allows ‘%xx’ encoded parts. Hence, a string entitlement is not ‘%xx’ decoded.

G069 uses the same parameters as Base.