8000 📝 Update `tutorial/security/oauth2-jwt/` to use `pwdlib` with Argon2 instead of `passlib` by Neizvestnyj · Pull Request #13917 · fastapi/fastapi · GitHub
[go: up one dir, main page]

Skip to content

Conversation

@Neizvestnyj
Copy link
Contributor

Reason for Change: Migrating to pwdlib and Argon2 for Modern Password Management

This PR aims to modernize project's password hashing approach, transitioning from the aging passlib/bcrypt combination to a more contemporary and secure solution: pwdlib paired with the Argon2 algorithm.

Key Motivations for this Change:

  1. passlib & Python 3.13+ Compatibility Issue:

    • The crypt module, utilized by passlib for certain operations, is officially deprecated and slated for complete removal in Python 3.13 (as per PEP 594).
    • As highlighted by the pwdlib documentation, passlib has not been actively maintained recently, raising questions about its long-term support. This implies passlib will become incompatible with future Python versions, potentially blocking upgrades or necessitating urgent alternatives.
    • pwdlib was specifically created to address this gap, offering a modern, actively maintained tool for password hashing designed for the "modern Python era."
  2. Industry Standard and fastapi-users Adoption:

    • The fastapi-users library, commonly used fo user management in FastAPI, has already adopted pwdlib and Argon2 since version 13.0.0. This can be verified in their commit history (see v13.0.0...master comparison).
    • Their decision directly stemmed from the crypt deprecation warning (Issue #1325), underscoring the broader community's recognition of this critical issue.
  3. Argon2's Superiority Over bcrypt:

    • While bcrypt has long been a reliable choice, Argon2 is now considered the most preferred password hashing algorithm, recommended by the IETF and winner of the Password Hashing Competition.
    • GPU Attack Resistance (Memory Hardness): Argon2 is designed to be memory-hard, requiring significant amounts of memory, which makes it particularly resistant to GPU-based brute-force attacks that are becoming increasingly common. bcrypt is less resilient in this regard as it primarily relies on computational complexity.
    • Configurability: Argon2 offers more flexible parameters (time, memory, parallelism), allowing for better adaptation to specific security requirements and hardware capabilities.
    • Proven Security: Argon2 has undergone extensive cryptographic analysis and is widely regarded as a robust choice for password protection.
    • For more information on the benefits of Argon2, please refer to:

@github-actions github-actions bot added the docs Documentation about how to use FastAPI label Jul 23, 2025
@github-actions
Copy link
Contributor

@YuriiMotov
Copy link
Member
YuriiMotov commented Jul 25, 2025

Related discussions:

A few notes:

  • This makes translations of tutorial/security/oauth2-jwt/ not valid (code example is updated, but descriptions are not). Should we invalidate those translations?
  • We should probably remove passlib from project.toml and requirements-tests.txt
  • Replace passlib in conditional-openapi.md

@YuriiMotov YuriiMotov changed the title Added pwdlib support with Argon2 instead of passlib 📝 Update tutorial/security/oauth2-jwt/ to use pwdlib with Argon2 instead of passlib Jul 25, 2025
@Neizvestnyj
Copy link
Contributor Author

Related discussions:

A few notes:

  • This makes translations of tutorial/security/oauth2-jwt/ not valid (code example is updated, but descriptions are not). Should we invalidate those translations?
  • We should probably remove passlib from project.toml and requirements-tests.txt
  • Replace passlib in conditional-openapi.md

Thank you for your response and your feedback. I’ve taken it into account and removed passlib from pyproject.toml, replaced it with pwdlib in requirements-tests.txt, updated the reference to passlib in docs/en/docs/how-to/conditional-openapi.md, and updated all relevant examples that used this library.

As for the tutorials in other languages, I think we have two options: either mark them as invalid, as you suggested, or try translating them ourselves using some translation tools and then wait for native speakers to correct them if the translation isn't good.

@github-actions

This comment was marked as outdated.

@github-actions
Copy link
Contributor
github-actions bot commented Sep 5, 2025

This pull request has a merge conflict that needs to be resolved.

@github-actions github-actions bot added the conflicts Automatically generated when a PR has a merge conflict label Sep 5, 2025
@github-actions github-actions bot removed the conflicts Automatically generated when a PR has a merge conflict label Sep 26, 2025
@github-actions
Copy link
Contributor

Copy link
Member
@tiangolo tiangolo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Awesome, thank you! 🚀 🎉


I removed the Russian translation so we can do that later in another PR.

We'll do it later on our end (@YuriiMotov will do it as part of a bigger translation system upgrade). 😎

@tiangolo tiangolo merged commit efdafa4 into fastapi:master Sep 29, 2025
53 checks passed
nilslindemann added a commit to nilslindemann/fastapi that referenced this pull request Oct 1, 2025
Plus a typo fix in tutorial/security/oauth2-jwt.md line 89.
YuriiMotov added a commit that referenced this pull request Oct 1, 2025
* Sync German docs with #13917

Plus a typo fix in tutorial/security/oauth2-jwt.md line 89.

* Sync german docs with #14099

---------

Co-authored-by: Motov Yurii <109919500+YuriiMotov@users.noreply.github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

docs Documentation about how to use FastAPI

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants

0