072b6e87ae
There was an issue with the apt packages where python3-requests-kerberos didn't actually work. Instead of debugging the apt package I switched to using a venv, which should be more robust anyway.
134 lines
5.4 KiB
Markdown
134 lines
5.4 KiB
Markdown
# entitlements
|
|
A tool to manage entitlements in SUKAT
|
|
|
|
## Setup
|
|
|
|
In order to avoid having to activate a virtual environment to run the
|
|
scripts, the path to the venv is hardcoded in the scripts'
|
|
shebang. Because of this, it's important to use the exact paths listed
|
|
in the setup instructions.
|
|
|
|
* Clone the repo into `/opt/entitlements`
|
|
* Create a venv in the project directory: `python3 -m venv env`
|
|
* Activate the venv and install dependencies:
|
|
`source env/bin/activate; pip install -r requirements.txt`
|
|
There may be errors regarding installation of the gssapi
|
|
package. In that case, make sure the apt packages `python3-dev` and
|
|
`heimdal-dev` are both installed on the 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.
|