py-microservice/README.md

# py-microservice

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"]
}
```

Strictly speaking this duplicates the permissions check already done by the broker, 
and thus requests without required permissions don't even reach the microservice - 
they've been rejected at the broker level.

### 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.)