microdot.auth — autenticação HTTP

Decoradores que protegem rotas com autenticação HTTP. Dois tipos: BasicAuth para o esquema Authorization: Basic <base64> que os navegadores solicitam nativamente, e TokenAuth para o esquema Authorization: Bearer <token> utilizado pelas APIs.

Ambas as classes derivam de uma base comum BaseAuth; uma aplicação constrói o objeto de autenticação, regista uma callback de autenticação com authenticate() e depois decora as rotas protegidas com a instância de autenticação.

class BasicAuth

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

Autenticação HTTP Basic. O navegador apresenta uma caixa de diálogo de nome de utilizador/palavra-passe quando um pedido não autenticado atinge uma rota protegida, e envia Authorization: Basic <base64(user:pass)> nos pedidos seguintes.

realm

A cadeia de carateres realm que o navegador mostra junto ao pedido de autenticação.

charset

Conjunto de carateres anunciado no desafio WWW-Authenticate.

scheme

Nome do esquema de autenticação. Predefinição: 'Basic'.

error_status

Estado HTTP devolvido em caso de falha de autenticação. Predefinição: 401.

authenticate(f)

Decorador que regista a verificação de credenciais. f recebe (request, username, password) e devolve o objeto de utilizador autenticado (ou None se as credenciais forem inválidas). O objeto devolvido é armazenado em 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)

Decorar uma rota com a instância BasicAuth protege-a:

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

optional(f)

Semelhante a __call__(), mas não rejeita pedidos sem credenciais — o handler executa na mesma, com request.g.current_user definido como o utilizador autenticado ou None.

class TokenAuth

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

Autenticação por token Bearer. Os clientes enviam um token no cabeçalho Authorization; a aplicação valida-o contra o repositório que preferir.

header

O nome do cabeçalho que transporta o token. O valor predefinido 'Authorization' espera o valor Bearer <token>; um cabeçalho personalizado transporta o valor do token diretamente.

scheme

Esquema de autenticação para o cabeçalho Authorization. Predefinição: 'Bearer'.

error_status

Estado HTTP em caso de falha de autenticação. Predefinição: 401.

authenticate(f)

Decorador que regista a verificação do token. f recebe (request, token) e devolve um objeto de utilizador ou 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)

Decorador que substitui a resposta 401 predefinida. f recebe o objeto de pedido e devolve uma resposta (ou interrompe a execução).

__call__(f: Callable) → Callable

Decorar uma rota com a instância TokenAuth protege-a. Pedidos sem token válido são rejeitados (401 por predefinição, ou o que errorhandler() devolver). Em caso de sucesso, o utilizador autenticado encontra-se em request.g.current_user

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

Devolve o handler envolvido.

optional(f: Callable) → Callable

Semelhante a __call__(), mas não rejeita pedidos sem token — o handler executa na mesma, com request.g.current_user definido como o utilizador autenticado ou None. Útil para rotas que alteram o seu resultado consoante o chamador esteja ou não autenticado, sem o exigir:

@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()

Devolve o handler envolvido.

class BaseAuth

class microdot.auth.BaseAuth

Base comum para BasicAuth e TokenAuth. Esquemas de autenticação personalizados podem criar subclasses a partir desta.

auth_callback: Callable | None

A callback registada via authenticate. None até a aplicação registar a callback (decorar uma função com @auth.authenticate é o que a define).

error_callback: Callable

Callable assíncrono que devolve a resposta enviada em caso de falha de autenticação. Definido pelo construtor com um valor predefinido que devolve uma resposta 401; pode ser substituído via errorhandler em TokenAuth, ou diretamente numa subclasse personalizada de BaseAuth.

As rotas decoradas recebem request.g.current_user preenchido com o valor devolvido pela callback de autenticação. Dentro da rota, inspecione esse atributo para identificar o chamador.