documentation, cleanup

README.md

@@ -1,3 +1,55 @@
 # py-microservice
 
-Sample microservice for use with basebox, written in Python
+Sample microservice for use with basebox broker, written in Python.
+
+## Running
+
+Configure the broker's schema accordingly (see notes in `config.toml`) and launch the microservice: 
+
+```shell
+# optional, but recommended:
+# setup/activate virtual env
+$ python3 -mvenv venv # once
+$ source venv/bin/activate # always
+
+# actual invocation
+$ pip install -r requirements.txt
+$ ./main.py -c config.toml
+```
+
+See top-level notes in `main.py` for further deployment information.
+
+## Extending the GraphQL schema
+
+see `schema.py` and [Strawberry GraphQL documentation](https://strawberry.rocks/docs)
+
+## Authorization
+
+### Attribute based permissions
+
+Assuming a zero trust deployment, the requesting user must have the correct claims to execute an operation - 
+to disable this during development (or if you operate the service in a trusted enviroment), remove the `permission_classes` parameter in all operations defined in `schema.py`. 
+
+These permissions must be a list stored in the access token under the key `config.AUTH_PERMISSIONS_KEY`, 
+its values prefixed with `config.AUTH_OLS_PREFIX`. For example:
+```javascript
+claims = {
+    //...
+    "basebox/permissions": ["allow::bb::operation::orderPizza", "allow::bb::operation::cancelPizzaOrder"]
+}
+```
+
+### JWT signature algorithm
+
+For security reasons the JWT signature algorithm must be a member of
+the `VALID_ALGS` list configured in `auth.py`.
+Since this is less of a user configurable setting and more a question
+of underlying security libraries' capabilities (i.e. `openssl`), it is intentionally
+not part of the config system. A more permissive but less secure alternative would be 
+to instead just check that the supplied algorithm (the `alg` field in JWT)
+is [not equal to `none`](https://blog.pentesteracademy.com/hacking-jwt-tokens-the-none-algorithm-67c14bb15771). In the author's opinion however this leaves an attacker with too much surface freedom:
+
+As a trivial example it's unclear whether `NONE` would be 
+wrongly accepted by the verification library, and while normalization to lowercase isn't hard,
+other loopholes might exist (future algorithms with unknown security profiles, 
+unicode normalization, implementation bugs, etc.)