# 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]`](https://fastapi.tiangolo.com/fastapi-cli/) 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.

```bash
$ 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.](https://developer.skao.int/en/latest/tools/documentation.html#accessing-readthedocs)

For example, we use the `verify_auth` script like this...

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

...and include it in reStructuredText docs like this...

````rst
.. csv-table:: Policy matrix
   :file: example_policy_matrix.csv
   :header-rows: 1
````
...or, if you're using MyST/Markdown...
````markdown
```
{csv-table} Policy matrix
:file: example_policy_matrix.csv
:header-rows: 1
```
````
...to produce the following table:

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

## Automating changes

If you're using the [standard SKAO documentation solutions](https://developer.skao.int/en/latest/tools/documentation.html), 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](https://docs.readthedocs.com/platform/stable/build-customization.html) file to invoke `verify_auth` to automatically update before building the docs:

```yaml
    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](https://developer.skao.int/en/latest/howto/integrate-cicd-make.html), you can add a `docs-pre-build` hook to the Makefile in your repository:

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