microdot.auth — HTTP authentication

Decorators that gate routes behind HTTP authentication. Two flavors: BasicAuth for the Authorization: Basic <base64> scheme that browsers prompt for natively, and TokenAuth for the Authorization: Bearer <token> scheme that APIs use.

Both classes derive from a common BaseAuth base; an application constructs the auth object, registers an authentication callback with authenticate(), then decorates protected routes with the auth instance.

class BasicAuth

class microdot.auth.BasicAuth(realm: str = 'Please login', charset: str = 'UTF-8', scheme: str = 'Basic', error_status: int = 401)

HTTP Basic authentication. The browser pops a username / password dialog when an unauthenticated request hits a protected route and sends Authorization: Basic <base64(user:pass)> on subsequent requests.

realm

The realm string the browser shows next to the prompt.

charset

Charset advertised in the WWW-Authenticate challenge.

scheme

Authentication scheme name. Default 'Basic'.

error_status

HTTP status returned on failed authentication. Default 401.

authenticate(f)

Decorator that registers the credential check. f takes (request, username, password) and returns the authenticated user object (or None on bad credentials). The returned object is stored on request.g.current_user.

basic = BasicAuth(realm='Camera')

@basic.authenticate
async def check(request, username, password):
    user = users.get(username)
    if user and user.check_password(password):
        return user

__call__(f)

Decorating a route with the BasicAuth instance protects it:

@app.route('/admin')
@basic
def admin(request):
    return 'hello ' + request.g.current_user.name

optional(f)

Like __call__(), but does not reject requests that lack credentials – the handler still runs, with request.g.current_user set to either the authenticated user or None.

class TokenAuth

class microdot.auth.TokenAuth(header: str = 'Authorization', scheme: str = 'Bearer', error_status: int = 401)

Bearer-token authentication. Clients send a token in the Authorization header; the application validates it against whatever backing store it likes.

header

The header name carrying the token. The default 'Authorization' expects the value Bearer <token>; a custom header carries the token value directly.

scheme

Auth scheme for the Authorization header. Default 'Bearer'.

error_status

HTTP status on auth failure. Default 401.

authenticate(f)

Decorator that registers the token check. f takes (request, token) and returns a user object or None:

import jwt

tokens = TokenAuth()

@tokens.authenticate
async def check(request, token):
    try:
        claims = jwt.decode(token, SECRET)
    except jwt.exceptions.PyJWTError:
        return None
    return claims['sub']

errorhandler(f)

Decorator that overrides the default 401 response. f takes the request object and returns a response (or aborts).

__call__(f: Callable) → Callable

Decorating a route with the TokenAuth instance protects it. Requests without a valid token are rejected (401 by default, or whatever errorhandler() returned). On success the authenticated user is on request.g.current_user:

@app.get('/api/me')
@tokens
async def me(request):
    return {'user': request.g.current_user}

Returns the wrapped handler.

optional(f: Callable) → Callable

Like __call__(), but does not reject requests that lack a token – the handler still runs, with request.g.current_user set to either the authenticated user or None. Useful for routes that change their output based on whether the caller is authenticated without requiring it:

@app.get('/api/feed')
@tokens.optional
async def feed(request):
    if request.g.current_user:
        return personalized_feed(request.g.current_user)
    return public_feed()

Returns the wrapped handler.

class BaseAuth

class microdot.auth.BaseAuth

Common base for BasicAuth and TokenAuth. Custom auth schemes can subclass it.

auth_callback: Callable | None

The callback registered via authenticate. None until the application registers the callback (decorating a function with @auth.authenticate is what sets it).

error_callback: Callable

Async callable returning the response sent on auth failure. Set by the constructor to a default that returns a 401 response; replace it via errorhandler on TokenAuth, or directly on a custom BaseAuth subclass.

The decorated routes get request.g.current_user populated with the value returned from the authentication callback. Inside the route, inspect that attribute to identify the caller.