✨ Use 401 with WWW-Authenticate for OAuth2 and add scope_str (#188)

docs/src/security/tutorial001.py

@@ -1,4 +1,4 @@
-from fastapi import FastAPI, Security
+from fastapi import Depends, FastAPI
 from fastapi.security import OAuth2PasswordBearer
 
 app = FastAPI()
@@ -7,5 +7,5 @@ oauth2_scheme = OAuth2PasswordBearer(tokenUrl="/token")
 
 
 @app.get("/items/")
-async def read_items(token: str = Security(oauth2_scheme)):
+async def read_items(token: str = Depends(oauth2_scheme)):
     return {"token": token}

docs/src/security/tutorial002.py

@@ -1,6 +1,6 @@
 from typing import Optional
 
-from fastapi import Depends, FastAPI, Security
+from fastapi import Depends, FastAPI
 from fastapi.security import OAuth2PasswordBearer
 from pydantic import BaseModel
 
@@ -22,7 +22,7 @@ def fake_decode_token(token):
     )
 
 
-async def get_current_user(token: str = Security(oauth2_scheme)):
+async def get_current_user(token: str = Depends(oauth2_scheme)):
     user = fake_decode_token(token)
     return user
 

docs/src/security/tutorial003.py

@@ -1,6 +1,7 @@
-from fastapi import Depends, FastAPI, HTTPException, Security
+from fastapi import Depends, FastAPI, HTTPException
 from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
 from pydantic import BaseModel
