entitlements

A tool to manage entitlements in SUKAT

Setup

• Clone the repo
• Make sure you have the python packages listed in dependencies.list installed on your system.
• Copy config.ini.example to config.ini and update with real credentials.
• Create your entitlement map file according to the value of entitlement_map in config.ini. See entmap.conf.example and the section below for details on the format.
• Run update-entitlements.py to synchronize with SUKAT.

update-entitlements.py

Synchronizes the entitlements in SUKAT with the desired state from entmap.conf.

usage: update-entitlements.py [-h] [--dry-run] [--debug]
                              [--only-add | --only-remove]
                              [<entitlement> ...]

Update entitlements in SUKAT according to entmap.conf.

positional arguments:
  <entitlement>  If present, only act on these entitlements. If not present,
                 act on all entitlements.

options:
  -h, --help     show this help message and exit
  --dry-run      Don't make any changes, only print what would be done.
  --debug        Show extra output for debug purposes.
  --only-add     Only add entitlements, don't remove any.
  --only-remove  Only remove entitlements, don't add any.

manage-entitlements.py

Adds and/or removes entitlements to/from a given user or list of users and updates entmap.conf to reflect the changes made.

usage: manage-entitlements.py [--entmap-update]
                              [<username> ...]
                              [--add, -a <entitlement> ...]
                              [--remove, -r <entitlement> ...]
       manage-entitlements.py -h|--help


Manage entitlements in SUKAT

positional arguments:
  <username>            The user(s) to be acted upon. If no users given, read
                        users from stdin.

options:
  -h, --help            show this help message and exit
  --add [<entitlement> ...], -a [<entitlement> ...]
                        Add one or more entitlements to the given user(s). Can
                        be specified multiple times.
  --remove [<entitlement> ...], -r [<entitlement> ...]
                        Delete one or more entitlements from the given users(s).
                        Can be specified multiple times.
  --entmap-update       Update entmap.conf to reflect the changes made.

(Due to a quirk in argparse, the help message printed when the program is run with the --help argument is slightly misleading. The above is the actual correct invocation description.)

Additions to entmap.conf will be placed after the last occurrence of the given entitlement, or at the end of the file if it doesn't exist in the file already.

Removals simply delete the relevant line if it exists. If the line contains a comment, it will disappear as well.

entmap.conf

See also entmap.conf.example.

This file lists all entitlement mappings for update-entitlements.py to maintain. If an entitlement doesn't occur at all in the file, update-entitlements.py will not touch it.

A # character starts a comment, which runs to the end of the line. There is no multiline comment facility.

All whitespace except newline (\n) is ignored. Blank lines are allowed.

Each non-comment should match the following format: entitlement = [!]handler:query

• entitlement - An entitlement. Will be concatenated with the value of entitlement_base in config.ini. The same entitlement may be specified several times with different handler/query combinations.
  Depending on the environments, there will be restrictions on what entitlement names are considered valid.

• handler - The facility to be used to process query.
  If a handler is prefixed with !, the resulting set of users will be excluded from the given entitlement. This exclusion has precedence over all inclusion mechanisms.

• query - A handler-dependent description of who should be granted the entitlement.

There are five handlers:

• ldap - Takes an LDAP search string as a query. The query should result in a list of users who will then be granted the given entitlement.
• daisy - Accepts two kinds of queries:
  • students - Will return all students who have had an active registration at DSV at any time during the last 10 semesters.
  • course:<id> - Requires a Daisy courseSegment ID as a parameter, and will return all students currently registered on that courseSegment.
• user - Accepts a username as a query. The given user will be granted the given entitlement.
• unixgroup - Takes the name of a unix group as a query. All members of the named group will be granted the given entitlement.
• none - Does not take a query (the :query part will be ignored if it exists). Indicates that no users should have the given entitlement. Useful for removing outdated entitlements.