📝 Add first Security tutorials

docs/index.md

@@ -36,7 +36,7 @@ The key features are:
 * **Easy**: Designed to be easy to use and learn. Less time reading docs.
 * **Short**: Minimize code duplication. Multiple features from each parameter declaration. Less bugs.
 * **Robust**: Get production-ready code. With automatic interactive documentation.
-* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank">OpenAPI</a> and <a href="http://json-schema.org/" target="_blank">JSON Schema</a>.
+* **Standards-based**: Based on (and fully compatible with) the open standards for APIs: <a href="https://github.com/OAI/OpenAPI-Specification" target="_blank">OpenAPI</a> (previously known as Swagger) and <a href="http://json-schema.org/" target="_blank">JSON Schema</a>.
 
 <small>* estimation based on tests on an internal development team, building production applications.</small>
 

docs/tutorial/security/first-steps.md

@@ -1,5 +1,167 @@
-Coming soon...
+Let's imagine that you have your **backend** API in some domain.
+
+And you have a **frontend** in another domain or in a different path of the same domain (or in a mobile application).
+
+And you want to have a way for the frontend to authenticate with the backend, using a **username** and **password**.
+
+We can use **OAuth2** to build that with **FastAPI**.
+
+But let's save you the time of reading the full long specification just to find those little pieces of information you need.
+
+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.
+
+## Create `main.py`
+
+Copy the example in a file `main.py`:
+
+```Python
+{!./src/security/tutorial001.py!}
+```
+
+## Run it
+
+Run the example with:
+
+```bash
+uvicorn main:app --debug
+```
+
+## Check it
+
+Go to the interactive docs at: <a href="http://127.0.0.1:8000/docs" target="_blank">http://127.0.0.1:8000/docs</a>.
+
+You will see something like this:
+
+<img src="/img/tutorial/security/image01.png">
+
+!!! check "Authorize button!"
+    You already have a shinny new "Authorize" button.
+
+    And your path operation has a little lock in the top-right corner that you can click.
+
+
+And if you click it, you have a little authorization form to type a `username` and `password` (and other optional fields):
+
+<img src="/img/tutorial/security/image02.png">
+
+!!! note
+    It doesn't matter what you type in the form, it won't work yet. But we'll get there.
+
+This is of course not the frontend for the final users, but it's a great automatic tool to document interactively all your API.
+
+It can be used by the frontend team (that can also be yourself).
+
+It can be used by third party applications and systems.
+
+And it can also be used by yourself, to debug, check and test the same application.
+
+
+## The `password` flow
+
+Now let's go back a bit and understand what is all that.
+
+The `password` "flow" is one of the ways ("flows") defined in OAuth2, to handle security and authentication.
+
+OAuth2 was designed so that the backend or API could be independent of the server that authenticates the user.
+
+But in this case, the same **FastAPI** application will handle the API and the authentication.
+
+So, let's review it from that simplified point of view:
+
+* The user types his `username` and `password` in the frontend, and hits `Enter`.
+* The frontend (running in the user's browser) sends that `username` and `password` to a specific URL in our API.
+* 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.
+* 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`
+
+**FastAPI** provides several tools, at different levels of abstraction, to implement these security features.
+
+In this example we are going to use **OAuth2**, with the **Password** flow, using a **Bearer** token.
+
+
+!!! info
+    A "bearer" token is not the only option.
+    
+    But it's the best one for our use case.
+
+    And it might be the best for most use cases, unless you are an OAuth2 expert and know exactly why there's another option that suits better your needs.
+
+    In that case, **FastAPI** also provides you with the tools to build it.
+
+`OAuth2PasswordBearer` is a class that we create passing a parameter of the URL in where the client (the frontend running in the user's browser) can use to send the `username` and `password` and get a token.
+
+```Python hl_lines="6"
+{!./src/security/tutorial001.py!}
+```
+
+It doesn't create that endpoint / path operation, but declares that that URL is the one that the client should use to get the token. That information is used in OpenAPI, and then in the interactive API documentation systems.
+
+!!! info
+    If you are a very strict "Pythonista" you might dislike the style of the parameter name `tokenUrl` instead of `token_url`.
+
+    That's because it is using the same name as in the OpenAPI spec. So that if you need to investigate more about any of these security schemes you can just copy and paste it to find more information about it.
+
+The `oauth2_scheme` variable is an instance of `OAuth2PasswordBearer`, but it is also a "callable".
+
+It could be called as:
 
 ```Python
-{!./src/security/tutorial002.py!}
+oauth2_scheme(some, parameters)
 ```
+
+So, it can be used with `Security` (as it could be used with `Depends`).
+
+## 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.
+
+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.
+
+You can try it already in the interactive docs:
+
+<img src="/img/tutorial/security/image03.png">
+
+We are not verifying the validity of the token yet, but that's a start already.
+
+## Recap
+
+So, in just 3 or 4 extra lines, you already have some primitive form of security.

docs/tutorial/security/intro.md

@@ -1,5 +1,93 @@
-Coming soon...
+There are many ways to handle security, authentication and autorization.
 
-```Python
-{!./src/security/tutorial001.py!}
-```
+And it normally is a complex and "difficult" topic.
+
+In many frameworks and systems just handling security and authentication takes a big amount of effort and code (in many cases it can be 50% or more of all the code written).
+
+**FastAPI** provides several tools to help you deal with **Security** easily, rapidly, in a standard way, without having to study and learn all the security specifications.
+
+But first, let's check some small concepts.
+
+## In a hurry?
+
+If you don't care about any of these terms and you just need to add security with authentication based on username and password *right now*, skip to the next chapters.
+
+## OAuth2
+
+OAuth2 is a specification that defines several ways to handle authentication and autorization.
+
+It is quite an extensive especification and covers several complex use cases.
+
+It includes ways to authenticate using a "third party".
+
+That's what all the system with "login with Facebook, Google, Twitter, GitHub" use underneath.
+
+### OAuth 1
+
+There was an OAuth 1, which is very different from OAuth2, and more complex, as it included directly specifications on how to encrypt the communication.
+
+It is not very popular or used nowadays.
+
+OAuth2 doesn't specify how to encrypt the communication, it expects you to have your application served with HTTPS.
+
+!!! tip
+    In the section about **deployment** you will see how to set up HTTPS for free, using Traefik and Let's Encrypt.
+
+
+## OpenID Connect
+
+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).
+
+But Facebook login doesn't support OpenID Connect. It has its own flavor of OAuth2.
+
+### OpenID (not "OpenID Connect")
+
+There was also an "OpenID" specification. That tried to solve the same thing as **OpenID Connect**, but was not based on OAuth2.
+
+So, it was a complete additional system.
+
+It is not very popular or used nowadays.
+
+## OpenAPI
+
+OpenAPI (previously known as Swagger) is the open specification for building APIs (now part of the Linux Foundation).
+
+**FastAPI** is based on **OpenAPI**.
+
+That's what makes it possible to have multiple automatic interactive documentation interfaces, code generation, etc.
+
+OpenAPI has a way to define multiple security "schemes".
+
+By using them, you can take advantage of all these standard-based tools, including these interactive documentation systems.
+
+OpenAPI defines the following security schemes:
+
+* `apiKey`: an application specific key that can come from:
+    * A query parameter.
+    * A header.
+    * A cookie.
+* `http`: standard HTTP authentication systems, including:
+    * `bearer`: a header `Authorization` with a value of `Bearer ` plus a token. This is inherited from OAuth2.
+    * 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):
+        * `implicit`
+        * `clientCredentials`
+        * `authorizationCode`
+    * But there is one specific "flow" that can be perfectly used for handling authentication in the same application directly:
+        * `password`: some next chapters will cover examples of this.
+* `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.
+
+## **FastAPI** utilities
+
+FastAPI provides several tools for each of these security schemes in the `fastapi.security` module, to 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**.
+
+And you will also see how it gets automatically integrated into the interactive documentation system.