Login Manager
LoginManager
is where we set the configuration for authentication.
When creating the instance, redirect_to
and secret_key
argument must be provided.
This redirect_to
parameter is url name of redirect route that authentication is
required error will be redirected to.
redirect_to
value is either:
- the complete route name that is resolvable by
Request.url_for
method - path if the value contains
/
character.
from starlette_login.login_manager import LoginManager
login_manager = LoginManager(redirect_to='login', secret_key='secretkey')
The login_manager
instance is going to be passed to Starlette
application state, authentication Backend and Middleware.
Protection Level
There are 2 protection level Basic
(default) and Strong
.
Protection level will affect session and cookie session when session identifier (hash of user-agent and IP address) changed.
When the session is permanent and protection level is Strong
,
then the session will simply be marked as non-fresh,
and anything requiring a fresh login will force the user
to re-authenticate while Basic
will only mark
the current session as non-fresh
.
If the identifiers do not match in Strong
mode for a non-permanent session,
then the entire session (as well as the remember-token if it exists) is deleted.
Usage
from starlette_login.login_manager import Config, LoginManager, ProtectionLevel
config = Config(protection_level=ProtectionLevel.Strong)
login_manager = LoginManager(
redirect_to='login', secret_key='secretkey', config=config
)
User Loader Callback
You need to set up user loader callback
function to load user
for authentication session.
Callback signature
import typing
from starlette.requests import Request
# async def / def
async def load_user(request: Request, user_id: typing.Any):
...
return user
Usage
Websocket Authentication Error Callback
If you need to send custom message on ws_login_required
decorated router,
You can call login_manager.set_ws_not_authenticated
method.
By default, authentication error will close the websocket connection.
Usage
from starlette.websockets import WebSocket
async def custom_ws_auth_error(websocket: WebSocket):
await websocket.send_text('not authenticated')
await websocket.close()
login_manager.set_ws_not_authenticated(custom_ws_auth_error)
Config
You can pass custom configuration to LoginManager
instance to set custom cookie
values such as:
- COOKIE_NAME
- COOKIE_DURATION
- COOKIE_PATH
- COOKIE_DOMAIN
- COOKIE_SECURE
- COOKIE_HTTPONLY
- COOKIE_SAMESITE
See Configuration section for more information.