Allow user accounts to be activated via an activation_callback, which is called in the /register route to handle user verification, resolving #106.

User accounts created through the /register route have is_active == True if and only if activation_callback is supplied to get_register_router.

The activation_callback expects a token, which if supplied to the /activate route will activate the user upon token verification.

The semantics of after_register have been changed slightly: it's called at the point when an activated user has been created. If no activation_callback is supplied, it's called after the /register route. Otherwise, it's called after the /activate route; then any desired behaviour to be run after /register should be put in the activation_callback.

This PR additionally:

• Adds new error codes to fastapi_users/router/common.py
• Update documentation
• Add tests
• Is backward-compatible with all previous function interfaces.

Co-authored-by: Mark Todd

Hi @frankie567

Sometimes in a "production" application using fastapi-user (with Gunicorn and uvicorn and concurrency), I have this error I'm not unable to reproduce by myself in dev mode.

It occurs sometime at registration when two users want to register in the same two minutes. I don't know if it's related to the use of Fastapi-user but maybe I can find some help here to understand this error :-)

In fact this UUID mentioned in the error below appear to be the uuid of the previous saved user. I'm wondering if it's not a concurrency issue with gunicorn?

DuplicateKeyError: E11000 duplicate key error collection: myproject_db.users index: id_1 dup key: { id: UUID("c8ff467d-d490-4e32-b0b6-21ac94905dd5") }, full error: {'index': 0, 'code': 11000, 'keyPattern': {'id': 1}, 'keyValue': {'id': UUID('c8ff467d-d490-4e32-b0b6-21ac94905dd5')}, 'errmsg': 'E11000 duplicate key error collection: myproject_db.users index: id_1 dup key: { id: UUID("c8ff467d-d490-4e32-b0b6-21ac94905dd5") }'} File "myprojectapp/core/proxy_headers_middleware.py", line 43, in call return await self.app(scope, receive, send) File "starlette/middleware/cors.py", line 86, in call await self.simple_response(scope, receive, send, request_headers=headers) File "starlette/middleware/cors.py", line 142, in simple_response await self.app(scope, receive, send) File "starlette/exceptions.py", line 82, in call raise exc from None File "starlette/exceptions.py", line 71, in call await self.app(scope, receive, sender) File "starlette/routing.py", line 566, in call await route.handle(scope, receive, send) File "starlette/routing.py", line 227, in handle await self.app(scope, receive, send) File "starlette/routing.py", line 41, in app response = await func(request) File "fastapi/routing.py", line 183, in app dependant=dependant, values=values, is_coroutine=is_coroutine File "fastapi/routing.py", line 133, in run_endpoint_function return await dependant.call(**values) File "fastapi_users/router/register.py", line 38, in register created_user = await user_db.create(db_user) File "fastapi_users/db/mongodb.py", line 64, in create await self.collection.insert_one(user.dict()) File "concurrent/futures/thread.py", line 57, in run result = self.fn(*self.args, **self.kwargs) File "pymongo/collection.py", line 701, in insert_one session=session), File "pymongo/collection.py", line 615, in _insert bypass_doc_val, session) File "pymongo/collection.py", line 603, in _insert_one acknowledged, _insert_command, session) File "pymongo/mongo_client.py", line 1498, in _retryable_write return self._retry_with_session(retryable, func, s, None) File "pymongo/mongo_client.py", line 1384, in _retry_with_session return self._retry_internal(retryable, func, session, bulk) File "pymongo/mongo_client.py", line 1416, in _retry_internal return func(session, sock_info, retryable) File "pymongo/collection.py", line 600, in _insert_command _check_write_command_response(result) File "pymongo/helpers.py", line 230, in _check_write_command_response _raise_last_write_error(write_errors) File "pymongo/helpers.py", line 211, in _raise_last_write_error raise DuplicateKeyError(error.get("errmsg"), 11000, error)

Got a decent-sized project already built on SQLAlchemy. I'm using fastapi-sqlalchemy to inject a Session object into routes. Alternatively, FastAPI's documentation uses samples of SessionLocal = sessionmaker(... bind=engine) used with injection:

# Dependency
def get_db():
    db = SessionLocal()
    try:
        yield db
    finally:
        db.close()
...
@app.post("/users")
def create_user(..., db: Session = Depends(get_db)):
    ...

I figured: that's fine, I'll have fastapi-users's use of databases alongside my use of SQLAlchemy. But I'm hitting all sorts of snags in how fastapi-users loads the user model for downstream tasks, and how my app intends to work with such. Pretty vague, I'll update this ticket with specific issues as I unravel them (currently just error-mania and hard to wrap my head around). But in the meantime, I'm wondering what your thoughts are on supporting passing a sqlalchemy.orm.session object into SQLAlchemyUserDatabase instead of a databases.Database object? Something like:

# change this
database = databases.Database(DB_URL)
fastapi_users = FastAPIUsers(
    SQLAlchemyUserDatabase(UserDB, database, User.__table__), 
    [jwt_authentication], User, UserCreate, UserUpdate, UserDB,
)
# to this
engine = sqlalchemy.create_engine(DB_URL)
Sess = sqlalchemy.orm.sessionmaker(autocommit=False, autoflush=False, bind=engine)
fastapi_users = FastAPIUsers(
    SQLAlchemyUserDatabase(UserDB, Sess, User.__table__), 
    [jwt_authentication], User, UserCreate, UserUpdate, UserDB,
)

First of all, well done 👏🏼 I'm really impressed by the ideas, quality of code and documentation.

I'm thinking about adding email verification. Yes, it has some complexity, because you need to verify email after registration and when changing email but it's still essential for many apps.

I got inspired by forgot-password and reset-password routes. Here is my idea:

1. generate-token route that takes an email as input and returns a token.
2. on_after_generate_token event to handle email sending or what ever.
3. verify-token route that takes the generated token and returns a relevant status code.

Do you think it would work that way or there is a better way?

I am trying to migrate from old version but suggested script for MongoDB

db.getCollection('users').find().forEach(function(user) {
  var uuid = UUID(user.id);
  db.getCollection('users').update({_id: user._id}, [{$set: {id: uuid}}]);
});

gives an error

[thread1] Error: Invalid UUID string: UUID("49caa9b2-a1f1-4459-bc4c-7e5a5d7d88e1") :

so later i created new account and clearly see, that something have changed

Update I managed to update user in DB(?) well I think so, but nothing have changed(still same as showed in first picture) using admin user (which one was created in old version), I can't login, using a new one I can

This causes issues when integrating the openapi schema into openapi-generator. Because the code generator expects the response to be a JSON, as it should be.

Hi, First of all, great job. It's a very useful library.

However, after having setup my project. I noticed a few issues in the generated Swagger documentation. Indeed, the request body is pre-filled with the following information:

{
  "id": "string",
  "email": "[email protected]",
  "is_active": true,
  "is_superuser": false,
  "password": "string"
}

However, according to your documentation, only the fields email & password are required. It can lead to some misunderstandings for someone wanting to use the API for the first time since the Swagger (or redoc) should describe how to use the API.

I think it's a cheap fix that can be very useful for when you'll find a solution for adding auth in the Swagger. Indeed, after having had a look at your code, one solution could be to make the models BaseUserCreate and BaseUserUpdate not to inherit from BaseUser but BaseModel instead.

Looking forward to hearing from you :)

Hi @frankie567,

I would like to propose to return a 403 whenever a user is known but doesn't have enough privileges to access a resource and return a 401 if a user could not be authenticated at all (wrong or no credentials provided). This follows the conventions outlined in rfc7235 and lets fastapi-users play nicely with frontend frameworks such as vue-auth which will log you out on receiving a 401.

Let me know if you agree, so I can also update the tests.

Iḿ trying make custom user with fastapi_users,

so

from fastapi_users import models from fastapi_users.db import TortoiseBaseUserModel, TortoiseUserDatabase import datetime

class User(models.BaseUser):

nome: str = "defaultuserteste"
data_criado: str = datetime.datetime.now()
is_fund: bool = False
is_agendador: bool = False
is_revisor: bool = False
is_aprovador: bool = False

class UserCreate(models.BaseUserCreate):

nome: str = "defaultuserteste"
data_criado: str = datetime.datetime.now()
is_fund: bool = False
is_agendador: bool = False
is_revisor: bool = False
is_aprovador: bool = False

class UserUpdate(User, models.BaseUserUpdate):

nome: str = "defaultuserteste"
data_criado: str = datetime.datetime.now()
is_fund: bool = False
is_agendador: bool = False
is_revisor: bool = False
is_aprovador: bool = False

class UserDB(User, models.BaseUserDB):

nome: str = "defaultuserteste"
data_criado: str = datetime.datetime.now()
is_fund: bool = False
is_agendador: bool = False
is_revisor: bool = False
is_aprovador: bool = False

class UserModel(TortoiseBaseUserModel):

nome: str = "defaultuserteste"
data_criado: str = datetime.datetime.now()
is_fund: bool = False
is_agendador: bool = False
is_revisor: bool = False
is_aprovador: bool = False

user_db = TortoiseUserDatabase(UserDB, UserModel)

Database not changed i'm using mysql ... nothings happening.

Describe the bug

There is an error with tortoise orm 0.18.1 using aerich, when I ugrade to 0.19.0 the error goes away but the tortoise orm adapter lock to versions below 0.19.0, there is already a PR from a dependatbot fixing this, it just needs to be reviewed. The error in question is AttributeError: 'NoneType' object has no attribute 'acquire' when using the aerich upgrade command.

To Reproduce

Steps to reproduce the behavior:

1. Install fastapi-users
2. Setup Tortoise orm with fastapi-users
3. Install aerich
4. Initialize your database with aerich
5. Make a DB model change
6. Run aerich upgrade

Expected behavior

AttributeError: 'NoneType' object has no attribute 'acquire'

Configuration

• Python version : 3.10
• FastAPI version : 0.75.2
• FastAPI Users version : 9.3.2
• Tortoise Orm version: 0.18.1

This is not specific to fastapi users and the fix is quite simple.

