starlette-auth-toolkit

Authentication backends and helpers for Starlette-based apps and frameworks.

Note: documentation is in progress — in the meantime, feel free to read the source code!

Installation

pip install starlette-auth-toolkit

Note: you need to install Starlette yourself.

Base backends

Base backends implement an authentication flow, but the exact implementation of credentials verification is left up to you. This means you can choose to perform a database query, use environment variables or private files, etc.

These backends grant a set of scopes when authentication succeeds.

Base backends are user model agnostic, although we recommend you implement the interface specified by starlette.authentication.BaseUser (see also Starlette authentication).

BasicAuthBackend

Implementation of the Basic authentication scheme.

Request header format

Authorization: Basic {credentials}

where {credentials} refers to the base64 encoding of {username}:{password}.

Abstract methods

• .verify(self, username: str, password: str) -> Optional[BaseUser]

  If username and password are valid, return the corresponding user. Otherwise, return None.

Scopes

• authenticated

Example

# myapp/auth.py
from starlette.authentication import SimpleUser  # or a custom user model
from starlette_auth_toolkit import backends

class BasicAuthBackend(backends.BasicAuthBackend):
    async def verify(self, username: str, password: str):
        # TODO: in practice, request the database to find the user associated
        # to `username`, and validate that its password hash matches the
        # given password.
        if (username, password) != ("guido", "s3kr3t"):
            return None
        return SimpleUser(username)

BearerAuthBackend

Implementation of the Bearer authentication scheme.

Note: this is sometimes also referred to as "Token authentication".

Request header format

Authorization: Bearer {token}

Abstract methods

• .verify(self, token: str) -> Optional[BaseUser]

  If token refers to a valid token, return the corresponding user. Otherwise, return None.

Scopes

• authenticated

Example

# myapp/auth.py
from starlette.authentication import SimpleUser  # or a custom user model
from starlette_auth_toolkit import backends

class BearerAuthBackend(backends.BearerAuthBackend):
    async def verify(self, token: str):
        # TODO: in practice, request the database to find the token object
        # associated to `token`, and return its associated user.
        if token != "abcd":
            return None
        return SimpleUser("bob")

Contributing

Want to contribute? Awesome! Be sure to read our Contributing guidelines.

Changelog

See CHANGELOG.md.

License

MIT