Start updating documentation for 4.0.0 version

Author: Landon Gilbert-Bland

4.0.0_changelog.md

@@ -109,7 +109,7 @@ Breaking Changes
       return jsonify(msg="{} has an expired jwt".format(identity)), 401
   ```
 
-* `claims_verification_loaders` has been renamed to `token_verification_loader`.
+* `claims_verification_loader` has been renamed to `token_verification_loader`.
   It now takes two arguments instead of one, which are the `jwt_header` and
   `jwt_data`
 

docs/add_custom_data_claims.rst

@@ -1,16 +1,36 @@
 Storing Data in Access Tokens
 =============================
-
 You may want to store additional information in the access token which you could
-later access in the protected views. This can be done with the
-:meth:`~flask_jwt_extended.JWTManager.user_claims_loader` decorator, and the data can be
-accessed later in a protected endpoint with the
-:func:`~flask_jwt_extended.get_jwt` function.
+later access in the protected views. This can be done using the `additional_claims`
+argument with the :func:`~flask_jwt_extended.create_access_token` or
+:func:`~flask_jwt_extended.create_refresh_token` functions. The claims
+can be accessed in a protected route via the :func:`~flask_jwt_extended.get_jwt`
+function.
 
-Storing data in an access token can be good for performance. If you store data
-in the token, you wont need to look it up from disk next time you need it in
-a protected endpoint. However, you should take care what data you put in the
-token. Any data in the access token can be trivially viewed by anyone who can
-read the token. **Do not** store sensitive information in access tokens!
+It is important to remember that JWTs are not encrypted and the contents of
+a JWT can be trivially decoded by anyone who has access to it. As such, you
+should never put any sensitive information in a JWT.
 
 .. literalinclude:: ../examples/additional_data_in_access_token.py
+
+
+Alternately you can use the :meth:`~flask_jwt_extended.JWTManager.user_claims_loader`
+decorator to register a callback function that will be called whenever a new JWT
+is created, and return a dictionary of claims to add to that token. In the case
+that both :meth:`~flask_jwt_extended.JWTManager.user_claims_loader` and the
+`additional_claims` argument are used, both results are merged together, with ties
+going to the data suplied by the `additional_claims` argument.
+
+.. code-block:: python
+
+  # Using the user_claims_loader, we can specify a method that will be
+  # called when creating JWTs. The decorated method must take the identity
+  # we are creating a token for and return a dictionary of additional
+  # claims to add to the JWT.
+  @jwt.user_claims_loader
+  def add_claims_to_access_token(identity):
+       return = {
+           "aud": "some_audience",
+           "foo": "bar",
+           "upcase_name": identity.upper(),
+       }

docs/api.rst

@@ -12,44 +12,38 @@ Configuring Flask-JWT-Extended
 
   .. automethod:: __init__
   .. automethod:: init_app
-  .. automethod:: claims_verification_loader
-  .. automethod:: claims_verification_failed_loader
   .. automethod:: decode_key_loader
   .. automethod:: encode_key_loader
   .. automethod:: expired_token_loader
   .. automethod:: invalid_token_loader
   .. automethod:: needs_fresh_token_loader
   .. automethod:: revoked_token_loader
   .. automethod:: token_in_blocklist_loader
+  .. automethod:: token_verification_failed_loader
+  .. automethod:: token_verification_loader
   .. automethod:: unauthorized_loader
   .. automethod:: user_claims_loader
   .. automethod:: user_identity_loader
-  .. automethod:: user_lookup_loader
   .. automethod:: user_lookup_error_loader
+  .. automethod:: user_lookup_loader
 
 
 Protected endpoint decorators
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 .. autofunction:: jwt_required
-.. autofunction:: jwt_refresh_token_required
-.. autofunction:: fresh_jwt_required
-.. autofunction:: jwt_optional
 
 
 .. _Verify Tokens in Request:
 
 Verify Tokens in Request
 ~~~~~~~~~~~~~~~~~~~~~~~~
-These perform the same actions as the protected endpoint decorators, without
-actually decorating a function. These are very useful if you want to create
+This performs the same actions as the protected endpoint decorators, without
+actually decorating a function. This is very useful if you want to create
 your own decorators on top of flask jwt extended (such as role_required), or
 if you want to hook some of this extensions functionality into a flask
 before_request handler.
 
 .. autofunction:: verify_jwt_in_request
-.. autofunction:: verify_jwt_in_request_optional
-.. autofunction:: verify_fresh_jwt_in_request
-.. autofunction:: verify_jwt_refresh_token_in_request
 
 
 Utilities

docs/basic_usage.rst

@@ -30,17 +30,19 @@ We can see this in action using CURL:
   $ curl -H "Content-Type: application/json" -X POST \
     -d '{"username":"test","password":"test"}' http://localhost:5000/login
   {
-    "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmcmVzaCI6dHJ1ZSwianRpIjoiZjhmNDlmMjUtNTQ4OS00NmRjLTkyOWUtZTU2Y2QxOGZhNzRlIiwidXNlcl9jbGFpbXMiOnt9LCJuYmYiOjE0NzQ0NzQ3OTEsImlhdCI6MTQ3NDQ3NDc5MSwiaWRlbnRpdHkiOiJ0ZXN0IiwiZXhwIjoxNDc0NDc1NjkxLCJ0eXBlIjoiYWNjZXNzIn0.vCy0Sec61i9prcGIRRCbG8e9NV6_wFH2ICFgUGCLKpc"
+    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTYxMTQ2MzE4MCwianRpIjoiZTBjMzhhNDUtNGM5My00NTJmLWIzZWQtOTcyZGJiNzA5YWViIiwibmJmIjoxNjExNDYzMTgwLCJ0eXBlIjoiYWNjZXNzIiwic3ViIjoidGVzdCIsImV4cCI6MTYxNDA1NTE4MH0.Qc87HZBv_qBlzcybCMoeh0SM2oyM6Waefw_xEP0VdF8"
   }
 
-  $ export ACCESS="eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJmcmVzaCI6dHJ1ZSwianRpIjoiZjhmNDlmMjUtNTQ4OS00NmRjLTkyOWUtZTU2Y2QxOGZhNzRlIiwidXNlcl9jbGFpbXMiOnt9LCJuYmYiOjE0NzQ0NzQ3OTEsImlhdCI6MTQ3NDQ3NDc5MSwiaWRlbnRpdHkiOiJ0ZXN0IiwiZXhwIjoxNDc0NDc1NjkxLCJ0eXBlIjoiYWNjZXNzIn0.vCy0Sec61i9prcGIRRCbG8e9NV6_wFH2ICFgUGCLKpc"
+  $ export JWT="eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJmcmVzaCI6ZmFsc2UsImlhdCI6MTYxMTQ2MzE4MCwianRpIjoiZTBjMzhhNDUtNGM5My00NTJmLWIzZWQtOTcyZGJiNzA5YWViIiwibmJmIjoxNjExNDYzMTgwLCJ0eXBlIjoiYWNjZXNzIiwic3ViIjoidGVzdCIsImV4cCI6MTYxNDA1NTE4MH0.Qc87HZBv_qBlzcybCMoeh0SM2oyM6Waefw_xEP0VdF8"
 
-  $ curl -H "Authorization: Bearer $ACCESS" http://localhost:5000/protected
+  $ curl -H "Authorization: Bearer $JWT" http://localhost:5000/protected
   {
     "logged_in_as": "test"
   }
 
-NOTE: Remember to change the secret key of your application, and ensure that no
-one is able to view it. The JSON Web Tokens are signed with the secret key, so
-if someone gets that, they can create arbitrary tokens, and in essence log in
-as any user.
+**Important**
+
+Remember to change the jwt secret key in your application, and ensure that it
+is secure. The JWTs are signed with this key, and if someone gets their hands
+on it they will be able to create arbitraty tokens that are accepted by your
+web flask application.

docs/changing_default_behavior.rst

@@ -23,9 +23,9 @@ and what the return values of your callback functions need to be.
 
     * - Loader Decorator
       - Description
-    * - :meth:`~flask_jwt_extended.JWTManager.claims_verification_loader`
+    * - :meth:`~flask_jwt_extended.JWTManager.token_verification_loader`
       - Function that is called to verify the user_claims data. Must return True or False
-    * - :meth:`~flask_jwt_extended.JWTManager.claims_verification_failed_loader`
+    * - :meth:`~flask_jwt_extended.JWTManager.token_verification_failed_loader`
       - Function that is called when the user claims verification callback returns False
     * - :meth:`~flask_jwt_extended.JWTManager.decode_key_loader`
       - Function that is called to get the decode key before verifying a token

examples/additional_data_in_access_token.py

@@ -13,24 +13,18 @@
 jwt = JWTManager(app)
 
 
-# Using the user_claims_loader, we can specify a method that will be
-# called when creating access tokens, and add these claims to the said
-# token. This method is passed the identity of who the token is being
-# created for, and must return data that is json serializable
-@jwt.user_claims_loader
-def add_claims_to_access_token(identity):
-    return {"hello": identity, "foo": ["bar", "baz"]}
-
-
 @app.route("/login", methods=["POST"])
 def login():
     username = request.json.get("username", None)
     password = request.json.get("password", None)
     if username != "test" or password != "test":
         return jsonify({"msg": "Bad username or password"}), 401
 
-    ret = {"access_token": create_access_token(username)}
-    return jsonify(ret), 200
+    # You can use the additional_claims argument to either add
+    # custom claims or override default claims in the JWT.
+    additional_claims = {"aud": "some_audience", "foo": "bar"}
+    access_token = create_access_token(username, additional_claims=additional_claims)
+    return jsonify(access_token=access_token)
 
 
 # In a protected view, get the claims you added to the jwt with the
@@ -39,7 +33,7 @@ def login():
 @jwt_required
 def protected():
     claims = get_jwt()
-    return jsonify({"hello_is": claims["hello"], "foo_is": claims["foo"]}), 200
+    return jsonify(foo=claims["foo"])
 
 
 if __name__ == "__main__":

examples/simple.py

@@ -14,33 +14,23 @@
 jwt = JWTManager(app)
 
 
-# Provide a method to create access tokens. The create_access_token()
-# function is used to actually generate the token, and you can return
-# it to the caller however you choose.
+# Create a route to authenticate your users and return JWTs. The
+# create_access_token() function is used to actually generate the JWT.
 @app.route("/login", methods=["POST"])
 def login():
-    if not request.is_json:
-        return jsonify({"msg": "Missing JSON in request"}), 400
-
     username = request.json.get("username", None)
     password = request.json.get("password", None)
-    if not username:
-        return jsonify({"msg": "Missing username parameter"}), 400
-    if not password:
-        return jsonify({"msg": "Missing password parameter"}), 400
-
     if username != "test" or password != "test":
         return jsonify({"msg": "Bad username or password"}), 401
 
-    # Identity can be any data that is json serializable
     access_token = create_access_token(identity=username)
-    return jsonify(access_token=access_token), 200
+    return jsonify(access_token=access_token)
 
 
-# Protect a view with jwt_required, which requires a valid access token
-# in the request to access.
+# Protect a route with jwt_required, which will kick out requests
+# without a valid JWT present.
 @app.route("/protected", methods=["GET"])
-@jwt_required
+@jwt_required()
 def protected():
     # Access the identity of the current user with get_jwt_identity
     current_user = get_jwt_identity()