I send the login params and if the user is not found on db, the app just raise an internal console exception with this message:

tortoise.exceptions.DoesNotExist: Object does not exist

I have a frontend interface running on different port...so when I try to see the response from the login request, there is no message on browser console, just error 500, with no description. Is there a way of add one ?

This is a draft for feedback, and follows on from this discussion earlier in the year: https://github.com/fastapi-users/fastapi-users/discussions/350

I've made a first attempt here at implementing refresh tokens and the "freshness pattern" from fastapi-jwt-auth. It doesn't yet have any updates to docs, etc, as I'd like to get your initial input first.

Breaking changes

Any implementation of these features involves breaking changes to parts of the API. This is, unfortunately, inevitable because any solution will need to address these challenges:

Token metadata

It's no longer sufficient to determine whether a token simply exists for a given user and strategy, because we now also need to:

• Determine a token's "fresh" status
• Distinguish between an access token and a refresh token

For JWTStrategy this is straightforward (adding additional claims to the token), but for other strategies this requires non-backward-compatible changes. In this solution, that includes storing JSON in the Redis value for RedisStrategy and adding additional fields for DatabaseStrategy.

We also need to consider how to store and retrieve this metadata with the Strategy. For this I propose a Pydantic model, UserTokenData, which wraps the user object (conforming to UserProtocol) and its metadata. In this first draft I've created four metadata fields:

| Field | Description | | --- | --- | | created_at: datetime | the UTC datetime when the token was issued | | expires_at: Optional[datetime] | the UTC datetime when the token expires - this is no longer set by the Strategy but passed in by the AuthenticationBackend (see below) | | last_authenticated: datetime | the UTC datetime when the user was last explicitly authenticated (not with a refresh token) - a token is considered "fresh" when created_at == last_authenticated | | scopes: Set[str] | distinguishes between an access and refresh token, and can be extended for other purposes later |

Token response model

It's now no longer sufficient for a Transport instance to receive a string as a token, as it now needs to process an access tokan and (optionally) a refresh token. In this draft I've created a model

class TransportTokenResponse(BaseModel):
    access_token: str
    refresh_token: Optional[str] = None

which replaces the previous str type expected by Transport.get_login_response.

Moving token lifetime to AuthenticationBackend

As access tokens and refresh tokens have different lifetimes - and this could be extended to other token types in future - I've proposed removing the token lifetime configuration from Strategy and instead setting it in AuthenticationBackend, as well as whether refresh tokens should be generated and accepted:

    access_token_lifetime_seconds: Optional[int] = 3600,
    refresh_token_enabled: bool = False,
    refresh_token_lifetime_seconds: Optional[int] = 86400,

New features

New refresh router

I've added an OAuth2-compatible token refresh router, get_refresh_router in refresh.py for processing refresh tokens.

New "fresh" keyword arg in Authenticator methods

• The public methods in Authenticator now have a fresh: bool keyword arg, which, when true, will throw 403 Forbidden if the token is not fresh.
• I've also added an additional method, current_token, for users who need to inspect the token metadata.

Scopes

I've borrowed the concept of OAuth2 scopes to distinguish between access tokens and refresh tokens, and I've also defined some additional scopes to distinguish between classes of users.

| Enum | String | Description | | --- | --- | --- | | SystemScope.USER | "fastapi-users:user" | An access token belonging to an active user | | SystemScope.SUPERUSER | "fastapi-users:superuser" | An access token belonging to an active superuser | | SystemScope.VERIFIED | "fastapi-users:verified" | An access token belonging to an active and verified user | | SystemScope.REFRESH | "fastapi-users:refresh" | A refresh token |

This could be developed further - for example, both system- and user-defined routes could have "required scopes" that restrict what routes a particular token is permitted to access. By adding user-defined scopes, this could be used as a basis for a general-purpose user permissions system.

Potential additional features

The following additional security measures might be valuable but would require additional work:

• Preventing refresh token reuse: store the created_at datetime for the most recently used refresh token so that it (and any older refresh token) cannot be reused.
• Refreshing OAuth2 tokens: on token refresh, refresh an associated OAuth2 token with the original provider if it has expired
• Checking for revoked OAuth2 tokens: on token refresh, re-verify an associated OAuth2 token with the original provider

Open questions

• How should CookieTransport handle the concept of refresh tokens? Currently it ignores them entirely.

Alternative ideas

• This could be implemented in a non-breaking way by implementing it only for IWTStrategy and BearerTransport and having any use of refresh tokens / freshness with other strategies raise a NotImplementedError, but I do think it's possible that users will want this for other strategies and transports.
• I also considered using separate strategies for access and refresh tokens by adding a get_refresh_strategy to AuthenticationBackend, but this adds additional complexity. If this is something that user feedback indicates would be likely to be used I could add it back in.

Feedback welcome

Please let me know whether this is heading in the right direction and what other changes / different approaches you might have in mind!

Discussed in https://github.com/fastapi-users/fastapi-users/discussions/1047

It's possible to have it thanks to asgi-csrf. A detailed explanation and example in the doc would be nice.

Add an alert in the Cookie authentication backend to invite the user to check it out.