microdot.auth — HTTP-authenticatie

Decorators die routes afschermen achter HTTP-authenticatie. Er zijn twee varianten: BasicAuth voor het Authorization: Basic <base64>-schema waar browsers van nature om vragen, en TokenAuth voor het Authorization: Bearer <token>-schema dat API’s gebruiken.

Beide klassen zijn afgeleid van een gemeenschappelijke basis BaseAuth; een applicatie construeert het auth-object, registreert een authenticatie-callback met authenticate() en voorziet vervolgens beveiligde routes van de auth-instantie als decorator.

class BasicAuth

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

HTTP Basic-authenticatie. De browser toont een dialoog voor gebruikersnaam / wachtwoord wanneer een niet-geauthenticeerd verzoek een beveiligde route bereikt, en verstuurt Authorization: Basic <base64(user:pass)> bij volgende verzoeken.

realm

De realm-tekenreeks die de browser naast de prompt toont.

charset

Tekenset die wordt geadverteerd in de WWW-Authenticate-challenge.

scheme

Naam van het authenticatieschema. Standaard 'Basic'.

error_status

HTTP-status die wordt geretourneerd bij mislukte authenticatie. Standaard 401.

authenticate(f)

Decorator die de controle van inloggegevens registreert. f neemt (request, username, password) aan en retourneert het geauthenticeerde gebruikersobject (of None bij onjuiste inloggegevens). Het geretourneerde object wordt opgeslagen 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)

Een route voorzien van de BasicAuth-instantie als decorator beveiligt deze:

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

optional(f)

Net als __call__(), maar weigert geen verzoeken zonder inloggegevens – de handler wordt nog steeds uitgevoerd, met request.g.current_user ingesteld op ofwel de geauthenticeerde gebruiker ofwel None.

class TokenAuth

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

Bearer-token-authenticatie. Clients versturen een token in de Authorization-header; de applicatie valideert dit aan de hand van welke onderliggende opslag dan ook.

header

De headernaam die het token bevat. De standaardwaarde 'Authorization' verwacht de waarde Bearer <token>; een aangepaste header bevat de tokenwaarde rechtstreeks.

scheme

Auth-schema voor de Authorization-header. Standaard 'Bearer'.

error_status

HTTP-status bij mislukte authenticatie. Standaard 401.

authenticate(f)

Decorator die de tokencontrole registreert. f neemt (request, token) aan en retourneert een gebruikersobject of 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 die het standaard 401-antwoord overschrijft. f neemt het request-object aan en retourneert een antwoord (of breekt af).

__call__(f: Callable) → Callable

Een route voorzien van de TokenAuth-instantie als decorator beveiligt deze. Verzoeken zonder een geldig token worden geweigerd (standaard 401, of wat errorhandler() heeft geretourneerd). Bij succes staat de geauthenticeerde gebruiker in request.g.current_user

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

Retourneert de ingepakte handler.

optional(f: Callable) → Callable

Net als __call__(), maar weigert geen verzoeken zonder token – de handler wordt nog steeds uitgevoerd, met request.g.current_user ingesteld op ofwel de geauthenticeerde gebruiker ofwel None. Handig voor routes die hun uitvoer aanpassen op basis van of de aanroeper geauthenticeerd is, zonder dit te vereisen:

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

Retourneert de ingepakte handler.

class BaseAuth

class microdot.auth.BaseAuth

Gemeenschappelijke basis voor BasicAuth en TokenAuth. Aangepaste auth-schema’s kunnen hiervan een subklasse maken.

auth_callback: Callable | None

De callback geregistreerd via authenticate. None totdat de applicatie de callback registreert (het voorzien van een functie van @auth.authenticate als decorator stelt deze in).

error_callback: Callable

Async aanroepbaar object dat het antwoord retourneert dat wordt verstuurd bij mislukte authenticatie. Wordt door de constructor ingesteld op een standaardwaarde die een 401-antwoord retourneert; vervang het via errorhandler op TokenAuth, of rechtstreeks op een aangepaste BaseAuth-subklasse.

Bij de gedecoreerde routes wordt request.g.current_user gevuld met de waarde die de authenticatie-callback retourneert. Inspecteer binnen de route dit attribuut om de aanroeper te identificeren.