Token auth is a simple approach to authentication, which is most suitable for mobile apps and embedded systems.
Each user / client has a token generated for them. The token is just a random string - no information is embedded within it, as is the case with JWT.
When a client makes a request, the token needs to be added as a header. The
user object associated with this token is then retrieved from a
TokenAuthProvider. By default, this is a Piccolo table, but you can
implement your own token provider if you so choose.
The token doesn’t expire. It’s suitable for mobile apps and other systems where tokens can be securely stored on the device. The client logic is simple to implement, as you don’t have to worry about refreshing your token.
The client has to make a request which includes the Authorization HTTP header, with a value of Bearer SOMETOKEN.
The middleware builds upon Starlette’s
TokenAuthBackend is used to extract the token from the request. If the token
is present and correct, then the request is accepted and the corresponding user
is added to the scope, otherwise it is rejected.
TokenAuthBackend can work with several different
subclasses. The following are provided by default, but custom ones can be
written by creating your own
This provider checks whether the token provided by the client matches a list of predefined tokens.
from starlette.middleware.authentication import AuthenticationMiddleware from piccolo_api.token_auth.middleware import ( TokenAuthBackend, SecretTokenAuthProvider, ) app = AuthenticationMiddleware( my_asgi_app, backend=TokenAuthBackend(SecretTokenAuthProvider(tokens=["abc123"])), )
If successful a user called secret_token_user is added to the scope.
This provider is useful for protecting internal services, where the client is trusted not to leak the tokens.
It is also useful for protecting login endpoints when accessed from native apps. The client provides the token to be able to access the login endpoint, after which they obtain a unique token, which is used to authenticate with other endpoints.
This provider checks a Piccolo database table for a corresponding token, and retrieves a matching user ID. It is the default provider.
from starlette.middleware.authentication import AuthenticationMiddleware from piccolo_api.token_auth.middleware import ( TokenAuthBackend, SecretTokenAuthProvider, ) app = AuthenticationMiddleware( my_asgi_app, backend=PiccoloTokenAuthProvider(), )
You’ll have to run the migrations for this to work correctly.
If using Piccolo as a backend, there is an endpoint for logging in, which will return a token.