Usage

Info

This page is step by step usage.

First of all, you need to create a LoginManager instance. The login manager manage the Starlette-Login behaviour of your Starlette instance.

from starlette_login.login_manager import LoginManager

login_manager = LoginManager(redirect_to='/login_endpoint', secret_key='SECRET_KEY')

User Model Class

User class must inherit UserMixin class.

models.py

from starlette_login.mixins import UserMixin


class User(UserMixin):
    user_id: int
    name: str

    def identity(self) -> int:
        return self.user_id

    def display_name(self):
        return self.name

User Loader Callback

Then you will need to provide a user loader callback function.

from starlette.requests import Request

from models import User


async def get_user_by_id(request: Request, user_id: int):
    # return a sub class of `mixin.UserMixin` instance
    db = request.state.db
    user = await User.get_by_id(db, user_id)
    return user


login_manager.set_user_loader(get_user_by_id)

Starlette Application and Middleware

Upon creation of Starlette instance, we add SessionMiddleware and AuthenticationMiddleware.

SessionMiddleware is required to manage http and websocket session.

from starlette.applications import Starlette
from starlette.middleware import Middleware
from starlette.middleware.sessions import SessionMiddleware
from starlette_login.backends import SessionAuthBackend
from starlette_login.middleware import AuthenticationMiddleware


app = Starlette(
    middleware=[
        Middleware(SessionMiddleware, secret_key='SECRET_KEY'),
        Middleware(
            AuthenticationMiddleware,
            backend=SessionAuthBackend(login_manager),
            login_manager=login_manager,
            login_route='login',
        )
    ],
    ...
)

Then you need to add the login manager to Starlette instance state.

app.state.login_manager = login_manager

Now that the Starlette application instance is ready to use, you will need to create a login and logout route to manage user authentication.

See routes.py on Basic Example page for login and logout route example.

Decorator

Now we can filter our routes for authenticated user by using these decorators

Starlette-Login Decorator helps to prevent non-authorized user to access certain route. There are 3 available decorator:

login_required: only authenticated user can access the page
fresh_login_required: only newly logged-in user can access the page
ws_login_required: websocket route version of login_required

Usage

from starlette.requests import Request
from starlette.responses import PlainTextResponse
from starlette.websockets import WebSocket
from starlette_login.decorator import login_required, ws_login_required


@login_required
async def protected_page(request: Request):
    return PlainTextResponse(f'You are logged in as {request.user.username}')


@ws_login_required
async def ws_endpoint(websocket: WebSocket):
    await websocket.accept()
    await websocket.send_text("authenticated")
    await websocket.close()

See tests/views.py for more decorated routes example.