✨ (Flask-JWT-Extended) Add section with everything written

Author: jslvtr

docs/docs/08_flask_jwt_extended/01_section_changes/README.md

@@ -3,4 +3,17 @@ title: Changes in this section
 description: Overview of the API endpoints we'll use for user registration and authentication.
 ---
 
-# Changes in this section
+# Changes in this section
+
+In this section we will add the following endpoints:
+
+| Method         | Endpoint          | Description                                           |
+| -------------- | ----------------- | ----------------------------------------------------- |
+| `POST`         | `/register`       | Create user accounts given an `email` and `password`. |
+| `POST`         | `/login`          | Get a JWT given an `email` and `password`.            |
+| 🔒 <br/> `POST` | `/logout`         | Revoke a JWT.                                         |
+| 🔒 <br/> `POST` | `/refresh`        | Get a fresh JWT given a refresh JWT.                  |
+| `GET`          | `/user/{user_id}` | (dev-only) Get info about a user given their ID.      |
+| `DELETE`       | `/user/{user_id}` | (dev-only) Delete a user given their ID.              |
+
+We will also protect some existing endpoints by requiring a JWT from clients. You can see which endpoints will be protected in [The API we'll build in this course](/docs/course_intro/what_is_rest_api/#the-api-well-build-in-this-course)

docs/docs/08_flask_jwt_extended/02_what_is_a_jwt/README.md

@@ -5,7 +5,17 @@ description: Understand what a JWT is, what data it contains, and how it may be
 
 # What is a JWT?
 
-- What is stored in a JWT?
-- When does a JWT expire?
-    - What happens when the JWT expires?
-- How does a client use a JWT?
+A JWT is a signed JSON object with a specific structure. Our Flask app will sign the JWTs with the secret key, proving that _it generated them_.
+
+The Flask app generates a JWT when a user logs in (with their username and password). In the JWT, we'll store the user ID. The client then stores the JWT and sends it to us on every request.
+
+Because we can prove our app generated the JWT (through its signature), and we will receive the JWT with the user ID in every request, we can _treat requests that include a JWT as "logged in"_.
+
+For example, if we want certain endpoints to only be accessible to logged-in users, all we do is require a JWT in them. Since the client can only get a JWT after logging in, we know that including a JWT is proof that the client logged in successfully at some point in the past.
+
+And since the JWT includes the user ID inside it, when we receive a JWT we know _who logged in_ to get the JWT.
+
+There's a lot more information about JWTs here: [https://jwt.io/introduction](https://jwt.io/introduction). This includes information such as:
+
+- What is stored inside a JWT?
+- Are JWTs secure?

docs/docs/08_flask_jwt_extended/03_flask_jwt_extended_setup/README.md

@@ -3,10 +3,75 @@ title: Flask-JWT-Extended setup
 description: Install and set up the Flask-JWT-Extended extension with our REST API.
 ---
 
-# Many-to-many relationships
+# Flask-JWT-Extended setup
 
 - [x] Set metadata above
-- [ ] Start writing!
+- [x] Start writing!
 - [x] Create `start` folder
 - [x] Create `end` folder
-- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+
+First, let's update our requirements:
+
+```diff title="requirements.txt"
++ flask-jwt-extended
+```
+
+Then we must do two things:
+
+- Add the extension to our `app.py`.
+- Set a secret key that the extension will use to _sign_ the JWTs.
+
+```python title="app.py"
+from flask import Flask
+from flask_smorest import Api
+# highlight-start
+from flask_jwt_extended import JWTManager
+# highlight-end
+
+from db import db
+
+from resources.item import blp as ItemBlueprint
+from resources.store import blp as StoreBlueprint
+from resources.tag import blp as TagBlueprint
+
+
+def create_app(db_url=None):
+    app = Flask(__name__)
+    app.config["API_TITLE"] = "Stores REST API"
+    app.config["API_VERSION"] = "v1"
+    app.config["OPENAPI_VERSION"] = "3.0.3"
+    app.config["OPENAPI_URL_PREFIX"] = "/"
+    app.config["OPENAPI_SWAGGER_UI_PATH"] = "/swagger-ui"
+    app.config[
+        "OPENAPI_SWAGGER_UI_URL"
+    ] = "https://cdn.jsdelivr.net/npm/swagger-ui-dist/"
+    app.config["SQLALCHEMY_DATABASE_URI"] = db_url or "sqlite:///data.db"
+    app.config["SQLALCHEMY_TRACK_MODIFICATIONS"] = False
+    app.config["PROPAGATE_EXCEPTIONS"] = True
+    db.init_app(app)
+    api = Api(app)
+
+    # highlight-start
+    app.config["JWT_SECRET_KEY"] = "jose"
+    jwt = JWTManager(app)
+    # highlight-end
+
+    @app.before_first_request
+    def create_tables():
+        import models  # noqa: F401
+
+        db.create_all()
+
+    api.register_blueprint(ItemBlueprint)
+    api.register_blueprint(StoreBlueprint)
+    api.register_blueprint(TagBlueprint)
+
+    return app
+```
+
+:::caution
+The secret key set here, `"jose"`, is **not very safe**.
+
+Instead you should generate a long and random secret key using something like `secrets.SystemRandom().getrandbits(128)`.
+:::

docs/docs/08_flask_jwt_extended/04_user_model_and_schema/README.md

@@ -9,4 +9,42 @@ description: Create the SQLAlchemy User model and marshmallow schema.
 - [ ] Start writing!
 - [x] Create `start` folder
 - [x] Create `end` folder
-- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+
+Just as we did with items, stores, and tags, let's create two classes for our users:
+
+- The SQLAlchemy model, to interact with the database.
+- The marshmallow schema, to deserialize data from clients and serialize it back to return data.
+
+## The User SQLAlchemy model
+
+```python title="models/user.py"
+from db import db
+
+
+class UserModel(db.Model):
+    __tablename__ = "users"
+
+    id = db.Column(db.Integer, primary_key=True)
+    username = db.Column(db.String(80), unique=True, nullable=False)
+    password = db.Column(db.String(80), unique=True, nullable=False)
+```
+
+Let's also add this class to `models/__init__.py` so it can then be imported by `app.py`:
+
+```python title="models/__init__.py"
+from models.user import UserModel
+from models.item import ItemModel
+from models.tag import TagModel
+from models.store import StoreModel
+from models.item_tags import ItemsTags
+```
+
+## The User marshmallow schema
+
+```python title="schemas.py"
+class UserSchema(Schema):
+    id = fields.Int(dump_only=True)
+    username = fields.Str(required=True)
+    password = fields.Str(required=True, load_only=True)
+```

docs/docs/08_flask_jwt_extended/05_registering_users_rest_api/README.md

@@ -6,7 +6,115 @@ description: Learn how to add a registration endpoint to a REST API using Flask-
 # How to add a register endpoint to the REST API
 
 - [x] Set metadata above
-- [ ] Start writing!
+- [x] Start writing!
 - [x] Create `start` folder
 - [x] Create `end` folder
-- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+
+Registering users sounds like a conceptually very difficult thing, but let's break it down into steps:
+
+- Receive username and password from the client (as JSON).
+- Check if a user with that username already exists.
+- If it doesn't...
+  - Encrypt the password.
+  - Add a new `UserModel` to the database.
+  - Return a success message.
+
+## Boilerplate set-up for a blueprint with Flask-Smorest
+
+First, we need our imports and blueprint set-up. This is the same for pretty much every Flask-Smorest blueprint, so you already know how to do it!
+
+```python title="resources/user.py"
+from flask.views import MethodView
+from flask_smorest import Blueprint, abort
+from passlib.hash import pbkdf2_sha256
+
+from db import db
+from models import UserModel
+from schemas import UserSchema
+
+
+blp = Blueprint("Users", "users", description="Operations on users")
+```
+
+## Creating the `UserRegister` resource
+
+Now let's create the `MethodView` class, and register a route to it using the blueprint:
+
+```python title="resources/user.py"
+from flask.views import MethodView
+from flask_smorest import Blueprint, abort
+from passlib.hash import pbkdf2_sha256
+
+from db import db
+from models import UserModel
+from schemas import UserSchema
+
+
+blp = Blueprint("Users", "users", description="Operations on users")
+
+
+# highlight-start
+@blp.route("/register")
+class UserRegister(MethodView):
+    @blp.arguments(UserSchema)
+    def post(self, user_data):
+        if UserModel.query.filter(UserModel.username == user_data["username"]).first():
+            abort(409, message="A user with that username already exists.")
+
+        user = UserModel(
+            username=user_data["username"],
+            password=pbkdf2_sha256.hash(user_data["password"]),
+        )
+        db.session.add(user)
+        db.session.commit()
+
+        return {"message": "User created successfully."}, 201
+# highlight-end
+```
+
+## Creating a testing-only `User` resource
+
+Let's also create a `User` resource that we will only use during testing. It allows us to retrieve information about a single user, or delete a user. This will be handy so that using Insomnia or Postman we can clear the registered users and we don't have to change our request arguments each time!
+
+```python title="resources/user.py"
+@blp.route("/user/<int:user_id>")
+class User(MethodView):
+    """
+    This resource can be useful when testing our Flask app.
+    We may not want to expose it to public users, but for the
+    sake of demonstration in this course, it can be useful
+    when we are manipulating data regarding the users.
+    """
+
+    @classmethod
+    @blp.response(200, UserSchema)
+    def get(cls, user_id: int):
+        user = UserModel.query.get_or_404(user_id)
+        return user
+
+    @classmethod
+    def delete(cls, user_id: int):
+        user = UserModel.query.get_or_404(user_id)
+        db.session.delete(user)
+        db.session.commit()
+        return {"message": "User deleted."}, 200
+```
+
+## Register the user blueprint in `app.py`
+
+Finally, let's go to `app.py` and register the blueprint!
+
+```diff title="app.py"
++from resources.user import blp as UserBlueprint
+from resources.item import blp as ItemBlueprint
+from resources.store import blp as StoreBlueprint
+from resources.tag import blp as TagBlueprint
+
+...
+
++api.register_blueprint(UserBlueprint)
+api.register_blueprint(ItemBlueprint)
+api.register_blueprint(StoreBlueprint)
+api.register_blueprint(TagBlueprint)
+```

docs/docs/08_flask_jwt_extended/06_login_users_rest_api/README.md

@@ -9,4 +9,35 @@ description: Learn how to add a login endpoint that returns a JWT to a REST API
 - [ ] Start writing!
 - [x] Create `start` folder
 - [x] Create `end` folder
-- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+- [ ] Create per-file diff between `end` and `start` (use "Compare Folders")
+
+Now that we've done registration, we can do log in! It's very similar.
+
+Let's import `flask_jwt_extended.create_access_token` so that when we receive a valid username and password from the client, we can create a JWT and send it back:
+
+```diff title="resources/user.py"
+from flask.views import MethodView
+from flask_smorest import Blueprint, abort
++from flask_jwt_extended import create_access_token
+from passlib.hash import pbkdf2_sha256
+```
+
+Then let's create our `UserLogin` resource.
+
+```python title="resources/user.py"
+@blp.route("/login")
+class UserLogin(MethodView):
+    @blp.arguments(UserSchema)
+    def post(self, user_data):
+        user = UserModel.query.filter(
+            UserModel.username == user_data["username"]
+        ).first()
+
+        if user and pbkdf2_sha256.verify(user_data["password"], user.password):
+            access_token = create_access_token(identity=user.id)
+            return {"access_token": access_token}, 200
+
+        abort(401, message="Invalid credentials.")
+```
+
+Here you can see the when we call `create_access_token(identity=user.id)` we pass in the user's `id`. This is what gets stored (among other things) inside the JWT, so when the client sends the JWT back on every request, we can tell who the JWT belongs to.