microdot.auth — autenticazione HTTP

Decoratori che proteggono le route dietro l’autenticazione HTTP. Due varianti: BasicAuth per lo schema Authorization: Basic <base64> che i browser richiedono nativamente, e TokenAuth per lo schema Authorization: Bearer <token> utilizzato dalle API.

Entrambe le classi derivano da una base comune BaseAuth; un’applicazione costruisce l’oggetto di autenticazione, registra un callback di autenticazione con authenticate(), quindi decora le route protette con l’istanza di autenticazione.

class BasicAuth

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

Autenticazione HTTP Basic. Il browser mostra una finestra di dialogo per nome utente / password quando una richiesta non autenticata raggiunge una route protetta e invia Authorization: Basic <base64(user:pass)> nelle richieste successive.

realm

La stringa realm che il browser mostra accanto alla richiesta.

charset

Charset annunciato nella sfida WWW-Authenticate.

scheme

Nome dello schema di autenticazione. Predefinito 'Basic'.

error_status

Stato HTTP restituito in caso di autenticazione fallita. Predefinito 401.

authenticate(f)

Decoratore che registra il controllo delle credenziali. f riceve (request, username, password) e restituisce l’oggetto utente autenticato (oppure None in caso di credenziali errate). L’oggetto restituito viene memorizzato in 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)

Decorare una route con l’istanza BasicAuth la protegge:

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

optional(f)

Come __call__(), ma non rifiuta le richieste prive di credenziali – l’handler viene comunque eseguito, con request.g.current_user impostato sull’utente autenticato oppure su None.

class TokenAuth

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

Autenticazione tramite token Bearer. I client inviano un token nell’header Authorization; l’applicazione lo convalida rispetto al backing store che preferisce.

header

Il nome dell’header che trasporta il token. Il valore predefinito 'Authorization' si aspetta il valore Bearer <token>; un header personalizzato trasporta direttamente il valore del token.

scheme

Schema di autenticazione per l’header Authorization. Predefinito 'Bearer'.

error_status

Stato HTTP in caso di autenticazione fallita. Predefinito 401.

authenticate(f)

Decoratore che registra il controllo del token. f riceve (request, token) e restituisce un oggetto utente oppure 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)

Decoratore che sovrascrive la risposta 401 predefinita. f riceve l’oggetto request e restituisce una risposta (oppure interrompe).

__call__(f: Callable) → Callable

Decorare una route con l’istanza TokenAuth la protegge. Le richieste prive di un token valido vengono rifiutate (401 per impostazione predefinita, oppure qualsiasi valore restituito da errorhandler()). In caso di successo l’utente autenticato si trova in request.g.current_user

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

Restituisce l’handler avvolto.

optional(f: Callable) → Callable

Come __call__(), ma non rifiuta le richieste prive di token – l’handler viene comunque eseguito, con request.g.current_user impostato sull’utente autenticato oppure su None. Utile per le route che modificano il proprio output a seconda che il chiamante sia autenticato senza richiederlo:

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

Restituisce l’handler avvolto.

class BaseAuth

class microdot.auth.BaseAuth

Base comune per BasicAuth e TokenAuth. Schemi di autenticazione personalizzati possono ereditarne.

auth_callback: Callable | None

Il callback registrato tramite authenticate. None finché l’applicazione non registra il callback (decorare una funzione con @auth.authenticate è ciò che lo imposta).

error_callback: Callable

Callable asincrono che restituisce la risposta inviata in caso di autenticazione fallita. Impostato dal costruttore su un valore predefinito che restituisce una risposta 401; sostituiscilo tramite errorhandler su TokenAuth, oppure direttamente su una sottoclasse personalizzata di BaseAuth.

Le route decorate ricevono request.g.current_user popolato con il valore restituito dal callback di autenticazione. All’interno della route, ispeziona quell’attributo per identificare il chiamante.