Skip to content

Quickstart for cattle_grid.auth

cattle_grid.auth is just the authorization component of cattle_grid. As described in request_flow and configuration one can use it to take care of checking HTTP signatures, as an authentication step before processing the request.

  • Authentication

    Instead of checking HTTP Signatures, including resolving public keys yourself. You can let cattle_grid.auth handle it.

  • Blocks

    cattle_grid.auth allows you to manage a block list that is done on authentication level. This can be used as a first block list that contains the worst offenders.

Basic installation

First install cattle_grid from pypi via

pip install cattle_grid

To configure cattle_grid.auth, you need to supply the actor id used to fetch public keys, e.g.

python -mcattle_grid.auth new-config\
    https://your_domain.example/cattle_grid_actor

where you have to replace your_domain.example with your domain name. The path parameter can also be freely chosen. By inspecting cattle_grid_auth.toml, you can see that a public and private key was generated for this actor, e.g.

cattle_grid_auth.toml
[auth]
enabled = true
actor_id = "http://cattle_grid/cattle_grid_actor"
actor_acct_id = "acct:4ILq9osJUscnVDwe@cattle_grid"
public_key = """
-----BEGIN PUBLIC KEY-----
...
-----END PUBLIC KEY-----
"""
private_key = """
-----BEGIN PRIVATE KEY-----
...
-----END PRIVATE KEY-----
"""

This finishes the configuration of cattle_grid.

Configuring the database

By adding

cattle_grid_auth.toml
db_uri = "sqlite://other.db"

[auth]
enabled = true

one can change the db file that cattle_grid.auth is using. Similarly by setting

cattle_grid_auth.toml
db_uri = "postgres://postgres:pass@postgres"

one can set it to use a postgres database.

Running cattle_grid

You can now run cattle grid via

uvicorn --factory cattle_grid.auth:create_app

Then one needs to run

python -mcattle_grid.config

For the exposed routes see OpenAPI specification.

Warning

cattle_grid does not check that the digest is correct. This is the responsibility of your application. One can consider this a performance optimization, as it means that nginx only needs to transmit the headers to cattle_grid in order to get the authentication result.

Blocking

The blocklist of cattle_grid.auth is another toml file.

cattle_grid_block_list.toml
auth.domain_blocks = [
    "bad.example",
    "worse.example"
]

By running

python -mcattle_grid.auth block

one can view the commands available for managing the blocklist.