+from starlette.status import HTTP_401_UNAUTHORIZED
 
 fake_users_db = {
     "johndoe": {
@@ -53,11 +54,13 @@ def fake_decode_token(token):
     return user
 
 
-async def get_current_user(token: str = Security(oauth2_scheme)):
+async def get_current_user(token: str = Depends(oauth2_scheme)):
     user = fake_decode_token(token)
     if not user:
         raise HTTPException(
-            status_code=400, detail="Invalid authentication credentials"
+            status_code=HTTP_401_UNAUTHORIZED,
+            detail="Invalid authentication credentials",
+            headers={"WWW-Authenticate": "Bearer"},
         )
     return user
 

docs/src/security/tutorial004.py

@@ -6,7 +6,7 @@ from fastapi.security import OAuth2PasswordBearer, OAuth2PasswordRequestForm
 from jwt import PyJWTError
 from passlib.context import CryptContext
 from pydantic import BaseModel
-from starlette.status import HTTP_403_FORBIDDEN
+from starlette.status import HTTP_401_UNAUTHORIZED
 
 # to get a string like this run:
 # openssl rand -hex 32
@@ -89,7 +89,9 @@ def create_access_token(*, data: dict, expires_delta: timedelta = None):
 
 async def get_current_user(token: str = Depends(oauth2_scheme)):
     credentials_exception = HTTPException(
-        status_code=HTTP_403_FORBIDDEN, detail="Could not validate credentials"
+        status_code=HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": "Bearer"},
     )
     try:
         payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
@@ -115,7 +117,11 @@ async def get_current_active_user(current_user: User = Depends(get_current_user)
 async def login_for_access_token(form_data: OAuth2PasswordRequestForm = Depends()):
     user = authenticate_user(fake_users_db, form_data.username, form_data.password)
     if not user:
-        raise HTTPException(status_code=400, detail="Incorrect username or password")
+        raise HTTPException(
+            status_code=HTTP_401_UNAUTHORIZED,
+            detail="Incorrect username or password",
+            headers={"WWW-Authenticate": "Bearer"},
+        )
     access_token_expires = timedelta(minutes=ACCESS_TOKEN_EXPIRE_MINUTES)
     access_token = create_access_token(
         data={"sub": user.username}, expires_delta=access_token_expires

docs/src/security/tutorial005.py

@@ -11,7 +11,7 @@ from fastapi.security import (
 from jwt import PyJWTError
 from passlib.context import CryptContext
 from pydantic import BaseModel, ValidationError
-from starlette.status import HTTP_403_FORBIDDEN
+from starlette.status import HTTP_401_UNAUTHORIZED
 
 # to get a string like this run:
 # openssl rand -hex 32
@@ -106,8 +106,14 @@ def create_access_token(*, data: dict, expires_delta: timedelta = None):
 async def get_current_user(
     security_scopes: SecurityScopes, token: str = Depends(oauth2_scheme)
 ):
+    if security_scopes.scopes:
+        authenticate_value = f'Bearer scope="{security_scopes.scope_str}"'
+    else:
+        authenticate_value = f"Bearer"
     credentials_exception = HTTPException(
-        status_code=HTTP_403_FORBIDDEN, detail="Could not validate credentials"
+        status_code=HTTP_401_UNAUTHORIZED,
+        detail="Could not validate credentials",
+        headers={"WWW-Authenticate": authenticate_value},
     )
     try:
         payload = jwt.decode(token, SECRET_KEY, algorithms=[ALGORITHM])
@@ -124,7 +130,9 @@ async def get_current_user(
     for scope in security_scopes.scopes:
         if scope not in token_data.scopes:
             raise HTTPException(
-                status_code=HTTP_403_FORBIDDEN, detail="Not enough permissions"
+                status_code=HTTP_401_UNAUTHORIZED,
+                detail="Not enough permissions",
+                headers={"WWW-Authenticate": authenticate_value},
             )
     return user
 
@@ -160,3 +168,8 @@ async def read_own_items(
     current_user: User = Security(get_current_active_user, scopes=["items"])
 ):
     return [{"item_id": "Foo", "owner": current_user.username}]
+
+
+@app.get("/status/")
+async def read_system_status(current_user: User = Depends(get_current_user)):
+    return {"status": "ok"}

docs/tutorial/security/first-steps.md

@@ -12,7 +12,7 @@ Let's use the tools provided by **FastAPI** to handle security.
 
 ## How it looks
 
-But let's first just use the code and see how it works, and then we'll come back to understand what's happening.
+Let's first just use the code and see how it works, and then we'll come back to understand what's happening.
 
 ## Create `main.py`
 
@@ -77,37 +77,14 @@ So, let's review it from that simplified point of view:
 * The API checks that `username` and `password`, and responds with a "token".
     * A "token" is just a string with some content that we can use later to verify this user.
     * Normally, a token is set to expire after some time.
-    * So, the user will have to login again at some point later.
-    * And if the token is stolen, the risk is less. It is not like a permanent key that will work forever.
+        * So, the user will have to login again at some point later.
+        * And if the token is stolen, the risk is less. It is not like a permanent key that will work forever (in most of the cases).
 * The frontend stores that token temporarily somewhere.
 * The user clicks in the frontend to go to another section of the frontend web app.
 * The frontend needs to fetch some more data from the API.
     * But it needs authentication for that specific endpoint.
     * So, to authenticate with our API, it sends a header `Authorization` with a value of `Bearer ` plus the token.
     * If the token contains `foobar`, the content of the `Authorization` header would be: `Bearer foobar`.
-    * Note that although the header is case-insensitive (`Authorization` is the same as `authorization`), the value is not. So, `bearer foobar` would not be valid. It has to be `Bearer foobar`.
-
-## **FastAPI**'s `Security`
-
-### Import it
-
-The same way **FastAPI** provides a `Depends`, there is a `Security` that you can import:
-
-```Python hl_lines="1"
-{!./src/security/tutorial001.py!}
-```
-
-### Use it
-
-It is actually a subclass of `Depends`, and it has just one extra parameter that we'll see later.
-
-But by using `Security` instead of `Depends`, **FastAPI** will know that it can use this dependency to define "security schemes" in OpenAPI.
-
-```Python hl_lines="10"
-{!./src/security/tutorial001.py!}
-```
-
-In this case, we have a `Security` definition (which at the same time is a dependency definition) that will provide a `str` that is assigned to the parameter `token`.
 
 ## **FastAPI**'s `OAuth2PasswordBearer`
 
@@ -146,13 +123,30 @@ It could be called as:
 oauth2_scheme(some, parameters)
 ```
 
-So, it can be used with `Security` (as it could be used with `Depends`).
+So, it can be used with `Depends`.
+
+### Use it
+
+Now you can pass that `oauth2_scheme` in a dependency with `Depends`.
+
+```Python hl_lines="10"
+{!./src/security/tutorial001.py!}
+```
+
+This dependency will provide a `str` that is assigned to the parameter `token` of the *path operation function*.
+
+**FastAPI** will know that it can use this dependency to define a "security scheme" in the OpenAPI schema (and the automatic API docs).
+
+!!! info "Technical Details"
+    **FastAPI** will know that it can use the class `OAuth2PasswordBearer` (declared in a dependency) to define the security scheme in OpenAPI because it inherits from `fastapi.security.oauth2.OAuth2`, which in turn inherits from `fastapi.security.base.SecurityBase`.
+
+    All the security utilities that integrate with OpenAPI (and the automatic API docs) inherit from `SecurityBase`, that's how **FastAPI** can know how to integrate them in OpenAPI.
 
 ## What it does
 
 It will go and look in the request for that `Authorization` header, check if the value is `Bearer ` plus some token, and will return the token as a `str`.
 
-If it doesn't see an `Authorization` header, or the value doesn't have a `Bearer ` token, it will respond with a 403 status code error (`FORBIDDEN`) directly.
+If it doesn't see an `Authorization` header, or the value doesn't have a `Bearer ` token, it will respond with a 401 status code error (`UNAUTHORIZED`) directly.
 
 You don't even have to check if the token exists to return an error. You can be sure that if your function is executed, it will have a `str` in that token.
 

docs/tutorial/security/get-current-user.md

@@ -24,13 +24,9 @@ Let's create a dependency `get_current_user`.
 
 Remember that dependencies can have sub-dependencies?
 
-And remember that `Security` is based on `Depends`?
+`get_current_user` will have a dependency with the same `oauth2_scheme` we created before.
 
-So, we can have sub-dependencies using `Security` too.
-
-`get_current_user` will have a `Security` dependency with the same `oauth2_scheme` we created before.
-
-The same as we were doing before in the path operation directly, our new dependency will receive a `token` as a `str` from the `Security` dependency:
+The same as we were doing before in the path operation directly, our new dependency `get_current_user` will receive a `token` as a `str` from the sub-dependency `oauth2_scheme`:
 
 ```Python hl_lines="25"
 {!./src/security/tutorial002.py!}
@@ -52,15 +48,6 @@ So now we can use the same `Depends` with our `get_current_user` in the path ope
 {!./src/security/tutorial002.py!}
 ```
 
-!!! info
-    Here you could actually use `Security` instead of depends too.
-    
-    But it is not required.
-
-    The key point where you should use `Security` is when passing an instance of `OAuth2PasswordBearer`.
-
-    Because **FastAPI** will use the fact that you are using `Security` and that you are passing an instance of that class `OAuth2PasswordBearer` (that inherits from `SecurityBase`) to create all the security definitions in OpenAPI.
-
 Notice that we declare the type of `current_user` as the Pydantic model `User`.
 
 This will help us inside of the function with all the completion and type checks.
@@ -68,7 +55,7 @@ This will help us inside of the function with all the completion and type checks
 !!! tip
     You might remember that request bodies are also declared with Pydantic models.
 
-    Here **FastAPI** won't get confused because you are using `Depends` or `Security`.
+    Here **FastAPI** won't get confused because you are using `Depends`.
 
 !!! check
     The way this dependency system is designed allows us to have different dependencies (different "dependables") that all return a `User` model.
@@ -78,7 +65,7 @@ This will help us inside of the function with all the completion and type checks
 
 ## Other models
 
-You can now get the current user directly in the path operation functions and deal with the security mechanisms at the **Dependency Injection** level, using `Security`.
+You can now get the current user directly in the path operation functions and deal with the security mechanisms at the **Dependency Injection** level, using `Depends`.
 
 And you can use any model or data for the security requirements (in this case, a Pydantic model `User`).
 
@@ -88,6 +75,10 @@ Do you want to have an `id` and `email` and not have any `username` in your mode
 
 Do you want to just have a `str`? Or just a `dict`? Or a database class model instance directly? It all works the same way.
 
+You actually don't have users that log in to your application but robots, bots, or other systems, that have just an access token? Again, it all works the same.
+
+Just use any kind of model, any kind of class, any kind of database that you need for your application. **FastAPI** has you covered with the dependency injection system.
+
 
 ## Code size
 
@@ -97,7 +88,7 @@ But here's the key point.
 
 The security and dependency injection stuff is written once.
 
-And you can make it as complex as you want. And still, have it written only once, in a single place.
+And you can make it as complex as you want. And still, have it written only once, in a single place. With all the flexibility.
 
 But you can have thousands of endpoints (path operations) using the same security system.
 
@@ -115,6 +106,6 @@ You can now get the current user directly in your path operation function.
 
 We are already halfway there.
 
-We just need to add a path operation for the user / client to actually send the `username` and `password`.
+We just need to add a path operation for the user/client to actually send the `username` and `password`.
 
 That comes next.

docs/tutorial/security/intro.md

@@ -40,7 +40,7 @@ OpenID Connect is another specification, based on **OAuth2**.
 
 It just extends OAuth2 specifying some things that are relatively ambiguous in OAuth2, to try to make it more interoperable.
 
-For example, Google login used OpenID Connect (which underneath uses OAuth2).
+For example, Google login uses OpenID Connect (which underneath uses OAuth2).
 
 But Facebook login doesn't support OpenID Connect. It has its own flavor of OAuth2.
 
@@ -75,7 +75,7 @@ OpenAPI defines the following security schemes:
     * HTTP Basic authentication.
     * HTTP Digest, etc.
 * `oauth2`: all the OAuth2 ways to handle security (called "flows").
-    * Several of these flows are appropriate for delegating the authentication to a third party (like Google, Facebook, Twitter, GitHub, etc):
+    * Several of these flows are appropriate for building an OAuth 2.0 authentication provider (like Google, Facebook, Twitter, GitHub, etc):
         * `implicit`
         * `clientCredentials`
         * `authorizationCode`
@@ -84,10 +84,16 @@ OpenAPI defines the following security schemes:
 * `openIdConnect`: has a way to define how to discover OAuth2 authentication data automatically.
     * This automatic discovery is what is defined in the OpenID Connect specification.
 
+
+!!! tip
+    Integrating other authentication/authorization providers like Google, Facebook, Twitter, GitHub, etc. is also possible and relatively easy.
+
+    The most complex problem is building an authentication/authorization provider like those, but **FastAPI** gives you the tools to do it easily, while doing the heavy lifting for you.
+
 ## **FastAPI** utilities
 
-FastAPI provides several tools for each of these security schemes in the `fastapi.security` module, to simplify using these security mechanisms.
+FastAPI provides several tools for each of these security schemes in the `fastapi.security` module that simplify using these security mechanisms.
 
-In the next chapters you will see how to add security to your API in a very simple way, using the tools provided by **FastAPI**.
+In the next chapters you will see how to add security to your API using those tools provided by **FastAPI**.
 
 And you will also see how it gets automatically integrated into the interactive documentation system.

docs/tutorial/security/oauth2-jwt.md

@@ -1,4 +1,4 @@
-Now that we have all the security flow, let's make the application actually secure, using JWT tokens and secure password hashing.
+Now that we have all the security flow, let's make the application actually secure, using <abbr title="JSON Web Tokens">JWT</abbr> tokens and secure password hashing.
 
 This code is something you can actually use in your application, save the password hashes in your database, etc.
 
@@ -8,7 +8,11 @@ We are going to start from where we left in the previous chapter and increment i
 
 JWT means "JSON Web Tokens".
 
-It's a standard to codify a JSON object in a long string.
+It's a standard to codify a JSON object in a long dense string without spaces. It looks like this:
+
+```
+eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c
+```
 
 It is not encrypted, so, anyone could recover the information from the contents.
 
@@ -16,7 +20,7 @@ But it's signed. So, when you receive a token that you emitted, you can verify t
 
 That way, you can create a token with an expiration of, let's say, 1 week, and then, after a week, when the user comes back with the token, you know he's still signed into your system.
 
-And after a week, the token will be expired. And if the user (or a third party) tried to modify the token to change the expiration, you would be able to discover it, because the signature would not match.
+And after a week, the token will be expired. And if the user (or a third party) tried to modify the token to change the expiration, you would be able to discover it, because the signatures would not match.
 
 If you want to play with JWT tokens and see how they work, check <a href="https://jwt.io/" target="_blank">https://jwt.io</a>.
 
@@ -30,7 +34,7 @@ pip install pyjwt
 
 ## Password hashing
 
-"Hashing" means converting some content (a password in this case) into a sequence of bytes (just a string) that look like gibberish.
+"Hashing" means converting some content (a password in this case) into a sequence of bytes (just a string) that looks like gibberish.
 
 Whenever you pass exactly the same content (exactly the same password) you get exactly the same gibberish.
 
@@ -57,10 +61,11 @@ pip install passlib[bcrypt]
 ```
 
 !!! tip
-    With `passlib`, you could even configure it to be able to read passwords created by **Django** (among many others).
+    With `passlib`, you could even configure it to be able to read passwords created by **Django**, a **Flask** security plug-in or many others.
 
     So, you would be able to, for example, share the same data from a Django application in a database with a FastAPI application. Or gradually migrate a Django application using the same database.
 
+    And your users would be able to login from your Django app or from your **FastAPI** app, at the same time.
 
 ## Hash and verify the passwords
 
@@ -122,7 +127,7 @@ Decode the received token, verify it, and return the current user.
 
 If the token is invalid, return an HTTP error right away.
 
-```Python hl_lines="90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105"
+```Python hl_lines="90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107"
 {!./src/security/tutorial004.py!}
 ```
 
@@ -132,7 +137,7 @@ Create a `timedelta` with the expiration time of the token.
 
 Create a real JWT access token and return it.
 
-```Python hl_lines="114 115 116 117 118 119 120 121 122 123"
+```Python hl_lines="116 117 118 119 120 121 122 123 124 125 126 127 128 129"
 {!./src/security/tutorial004.py!}
 ```
 
@@ -155,9 +160,9 @@ Using these ideas, JWT can be used for way more sophisticate scenarios.
 
 In those cases, several of those entities could have the same ID, let's say `foo` (a user `foo`, a car `foo`, and a blog post `foo`).
 
-So, to avoid ID collisions, when creating the JWT token for the user, you could prefix the value of the `sub` key, e.g. with `username:`.
+So, to avoid ID collisions, when creating the JWT token for the user, you could prefix the value of the `sub` key, e.g. with `username:`. So, in this example, the value of `sub` could have been: `username:johndoe`.
 
-The important thing to have in mind is that the `sub` key should have a unique identifier across the entire application.
+The important thing to have in mind is that the `sub` key should have a unique identifier across the entire application, and it should be a string.
 
 ## Check it
 
@@ -192,7 +197,7 @@ Call the endpoint `/users/me/`, you will get the response as:
 
 <img src="/img/tutorial/security/image09.png">
 
-If you open the developer tools, you could see how the data sent and received is just the token, the password is only sent in the first request to authenticate the user:
+If you open the developer tools, you could see how the data sent and only includes the token, the password is only sent in the first request to authenticate the user and get that access token, but not afterwards:
 
 <img src="/img/tutorial/security/image10.png">
 
@@ -207,7 +212,7 @@ You can use them to add a specific set of permissions to a JWT token.
 
 Then you can give this token to a user directly or a third party, to interact with your API with a set of restrictions.
 
-You can learn how to use them and how they are integrated into **FastAPI** in the next section.
+You can learn how to use them and how they are integrated into **FastAPI** in the next chapter.
 
 ## Recap
 
@@ -227,8 +232,8 @@ And you can use directly many well maintained and widely used packages like `pas
 
 But it provides you the tools to simplify the process as much as possible without compromising flexibility, robustness or security.
 
-And you can use secure, standard protocols like OAuth2 in a relatively simple way.
+And you can use and implement secure, standard protocols, like OAuth2 in a relatively simple way.
 
-In the next (optional) section you can see how to extend this even further, using OAuth2 "scopes", for a more fine-grained permission system following standards.
+In the next (optional) section you can see how to extend this even further, using OAuth2 "scopes", for a more fine-grained permission system, following these same standards.
 
 OAuth2 with scopes (explained in the next section) is the mechanism used by many big authentication providers, like Facebook, Google, GitHub, Microsoft, Twitter, etc.

docs/tutorial/security/oauth2-scopes.md

@@ -11,11 +11,11 @@ In this section you will see how to manage authentication and authorization with
 !!! warning
     This is a more or less advanced section. If you are just starting, you can skip it.
 
-    You don't necessarily need OAuth2 scopes, you can handle authentication and authorization however you want.
+    You don't necessarily need OAuth2 scopes, and you can handle authentication and authorization however you want.
 
     But OAuth2 with scopes can be nicely integrated into your API (with OpenAPI) and your API docs.
     
-    Nevertheless, you still enforce those scopes or any other security/authorization requirement however you need in your code.
+    Nevertheless, you still enforce those scopes, or any other security/authorization requirement, however you need, in your code.
 
     In many cases, OAuth2 with scopes can be an overkill.
     
@@ -37,7 +37,7 @@ When one of these security schemes uses OAuth2, you can also declare and use sco
 
 First, let's quickly see the parts that change from the previous section about OAuth2 and JWT. Now using OAuth2 scopes:
 
-```Python hl_lines="2 5 9 13 48 66 106 115 116 117 122 123 124 125 126 131 145 158"
+```Python hl_lines="2 5 9 13 48 66 107 109 110 111 112 113 114 115 116 117 123 124 125 126 130 131 132 133 134 135 136 141 155"
 {!./src/security/tutorial005.py!}
 ```
 
@@ -53,7 +53,7 @@ The `scopes` parameter receives a `dict` with each scope as a key and the descri
 {!./src/security/tutorial005.py!}
 ```
 
-Because we are now declaring those scopes,they will show up in the API docs when you log-in/authorize.
+Because we are now declaring those scopes, they will show up in the API docs when you log-in/authorize.
 
 And you will be able to select which scopes you want to give access to: `me` and `items`.
 
@@ -65,7 +65,7 @@ This is the same mechanism used when you give permissions while logging in with
 
 Now, modify the token *path operation* to return the scopes requested.
 
-We are still using the same `OAuth2PasswordRequestForm`. It includes a property `scopes` with each scope it received.
+We are still using the same `OAuth2PasswordRequestForm`. It includes a property `scopes` with a `list` of `str`, with each scope it received in the request.
 
 And we return the scopes as part of the JWT token.
 
@@ -74,7 +74,7 @@ And we return the scopes as part of the JWT token.
 
     But in your application, for security, you should make sure you only add the scopes that the user is actually able to have, or the ones you have predefined.
 
-```Python hl_lines="145"
+```Python hl_lines="156"
 {!./src/security/tutorial005.py!}
 ```
 
@@ -99,38 +99,82 @@ In this case, it requires the scope `me` (it could require more than one scope).
     
     We are doing it here to demonstrate how **FastAPI** handles scopes declared at different levels.
 
-```Python hl_lines="5 131 158"
+```Python hl_lines="5 141 168"
 {!./src/security/tutorial005.py!}
 ```
 
+!!! info "Technical Details"
+    `Security` is actually a subclass of `Depends`, and it has just one extra parameter that we'll see later.
+
+    But by using `Security` instead of `Depends`, **FastAPI** will know that it can declare security scopes, use them internally, and document the API with OpenAPI.
+
 ## Use `SecurityScopes`
 
 Now update the dependency `get_current_user`.
 
 This is the one used by the dependencies above.
 
-Here's were we are declaring the same OAuth2 scheme we created above as a dependency: `oauth2_scheme`.
+Here's were we are using the same OAuth2 scheme we created before, declaring it as a dependency: `oauth2_scheme`.
 
-Because this dependency function doesn't have any scope requirements itself, we can use `Depends` with `oauth2_scheme`, we don't have to use `Security`.
+Because this dependency function doesn't have any scope requirements itself, we can use `Depends` with `oauth2_scheme`, we don't have to use `Security` when we don't need to specify security scopes.
 
 We also declare a special parameter of type `SecurityScopes`, imported from `fastapi.security`.
 
 This `SecurityScopes` class is similar to `Request` (`Request` was used to get the request object directly).
 
-The parameter `security_scopes` will be of type `SecurityScopes`. It will have a property `scopes` with a list containing all the scopes required by itself and all the dependencies that use this as a sub-dependency. That means, all the "dependants" or all the super-dependencies (the contrary of sub-dependencies).
+```Python hl_lines="9 107"
+{!./src/security/tutorial005.py!}
+```
 
-We verify that all the scopes required, by this dependency and all the dependants (including *path operations*), are included in the scopes provided in the token received, otherwise raise an `HTTPException`.
+## Use the `scopes`
 
-We also check that the token data is validated with the Pydantic model (catching the `ValidationError` exception), and if we get an error reading the JWT token or validating the data with Pydantic, we also raise an `HTTPException`.
+The parameter `security_scopes` will be of type `SecurityScopes`.
 
-By validating the data with Pydantic we can make sure that we have, for example, exactly a `list` of `str` with the scopes and a `str` with the `username`. Instead of, for example, a `dict`, or something else, as it could break the application at some point later.
+It will have a property `scopes` with a list containing all the scopes required by itself and all the dependencies that use this as a sub-dependency. That means, all the "dependants"... this might sound confusing, it is explained again later below.
 
+The `security_scopes` object (of class `SecurityScopes`) also provides a `scope_str` attribute with a single string, containing those scopes separated by spaces (we are going to use it).
 
-```Python hl_lines="9 13 106 48 106 115 116 117 122 123"
+We create an `HTTPException` that we can re-use (`raise`) later at several points.
+
+In this exception, we include the scopes required (if any) as a string separated by spaces (using `scope_str`). We put that string containing the scopes in in the `WWW-Authenticate` header (this is part of the spec).
+
+```Python hl_lines="107 109 110 111 112 113 114 115 116 117"
 {!./src/security/tutorial005.py!}
 ```
 
-So, as the other dependency `get_current_active_user` has as a sub-dependency this `get_current_user`, the scope `"me"` declared at `get_current_active_user` will be included in the `security_scopes.scopes` `list` inside of `get_current_user`.
+## Verify the `username` and data shape
+
+We verify that we get a `username`, and extract the scopes.
+
+And then we validate that data with the Pydantic model (catching the `ValidationError` exception), and if we get an error reading the JWT token or validating the data with Pydantic, we raise the `HTTPException` we created before.
+
+For that, we update the Pydantic model `TokenData` with a new property `scopes`.
+
+By validating the data with Pydantic we can make sure that we have, for example, exactly a `list` of `str` with the scopes and a `str` with the `username`.
+
+Instead of, for example, a `dict`, or something else, as it could break the application at some point later, making it a security risk.
+
+We also verify that we have a user with that username, and if not, we raise that same exception we created before.
+
+```Python hl_lines="48 118 119 120 121 122 123 124 125 126 127 128 129"
+{!./src/security/tutorial005.py!}
+```
+
+## Verify the `scopes`
+
+We now verify that all the scopes required, by this dependency and all the dependants (including *path operations*), are included in the scopes provided in the token received, otherwise raise an `HTTPException`.
+
+For this, we use `security_scopes.scopes`, that contains a `list` with all these scopes as `str`.
+
+```Python hl_lines="130 131 132 133 134 135 136"
+{!./src/security/tutorial005.py!}
+```
+
+## Dependency tree and scopes
+
+Let's review again this dependency tree and the scopes.
+
+As the other dependency `get_current_active_user` has as a sub-dependency this `get_current_user`, the scope `"me"` declared at `get_current_active_user` will be included in the `security_scopes.scopes` `list` inside of `get_current_user`.
 
 And as the *path operation* itself also declares a scope `"items"`, it will also be part of this `list` `security_scopes.scopes` in `get_current_user`.
 
@@ -147,15 +191,24 @@ Here's how the hierarchy of dependencies and scopes looks like:
                     * A dependency using `oauth2_scheme`.
                     * A `security_scopes` parameter of type `SecurityScopes`:
                         * This `security_scopes` parameter has a property `scopes` with a `list` containing all these scopes declared above, so:
-                            * `security_scopes.scopes` will contain `["me", "items"]`
+                            * `security_scopes.scopes` will contain `["me", "items"]` for the *path operation* `read_own_items`.
+                            * `security_scopes.scopes` will contain `["me"]` for the *path operation* `read_users_me`, because it is declared in the dependency `get_current_active_user`.
+                            * `security_scopes.scopes` will contain `[]` (nothing) for the *path operation* `read_system_status`, because it didn't declare any `Security` with `scopes`, and its dependency, `get_current_user`, doesn't declare any `scope` either.
+
+!!! tip
+    The important and "magic" thing here is that `get_current_user` will have a different list of `scopes` to check for each *path operation*.
+
+    All depending on the `scopes` declared in each *path operation* and each dependency in the dependency tree for that specific path operation.
 
 ## More details about `SecurityScopes`
 
 You can use `SecurityScopes` at any point, and in multiple places, it doesn't have to be at the "root" dependency.
 
-It will always have the security scopes declared in the current `Security` dependencies and all the super-dependencies/dependants.
+It will always have the security scopes declared in the current `Security` dependencies and all the dependants for **that specific** *path operation* and **that specific** dependency tree.
+
+Because the `SecurityScopes` will have all the scopes declared by dependants, you can use it to verify that a token has the required scopes in a central dependency function, and then declare different scope requirements in different *path operations*.
 
-Because the `SecurityScopes` will have all the scopes declared by super-dependencies/dependants, you can use it to verify that a token has the required scopes in a central dependency function, and then declare different scope requirements in different *path operations*.
+They will be checked independently for each path operation.
 
 ## Check it
 
@@ -163,7 +216,7 @@ If you open the API docs, you can authenticate and specify which scopes you want
 
 <img src="/img/tutorial/security/image11.png">
 
-If you don't select any scope, you will be "authenticated", but when you try to access `/users/me/` or `/users/me/items/` you will get an error saying that you don't have enough permissions.
+If you don't select any scope, you will be "authenticated", but when you try to access `/users/me/` or `/users/me/items/` you will get an error saying that you don't have enough permissions. You will still be able to access `/status/`.
 
 And if you select the scope `me` but not the scope `items`, you will be able to access `/users/me/` but not `/users/me/items/`.
 
@@ -181,7 +234,7 @@ But if you are building an OAuth2 application that others would connect to (i.e.
 
 The most common is the implicit flow.
 
-The most secure is the code flow, but is more complex to implement as it requires more steps. As it is more cumbersome, many providers end up suggesting the implicit flow.
+The most secure is the code flow, but is more complex to implement as it requires more steps. As it is more complex, many providers end up suggesting the implicit flow.
 
 !!! note
     It's common that each authentication provider names their flows in a different way, to make it part of their brand.

docs/tutorial/security/simple-oauth2.md

@@ -4,7 +4,7 @@ Now let's build from the previous chapter and add the missing parts to have a co
 
 We are going to use **FastAPI** security utilities to get the `username` and `password`.
 
-OAuth2 specifies that when using the "password flow" (that we are using) the client / user must send a `username` and `password` fields as form data.
+OAuth2 specifies that when using the "password flow" (that we are using) the client/user must send a `username` and `password` fields as form data.
 
 And the spec says that the fields have to be named like that. So `user-name` or `email` wouldn't work.
 
@@ -48,7 +48,7 @@ Now let's use the utilities provided by **FastAPI** to handle this.
 
 First, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depends` for the path `/token`:
 
-```Python hl_lines="2 73"
+```Python hl_lines="2 75"
 {!./src/security/tutorial003.py!}
 ```
 
@@ -67,6 +67,15 @@ First, import `OAuth2PasswordRequestForm`, and use it as a dependency with `Depe
 * An optional `client_id` (we don't need it for our example).
 * An optional `client_secret` (we don't need it for our example).
 
+!!! info
+    The `OAuth2PasswordRequestForm` is not a special class for **FastAPI** as is `OAuth2PasswordBearer`.
+    
+    `OAuth2PasswordBearer` makes **FastAPI** know that it is a security scheme. So it is added that way to OpenAPI.
+    
+    But `OAuth2PasswordRequestForm` is just a class dependency that you could have written yourself, or you could have declared `Form` parameters directly.
+    
+    But as it's a common use case, it is provided by **FastAPI** directly, just to make it easier.
+
 ### Use the form data
 
 !!! tip
@@ -80,13 +89,13 @@ If there is no such user, we return an error saying "incorrect username or passw
 
 For the error, we use the exception `HTTPException`:
 
-```Python hl_lines="1 73 74 75"
+```Python hl_lines="1 76 77 78"
 {!./src/security/tutorial003.py!}
 ```
 
 ### Check the password
 
-At this point we have a the user data from our database, but we haven't checked the password.
+At this point we have the user data from our database, but we haven't checked the password.
 
 Let's put that data in the Pydantic `UserInDB` model first.
 
@@ -96,7 +105,7 @@ If the passwords don't match, we return the same error.
 
 #### Password hashing
 
-"Hashing" means: converting some content (a password in this case) into a sequence of bytes (just a string) that look like gibberish.
+"Hashing" means: converting some content (a password in this case) into a sequence of bytes (just a string) that looks like gibberish.
 
 Whenever you pass exactly the same content (exactly the same password) you get exactly the same gibberish.
 
@@ -108,7 +117,7 @@ If your database is stolen, the thief won't have your users' plaintext passwords
 
 So, the thief won't be able to try to use that password in another system (as many users use the same password everywhere, this would be dangerous).
 
-```Python hl_lines="76 77 78 79"
+```Python hl_lines="79 80 81 82"
 {!./src/security/tutorial003.py!}
 ```
 
@@ -116,7 +125,7 @@ So, the thief won't be able to try to use that password in another system (as ma
 
 `UserInDB(**user_dict)` means:
     
-Pass the keys and values of the `user_dict` directly as key-value arguments, equivalent to:
+*Pass the keys and values of the `user_dict` directly as key-value arguments, equivalent to:*
 
 ```Python
 UserInDB(
@@ -142,14 +151,23 @@ And it should have an `access_token`, with a string containing our access token.
 For this simple example, we are going to just be completely insecure and return the same `username` as the token.
 
 !!! tip
-    In the next chapter, you will see a real secure implementation, with password hashing and JWT tokens.
+    In the next chapter, you will see a real secure implementation, with password hashing and <abbr title="JSON Web Tokens">JWT</abbr> tokens.
 
     But for now, let's focus on the specific details we need.
 
-```Python hl_lines="81"
+```Python hl_lines="84"
 {!./src/security/tutorial003.py!}
 ```
 
+!!! tip
+    By the spec, you should return a JSON with an `access_token` and a `token_type`, the same as in this example.
+
+    This is something that you have to do yourself in your code, and make sure you use those JSON keys.
+
+    It's almost the only thing that you have to remember to do correctly yourself, to be compliant with the specifications.
+    
+    For the rest, **FastAPI** handles it for you.
+
 ## Update the dependencies
 
 Now we are going to update our dependencies.
@@ -162,10 +180,25 @@ Both of these dependencies will just return an HTTP error if the user doesn't ex
 
 So, in our endpoint, we will only get a user if the user exists, was correctly authenticated, and is active:
 
-```Python hl_lines="56 57 58 59 60 61 62 65 66 67 68 85"
+```Python hl_lines="57 58 59 60 61 62 63 64 65 68 69 70 71 88"
 {!./src/security/tutorial003.py!}
 ```
 
+!!! info
+    The additional header `WWW-Authenticate` with value `Bearer` we are returning here is also part of the spec.
+
+    Any HTTP (error) status code 401 "UNAUTHORIZED" is supposed to also return a `WWW-Authenticate` header.
+
+    In the case of bearer tokens (our case), the value of that header should be `Bearer`.
+
+    You can actually skip that extra header and it would still work.
+
+    But it's provided here to be compliant with the specifications.
+
+    Also, there might be tools that expect and use it (now or in the future) and that might be useful for you or your users, now or in the future.
+
+    That's the benefit of standards...
+
 ## See it in action
 
 Open the interactive docs: <a href="http://127.0.0.1:8000/docs" target="_blank">http://127.0.0.1:8000/docs</a>.
@@ -204,7 +237,7 @@ You will get your user's data, like:
 
 <img src="/img/tutorial/security/image06.png">
 
-If you click the lock icon and logout, and then try the same operation again, you will get an HTTP 403 error of:
+If you click the lock icon and logout, and then try the same operation again, you will get an HTTP 401 error of:
 
 ```JSON
 {
@@ -238,4 +271,4 @@ Using these tools, you can make the security system compatible with any database
 
 The only detail missing is that it is not actually "secure" yet.
 
-In the next chapter you'll see how to use a secure password hashing library and JWT tokens.
+In the next chapter you'll see how to use a secure password hashing library and <abbr title="JSON Web Tokens">JWT</abbr> tokens.

fastapi/security/oauth2.py

@@ -1,12 +1,12 @@
 from typing import List, Optional
 
+from fastapi.exceptions import HTTPException
 from fastapi.openapi.models import OAuth2 as OAuth2Model, OAuthFlows as OAuthFlowsModel
 from fastapi.params import Form
 from fastapi.security.base import SecurityBase
 from fastapi.security.utils import get_authorization_scheme_param
-from starlette.exceptions import HTTPException
 from starlette.requests import Request
-from starlette.status import HTTP_403_FORBIDDEN
+from starlette.status import HTTP_401_UNAUTHORIZED, HTTP_403_FORBIDDEN
 
 
 class OAuth2PasswordRequestForm:
@@ -154,7 +154,9 @@ class OAuth2PasswordBearer(OAuth2):
         if not authorization or scheme.lower() != "bearer":
             if self.auto_error:
                 raise HTTPException(
-                    status_code=HTTP_403_FORBIDDEN, detail="Not authenticated"
+                    status_code=HTTP_401_UNAUTHORIZED,
+                    detail="Not authenticated",
+                    headers={"WWW-Authenticate": "Bearer"},
                 )
             else:
                 return None
@@ -164,3 +166,4 @@ class OAuth2PasswordBearer(OAuth2):
 class SecurityScopes:
     def __init__(self, scopes: List[str] = None):
         self.scopes = scopes or []
+        self.scope_str = " ".join(self.scopes)

tests/test_tutorial/test_security/test_tutorial001.py

@@ -41,8 +41,9 @@ def test_openapi_schema():
 
 def test_no_token():
     response = client.get("/items")
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Not authenticated"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"
 
 
 def test_token():
@@ -53,5 +54,6 @@ def test_token():
 
 def test_incorrect_token():
     response = client.get("/items", headers={"Authorization": "Notexistent testtoken"})
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Not authenticated"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"

tests/test_tutorial/test_security/test_tutorial003.py

@@ -135,8 +135,9 @@ def test_login_incorrect_username():
 
 def test_no_token():
     response = client.get("/users/me")
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Not authenticated"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"
 
 
 def test_token():
@@ -153,16 +154,18 @@ def test_token():
 
 def test_incorrect_token():
     response = client.get("/users/me", headers={"Authorization": "Bearer nonexistent"})
-    assert response.status_code == 400
+    assert response.status_code == 401
     assert response.json() == {"detail": "Invalid authentication credentials"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"
 
 
 def test_incorrect_token_type():
     response = client.get(
         "/users/me", headers={"Authorization": "Notexistent testtoken"}
     )
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Not authenticated"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"
 
 
 def test_inactive_user():

tests/test_tutorial/test_security/test_tutorial005.py

@@ -80,24 +80,31 @@ openapi_schema = {
                 "security": [{"OAuth2PasswordBearer": ["items", "me"]}],
             }
         },
+        "/status/": {
+            "get": {
+                "responses": {
+                    "200": {
+                        "description": "Successful Response",
+                        "content": {"application/json": {"schema": {}}},
+                    }
+                },
+                "summary": "Read System Status",
+                "operationId": "read_system_status_status__get",
+                "security": [{"OAuth2PasswordBearer": []}],
+            }
+        },
     },
     "components": {
         "schemas": {
-            "Body_login_for_access_token": {
-                "title": "Body_login_for_access_token",
-                "required": ["username", "password"],
+            "User": {
+                "title": "User",
+                "required": ["username"],
                 "type": "object",
                 "properties": {
-                    "grant_type": {
-                        "title": "Grant_Type",
-                        "pattern": "password",
-                        "type": "string",
-                    },
                     "username": {"title": "Username", "type": "string"},
-                    "password": {"title": "Password", "type": "string"},
-                    "scope": {"title": "Scope", "type": "string", "default": ""},
-                    "client_id": {"title": "Client_Id", "type": "string"},
-                    "client_secret": {"title": "Client_Secret", "type": "string"},
+                    "email": {"title": "Email", "type": "string"},
+                    "full_name": {"title": "Full_Name", "type": "string"},
+                    "disabled": {"title": "Disabled", "type": "boolean"},
                 },
             },
             "Token": {
@@ -109,15 +116,21 @@ openapi_schema = {
                     "token_type": {"title": "Token_Type", "type": "string"},
                 },
             },
-            "User": {
-                "title": "User",
-                "required": ["username"],
+            "Body_login_for_access_token": {
+                "title": "Body_login_for_access_token",
+                "required": ["username", "password"],
                 "type": "object",
                 "properties": {
+                    "grant_type": {
+                        "title": "Grant_Type",
+                        "pattern": "password",
+                        "type": "string",
+                    },
                     "username": {"title": "Username", "type": "string"},
-                    "email": {"title": "Email", "type": "string"},
-                    "full_name": {"title": "Full_Name", "type": "string"},
-                    "disabled": {"title": "Disabled", "type": "boolean"},
+                    "password": {"title": "Password", "type": "string"},
+                    "scope": {"title": "Scope", "type": "string", "default": ""},
+                    "client_id": {"title": "Client_Id", "type": "string"},
+                    "client_secret": {"title": "Client_Secret", "type": "string"},
                 },
             },
             "ValidationError": {
@@ -204,8 +217,9 @@ def test_login_incorrect_username():
 
 def test_no_token():
     response = client.get("/users/me")
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Not authenticated"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"
 
 
 def test_token():
@@ -225,16 +239,18 @@ def test_token():
 
 def test_incorrect_token():
     response = client.get("/users/me", headers={"Authorization": "Bearer nonexistent"})
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Could not validate credentials"}
+    assert response.headers["WWW-Authenticate"] == 'Bearer scope="me"'
 
 
 def test_incorrect_token_type():
     response = client.get(
         "/users/me", headers={"Authorization": "Notexistent testtoken"}
     )
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Not authenticated"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"
 
 
 def test_verify_password():
@@ -257,8 +273,9 @@ def test_token_no_sub():
             "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJkYXRhIjoiZm9vIn0.9ynBhuYb4e6aW3oJr_K_TBgwcMTDpRToQIE25L57rOE"
         },
     )
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Could not validate credentials"}
+    assert response.headers["WWW-Authenticate"] == 'Bearer scope="me"'
 
 
 def test_token_no_username():
@@ -268,8 +285,9 @@ def test_token_no_username():
             "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJmb28ifQ.NnExK_dlNAYyzACrXtXDrcWOgGY2JuPbI4eDaHdfK5Y"
         },
     )
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Could not validate credentials"}
+    assert response.headers["WWW-Authenticate"] == 'Bearer scope="me"'
 
 
 def test_token_no_scope():
@@ -277,8 +295,9 @@ def test_token_no_scope():
     response = client.get(
         "/users/me", headers={"Authorization": f"Bearer {access_token}"}
     )
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Not enough permissions"}
+    assert response.headers["WWW-Authenticate"] == 'Bearer scope="me"'
 
 
 def test_token_inexistent_user():
@@ -288,8 +307,9 @@ def test_token_inexistent_user():
             "Authorization": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJ1c2VybmFtZTpib2IifQ.HcfCW67Uda-0gz54ZWTqmtgJnZeNem0Q757eTa9EZuw"
         },
     )
-    assert response.status_code == 403
+    assert response.status_code == 401
     assert response.json() == {"detail": "Could not validate credentials"}
+    assert response.headers["WWW-Authenticate"] == 'Bearer scope="me"'
 
 
 def test_token_inactive_user():
@@ -311,3 +331,19 @@ def test_read_items():
     )
     assert response.status_code == 200
     assert response.json() == [{"item_id": "Foo", "owner": "johndoe"}]
+
+
+def test_read_system_status():
+    access_token = get_access_token()
+    response = client.get(
+        "/status/", headers={"Authorization": f"Bearer {access_token}"}
+    )
+    assert response.status_code == 200
+    assert response.json() == {"status": "ok"}
+
+
+def test_read_system_status_no_token():
+    response = client.get("/status/")
+    assert response.status_code == 401
+    assert response.json() == {"detail": "Not authenticated"}
+    assert response.headers["WWW-Authenticate"] == "Bearer"