Add refresh token implementation

.all-contributorsrc

@@ -39,7 +39,8 @@
  "avatar_url": "https://avatars.githubusercontent.com/u/5875019?v=4",
  "profile": "http://matthewscholefield.github.io",
  "contributions": [
- "bug"
+ "bug",
+ "code"
  ]
  },
  {

.github/workflows/build.yml

@@ -8,7 +8,7 @@ jobs:
  runs-on: ubuntu-latest
  strategy:
  matrix:
- python_version: [3.8, 3.9, '3.10', '3.11']
+ python_version: [3.8, 3.9, '3.10', '3.11', '3.12']
 
  steps:
  - uses: actions/checkout@v3
@@ -28,7 +28,7 @@ jobs:
  runs-on: ubuntu-latest
  strategy:
  matrix:
- python_version: [3.8, 3.9, '3.10', '3.11']
+ python_version: [3.8, 3.9, '3.10', '3.11', '3.12']
 
  steps:
  - uses: actions/checkout@v3

README.md

@@ -85,7 +85,7 @@ Thanks goes to these wonderful people ([emoji key](https://allcontributors.org/d
  <td align="center" valign="top" width="14.28%"><a href="http://francoisvoron.com"><img src="https://avatars.githubusercontent.com/u/1144727?v=4?s=100" width="100px;" alt="François Voron"/><br /><sub><b>François Voron</b></sub></a><br /><a href="#maintenance-frankie567" title="Maintenance">🚧</a></td>
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/paolodina"><img src="https://avatars.githubusercontent.com/u/1157401?v=4?s=100" width="100px;" alt="Paolo Dina"/><br /><sub><b>Paolo Dina</b></sub></a><br /><a href="#financial-paolodina" title="Financial">💵</a> <a href="https://github.com/fastapi-users/fastapi-users/commits?author=paolodina" title="Code">💻</a></td>
  <td align="center" valign="top" width="14.28%"><a href="https://freelancehunt.com/freelancer/slado122.html"><img src="https://avatars.githubusercontent.com/u/46085159?v=4?s=100" width="100px;" alt="Dmytro Ohorodnik"/><br /><sub><b>Dmytro Ohorodnik</b></sub></a><br /><a href="https://github.com/fastapi-users/fastapi-users/issues?q=author%3Aslado122" title="Bug reports">🐛</a></td>
- <td align="center" valign="top" width="14.28%"><a href="http://matthewscholefield.github.io"><img src="https://avatars.githubusercontent.com/u/5875019?v=4?s=100" width="100px;" alt="Matthew D. Scholefield"/><br /><sub><b>Matthew D. Scholefield</b></sub></a><br /><a href="https://github.com/fastapi-users/fastapi-users/issues?q=author%3AMatthewScholefield" title="Bug reports">🐛</a></td>
+ <td align="center" valign="top" width="14.28%"><a href="http://matthewscholefield.github.io"><img src="https://avatars.githubusercontent.com/u/5875019?v=4?s=100" width="100px;" alt="Matthew D. Scholefield"/><br /><sub><b>Matthew D. Scholefield</b></sub></a><br /><a href="https://github.com/fastapi-users/fastapi-users/issues?q=author%3AMatthewScholefield" title="Bug reports">🐛</a> <a href="https://github.com/fastapi-users/fastapi-users/commits?author=MatthewScholefield" title="Code">💻</a></td>
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/roywes"><img src="https://avatars.githubusercontent.com/u/3861579?v=4?s=100" width="100px;" alt="roywes"/><br /><sub><b>roywes</b></sub></a><br /><a href="https://github.com/fastapi-users/fastapi-users/issues?q=author%3Aroywes" title="Bug reports">🐛</a> <a href="https://github.com/fastapi-users/fastapi-users/commits?author=roywes" title="Code">💻</a></td>
  <td align="center" valign="top" width="14.28%"><a href="https://devwriters.com"><img src="https://avatars.githubusercontent.com/u/10217535?v=4?s=100" width="100px;" alt="Satwik Kansal"/><br /><sub><b>Satwik Kansal</b></sub></a><br /><a href="https://github.com/fastapi-users/fastapi-users/commits?author=satwikkansal" title="Documentation">📖</a></td>
  <td align="center" valign="top" width="14.28%"><a href="https://github.com/eddsalkield"><img src="https://avatars.githubusercontent.com/u/30939717?v=4?s=100" width="100px;" alt="Edd Salkield"/><br /><sub><b>Edd Salkield</b></sub></a><br /><a href="https://github.com/fastapi-users/fastapi-users/commits?author=eddsalkield" title="Code">💻</a> <a href="https://github.com/fastapi-users/fastapi-users/commits?author=eddsalkield" title="Documentation">📖</a></td>

docs/configuration/password-hash.md

@@ -1,21 +1,24 @@
 # Password hash
 
-By default, FastAPI Users will use the [BCrypt algorithm](https://en.wikipedia.org/wiki/Bcrypt) to **hash and salt** passwords before storing them in the database.
+By default, FastAPI Users will use the [Argon2 algorithm](https://en.wikipedia.org/wiki/Argon2) to **hash and salt** passwords before storing them in the database, with backwards-compatibility with [Bcrypt](https://en.wikipedia.org/wiki/Bcrypt).
 
-The implementation is provided by [Passlib](https://passlib.readthedocs.io/en/stable/index.html), a battle-tested Python library for password hashing.
+The implementation is provided by [pwdlib](https://github.com/frankie567/pwdlib), a modern password hashing wrapper.
 
-## Customize `CryptContext`
+## Customize `PasswordHash`
 
-If you need to support other hashing algorithms, you can customize the [`CryptContext` object of Passlib](https://passlib.readthedocs.io/en/stable/lib/passlib.context.html#the-cryptcontext-class).
+If you need to tune the algorithms used or their settings, you can customize the [`PasswordHash` object of pwdlib](https://frankie567.github.io/pwdlib/reference/pwdlib/#pwdlib.PasswordHash).
 
-For this, you'll need to instantiate the `PasswordHelper` class and pass it your `CryptContext`. The example below shows you how you can create a `CryptContext` to add support for the Argon2 algorithm while deprecating BCrypt.
+For this, you'll need to instantiate the `PasswordHelper` class and pass it your `PasswordHash`. The example below shows you how you can create a `PasswordHash` to only support the Argon2 algorithm.
 
 ```py
 from fastapi_users.password import PasswordHelper
-from passlib.context import CryptContext
+from pwdlib import PasswordHash, exceptions
+from pwdlib.hashers.argon2 import Argon2Hasher
 
-context = CryptContext(schemes=["argon2", "bcrypt"], deprecated="auto")
-password_helper = PasswordHelper(context)
+password_hash = PasswordHash((
+ Argon2Hasher(),
+))
+password_helper = PasswordHelper(password_hash)
 ```
 
 Finally, pass the `password_helper` variable while instantiating your `UserManager`:
@@ -32,12 +35,9 @@ async def get_user_manager(user_db=Depends(get_user_db)):
 
  If it is, we take the opportunity of having the password in plain-text at hand (since the user just logged in!) to hash it with a better algorithm and update it in database.
 
-!!! warning "Dependencies for alternative algorithms are not included by default"
- FastAPI Users won't install required dependencies to make other algorithms like Argon2 work. It's up to you to install them.
-
 ## Full customization
 
-If you don't wish to use Passlib at all – **which we don't recommend unless you're absolutely sure of what you're doing** — you can implement your own `PasswordHelper` class as long as it implements the `PasswordHelperProtocol` and its methods.
+If you don't wish to use `pwdlib` at all – **which we don't recommend unless you're absolutely sure of what you're doing** — you can implement your own `PasswordHelper` class as long as it implements the `PasswordHelperProtocol` and its methods.
 
 ```py
 from typing import Tuple

fastapi_users/__init__.py

@@ -1,6 +1,6 @@
 """Ready-to-use and customizable users management for FastAPI."""
 
-__version__ = "12.1.3"
+__version__ = "13.0.0"
 
 from fastapi_users import models, schemas # noqa: F401
 from fastapi_users.exceptions import InvalidID, InvalidPasswordException

fastapi_users/authentication/__init__.py

@@ -1,6 +1,10 @@
 from fastapi_users.authentication.authenticator import Authenticator
-from fastapi_users.authentication.backend import AuthenticationBackend
-from fastapi_users.authentication.strategy import JWTStrategy, Strategy
+from fastapi_users.authentication.backend import (
+ AuthenticationBackend,
+ AuthenticationBackendRefresh,
+ BaseAuthenticationBackend,
+)
+from fastapi_users.authentication.strategy import JWTStrategy, Strategy, StrategyRefresh
 
 try:
  from fastapi_users.authentication.strategy import RedisStrategy
@@ -9,17 +13,22 @@
 
 from fastapi_users.authentication.transport import (
  BearerTransport,
+ BearerTransportRefresh,
  CookieTransport,
  Transport,
 )
 
 __all__ = [
  "Authenticator",
  "AuthenticationBackend",
+ "AuthenticationBackendRefresh",
+ "BaseAuthenticationBackend",
  "BearerTransport",
+ "BearerTransportRefresh",
  "CookieTransport",
  "JWTStrategy",
  "RedisStrategy",
  "Strategy",
+ "StrategyRefresh",
  "Transport",
 ]

fastapi_users/authentication/authenticator.py

@@ -1,13 +1,13 @@
 import re
 from inspect import Parameter, Signature
-from typing import Callable, List, Optional, Sequence, Tuple, cast
+from typing import Any, Callable, List, Optional, Sequence, Tuple, cast
 
 from fastapi import Depends, HTTPException, status
 from makefun import with_signature
 
 from fastapi_users import models
-from fastapi_users.authentication.backend import AuthenticationBackend
-from fastapi_users.authentication.strategy import Strategy
+from fastapi_users.authentication.backend import BaseAuthenticationBackend, TokenType
+from fastapi_users.authentication.strategy.base import BaseStrategy
 from fastapi_users.manager import BaseUserManager, UserManagerDependency
 from fastapi_users.types import DependencyCallable
 
@@ -31,7 +31,7 @@ class DuplicateBackendNamesError(Exception):
  pass
 
 
-EnabledBackendsDependency = DependencyCallable[Sequence[AuthenticationBackend]]
+EnabledBackendsDependency = DependencyCallable[Sequence[BaseAuthenticationBackend]]
 
 
 class Authenticator:
@@ -46,11 +46,11 @@ class Authenticator:
  :param get_user_manager: User manager dependency callable.
  """
 
- backends: Sequence[AuthenticationBackend]
+ backends: Sequence[BaseAuthenticationBackend]
 
  def __init__(
  self,
- backends: Sequence[AuthenticationBackend],
+ backends: Sequence[BaseAuthenticationBackend[models.UP, models.ID, TokenType]],
  get_user_manager: UserManagerDependency[models.UP, models.ID],
  ):
  self.backends = backends
@@ -154,16 +154,16 @@ async def _authenticate(
  verified: bool = False,
  superuser: bool = False,
  **kwargs,
- ) -> Tuple[Optional[models.UP], Optional[str]]:
+ ) -> Tuple[Optional[models.UP], Optional[Any]]:
  user: Optional[models.UP] = None
  token: Optional[str] = None
- enabled_backends: Sequence[AuthenticationBackend] = kwargs.get(
+ enabled_backends: Sequence[BaseAuthenticationBackend] = kwargs.get(
  "enabled_backends", self.backends
  )
  for backend in self.backends:
  if backend in enabled_backends:
  token = kwargs[name_to_variable_name(backend.name)]
- strategy: Strategy[models.UP, models.ID] = kwargs[
+ strategy: BaseStrategy[models.UP, models.ID, str, Any] = kwargs[
  name_to_strategy_variable_name(backend.name)
  ]
  if token is not None:

fastapi_users/authentication/backend.py

@@ -1,20 +1,26 @@
-from typing import Generic
+from typing import Generic, Optional, TypeVar
 
 from fastapi import Response, status
 
 from fastapi_users import models
+from fastapi_users.authentication.models import AccessRefreshToken
 from fastapi_users.authentication.strategy import (
- Strategy,
+ BaseStrategy,
  StrategyDestroyNotSupportedError,
+ StrategyRefresh,
 )
 from fastapi_users.authentication.transport import (
- Transport,
+ BaseTransport,
  TransportLogoutNotSupportedError,
+ TransportRefresh,
 )
+from fastapi_users.manager import BaseUserManager
 from fastapi_users.types import DependencyCallable
 
+TokenType = TypeVar("TokenType")
 
-class AuthenticationBackend(Generic[models.UP, models.ID]):
+
+class BaseAuthenticationBackend(Generic[models.UP, models.ID, TokenType]):
  """
  Combination of an authentication transport and strategy.
 
@@ -27,26 +33,33 @@ class AuthenticationBackend(Generic[models.UP, models.ID]):
  """
 
  name: str
- transport: Transport
+ transport: BaseTransport[TokenType]
 
  def __init__(
  self,
  name: str,
- transport: Transport,
- get_strategy: DependencyCallable[Strategy[models.UP, models.ID]],
+ transport: BaseTransport[TokenType],
+ get_strategy: DependencyCallable[
+ BaseStrategy[models.UP, models.ID, str, TokenType]
+ ],
  ):
  self.name = name
  self.transport = transport
  self.get_strategy = get_strategy
 
  async def login(
- self, strategy: Strategy[models.UP, models.ID], user: models.UP
+ self,
+ strategy: BaseStrategy[models.UP, models.ID, str, TokenType],
+ user: models.UP,
  ) -> Response:
  token = await strategy.write_token(user)
  return await self.transport.get_login_response(token)
 
  async def logout(
- self, strategy: Strategy[models.UP, models.ID], user: models.UP, token: str
+ self,
+ strategy: BaseStrategy[models.UP, models.ID, str, TokenType],
+ user: models.UP,
+ token: str,
  ) -> Response:
  try:
  await strategy.destroy_token(token, user)
@@ -59,3 +72,41 @@ async def logout(
  response = Response(status_code=status.HTTP_204_NO_CONTENT)
 
  return response
+
+
+class AuthenticationBackend(
+ BaseAuthenticationBackend[models.UP, models.ID, str], Generic[models.UP, models.ID]
+):
+ pass
+
+
+class AuthenticationBackendRefresh(
+ BaseAuthenticationBackend[models.UP, models.ID, AccessRefreshToken],
+ Generic[models.UP, models.ID],
+):
+ transport: TransportRefresh
+
+ def __init__(
+ self,
+ name: str,
+ transport: TransportRefresh,
+ get_strategy: DependencyCallable[StrategyRefresh[models.UP, models.ID]],
+ ):
+ super().__init__(name, transport, get_strategy)
+
+ async def refresh(
+ self,
+ strategy: StrategyRefresh[models.UP, models.ID],
+ user_manager: BaseUserManager[models.UP, models.ID],
+ refresh_token: str,
+ ) -> Optional[Response]:
+ user = await strategy.read_token_by_refresh(
+ refresh_token=refresh_token, user_manager=user_manager
+ )
+ if user is not None:
+ await strategy.destroy_token_by_refresh(
+ user=user, refresh_token=refresh_token
+ )
+ token = await strategy.write_token(user)
+ return await self.transport.get_login_response(token)
+ return None

fastapi_users/authentication/models.py

@@ -0,0 +1,6 @@
+from typing import Tuple, TypeVar
+
+TokenIdentityType = TypeVar("TokenIdentityType", contravariant=True)
+TokenType = TypeVar("TokenType", covariant=True)
+
+AccessRefreshToken = Tuple[str, str] # First is access second is refresh

fastapi_users/authentication/strategy/__init__.py

@@ -1,9 +1,14 @@
 from fastapi_users.authentication.strategy.base import (
+ BaseStrategy,
  Strategy,
  StrategyDestroyNotSupportedError,
+ StrategyRefresh,
 )
 from fastapi_users.authentication.strategy.db import (
  AP,
+ APE,
+ AccessRefreshTokenDatabase,
+ AccessRefreshTokenProtocol,
  AccessTokenDatabase,
  AccessTokenProtocol,
  DatabaseStrategy,
@@ -17,11 +22,16 @@
 
 __all__ = [
  "AP",
+ "APE",
+ "AccessRefreshTokenDatabase",
+ "AccessRefreshTokenProtocol",
  "AccessTokenDatabase",
  "AccessTokenProtocol",
+ "BaseStrategy",
  "DatabaseStrategy",
  "JWTStrategy",
  "Strategy",
  "StrategyDestroyNotSupportedError",
+ "StrategyRefresh",
  "RedisStrategy",
 ]