Verifying your policies 🔍️

Defining our authorisation policies in code, at the point where they will be enforced, makes them easily visible to developers working on the application. However, in many cases we’ll also want to surface those policies for other people in the organisation: users trying to request access, product owners or other stakeholders who need to verify the correct rules are in place.

Use verify_auth to generate a policy matrix

Tip

In order to use the verify_auth script, you must have installed fastapi[standard] or added this library with the optional scripts dependency, e.g. uv add ska_aaa_authhelpers --extra scripts

The verify_auth script takes the path to a FastAPI application secured with authhelpers and outputs a CSV or JSON summary of the authorisation policies you have defined for each route in your application.

$ verify_auth --help

 Usage: verify_auth [OPTIONS] APP_PATH

╭─ Arguments ─────────────────────────────────────────────────────────────╮
│ *    app_path      PATH  [default: None] [required]                     │
╰─────────────────────────────────────────────────────────────────────────╯
╭─ Options ───────────────────────────────────────────────────────────────╮
│ --format          [csv|json]  [default: csv]                            │
│ --output  -o      FILENAME    Write results to file [default: (stdout)] │
│ --help                        Show this message and exit.               │
╰─────────────────────────────────────────────────────────────────────────╯

Include in Sphinx documentation

You can examine or share the output from verify_auth directly, but in many cases you’ll want to incorporate it into your application’s documentation pipeline in order to have a view of your permissions that updates automatically on Read The Docs.

For example, we use the verify_auth script like this…

verify_auth tests/integration/test_app.py --output docs/src/example_policy_matrix.csv

…and include it in reStructuredText docs like this…

.. csv-table:: Policy matrix
   :file: example_policy_matrix.csv
   :header-rows: 1

…or, if you’re using MyST/Markdown…

```
{csv-table} Policy matrix
:file: example_policy_matrix.csv
:header-rows: 1
```

…to produce the following table:

Policy matrix

path	method	roles	scopes
/docs	GET	UNSECURED	UNSECURED
/docs	HEAD	UNSECURED	UNSECURED
/docs/oauth2-redirect	GET	UNSECURED	UNSECURED
/docs/oauth2-redirect	HEAD	UNSECURED	UNSECURED
/openapi.json	GET	UNSECURED	UNSECURED
/openapi.json	HEAD	UNSECURED	UNSECURED
/redoc	GET	UNSECURED	UNSECURED
/redoc	HEAD	UNSECURED	UNSECURED
/users/me/items/	GET	SW_ENGINEER	read_items
/with/client/creds	GET	APP2APP

Automating changes

If you’re using the standard SKAO documentation solutions, then you can easily add a hook to generate an up-to-date policy matrix as part of your CI/CD pipeline.

You’ll need to make sure the verify_auth script is available in your docs dependencies, that means installing ska_aaa_authhelpers[scripts] to get the scripts extras.

Then you can use the pre_build hook in your .readthedocs.yaml file to invoke verify_auth to automatically update before building the docs:

    pre_build:
    - verify_auth tests/integration/test_app.py --output docs/src/example_policy_matrix.csv

If you also want to automatically update when running make docs-build html locally and you’re using the SKAO templates, you can add a docs-pre-build hook to the Makefile in your repository:

docs-pre-build:
	verify_auth tests/integration/test_app.py --output docs/src/example_policy_matrix.csv