Merge pull request #9 from paulussimanjuntak/docs

add docs installation & usage

Author: IndominusByte

docs/index.md

@@ -1,17 +1,27 @@
-# Welcome to MkDocs
+<h1 align="center" style="margin-bottom: 20px; font-weight: 500; font-size: 50px;">
+  FastAPI JWT Auth
+</h1>
+<p align="center">
+    <em>FastAPI extension that provides JWT Auth support (secure, easy to use, and lightweight)</em>
+</p>
 
-For full documentation visit [mkdocs.org](https://www.mkdocs.org).
+[![Build Status](https://travis-ci.org/IndominusByte/fastapi-jwt-auth.svg?branch=master)](https://travis-ci.org/IndominusByte/fastapi-jwt-auth)
+[![Coverage Status](https://coveralls.io/repos/github/IndominusByte/fastapi-jwt-auth/badge.svg?branch=master)](https://coveralls.io/github/IndominusByte/fastapi-jwt-auth?branch=master)
+[![PyPI version](https://badge.fury.io/py/fastapi-jwt-auth.svg)](https://badge.fury.io/py/fastapi-jwt-auth)
+[![Downloads](https://pepy.tech/badge/fastapi-jwt-auth)](https://pepy.tech/project/fastapi-jwt-auth)
 
-## Commands
+---
 
-* `mkdocs new [dir-name]` - Create a new project.
-* `mkdocs serve` - Start the live-reloading docs server.
-* `mkdocs build` - Build the documentation site.
-* `mkdocs -h` - Print help message and exit.
+**Documentation**: <a href="https://IndominusByte.github.io/fastapi-jwt-auth/" target="_blank">https://IndominusByte.github.io/fastapi-jwt-auth/</a>
 
-## Project layout
+**Source Code**: <a href="https://github.com/IndominusByte/fastapi-jwt-auth/" target="_blank">https://github.com/IndominusByte/fastapi-jwt-auth/</a>
 
-    mkdocs.yml    # The configuration file.
-    docs/
-        index.md  # The documentation homepage.
-        ...       # Other markdown pages, images and other files.
+---
+
+## Features
+FastAPI extension that provides JWT Auth support (secure, easy to use and lightweight), if you were familiar with flask-jwt-extended this extension suitable for you because this extension inspired by flask-jwt-extended.
+
+- Access token and refresh token
+- Token freshness will only allow fresh tokens to access endpoint
+- Token revoking/blacklisting
+- Custom token revoking

docs/installation.md

@@ -0,0 +1,10 @@
+The easiest way to start working with this extension with pip
+
+```bash
+pip install fastapi-jwt-auth
+```
+
+If you want to use asymmetric (public/private) key signing algorithms, include the <b>asymmetric</b> extra requirements.
+```bash
+pip install 'fastapi-jwt-auth[asymmetric]'
+```

docs/usage/basic.md

@@ -0,0 +1,91 @@
+Create a file `basic.py`:
+
+```python
+from fastapi import FastAPI, HTTPException, Depends, Request
+from fastapi.responses import JSONResponse
+from fastapi_jwt_auth import AuthJWT
+from fastapi_jwt_auth.exceptions import AuthJWTException
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class User(BaseModel):
+    username: str
+    password: str
+
+# in production you can use Settings management
+# from pydantic to get secret key from .env
+class Settings(BaseModel):
+    authjwt_secret_key: str = "secret"
+
+# callback to get your configuration
+@AuthJWT.load_config
+def get_config():
+    return Settings()
+
+# exception handler for authjwt
+# in production, you can tweak performance using orjson response
+@app.exception_handler(AuthJWTException)
+def authjwt_exception_handler(request: Request, exc: AuthJWTException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.message}
+    )
+
+# provide a method to create access tokens. The create_access_token()
+# function is used to actually generate the token to use authorization
+# later in endpoint protected
+@app.post('/login')
+def login(user: User, Authorize: AuthJWT = Depends()):
+    if user.username != "test" and user.password != "test":
+        raise HTTPException(status_code=401,detail="Bad username or password")
+
+    # subject identifier for who this token is for example id or username from database
+    access_token = Authorize.create_access_token(subject=user.username)
+    return {"access_token": access_token}
+
+# protect endpoint with function jwt_required(), which requires
+# a valid access token in the request headers to access.
+@app.get('/user')
+def user(Authorize: AuthJWT = Depends()):
+    Authorize.jwt_required()
+
+    current_user = Authorize.get_jwt_subject()
+    return {"user": current_user}
+```
+
+Run the server with:
+
+```bash
+$ uvicorn basic:app --host 0.0.0.0
+
+INFO:     Started server process [9859]
+INFO:     Waiting for application startup.
+INFO:     Application startup complete.
+INFO:     Uvicorn running on http://0.0.0.0:8000 (Press CTRL+C to quit)
+```
+
+To access a jwt_required protected url, all we have to do is send in the JWT with the request. By default, this is done with an authorization header that looks like:
+
+```
+Authorization: Bearer <access_token>
+```
+
+We can see this in action using <b>curl</b>:
+
+```bash
+$ curl http://localhost:8000/user
+
+{"detail":"Missing Authorization Header"}
+
+$ curl -H "Content-Type: application/json" -X POST \
+  -d '{"username":"test","password":"test"}' http://localhost:8000/login
+
+{"access_token":"eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjAzNjkyMjYxLCJuYmYiOjE2MDM2OTIyNjEsImp0aSI6IjZiMjZkZTkwLThhMDYtNDEzMy04MzZiLWI5ODJkZmI3ZjNmZSIsImV4cCI6MTYwMzY5MzE2MSwidHlwZSI6ImFjY2VzcyIsImZyZXNoIjpmYWxzZX0.ro5JMHEVuGOq2YsENkZigSpqMf5cmmgPP8odZfxrzJA"}
+
+$ export TOKEN=eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJ0ZXN0IiwiaWF0IjoxNjAzNjkyMjYxLCJuYmYiOjE2MDM2OTIyNjEsImp0aSI6IjZiMjZkZTkwLThhMDYtNDEzMy04MzZiLWI5ODJkZmI3ZjNmZSIsImV4cCI6MTYwMzY5MzE2MSwidHlwZSI6ImFjY2VzcyIsImZyZXNoIjpmYWxzZX0.ro5JMHEVuGOq2YsENkZigSpqMf5cmmgPP8odZfxrzJA
+
+$ curl -H "Authorization: Bearer $TOKEN" http://localhost:8000
+
+{"user":"test"}
+```

docs/usage/freshness.md

@@ -0,0 +1,93 @@
+The fresh token pattern is built into this extension. this pattern is very simple, you can choose to mark some access tokens as fresh and other as a non-fresh token, and use the <b>fresh_jwt_required()</b> function to only allow fresh tokens to access the certain endpoint.
+
+This is useful for allowing the fresh token to do some critical things (such as update information user) in real case you can see in the GitHub system when user wants to delete a repository in a certain time you need login if token not fresh again. Utilizing Fresh tokens in conjunction with refresh tokens can lead to a more secure site, without creating a bad user experience by making users constantly re-authenticate.
+
+Here is an example of how you could utilize refresh tokens with the fresh token pattern:
+
+```python
+from fastapi import FastAPI, HTTPException, Depends, Request
+from fastapi.responses import JSONResponse
+from fastapi_jwt_auth import AuthJWT
+from fastapi_jwt_auth.exceptions import AuthJWTException
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class User(BaseModel):
+    username: str
+    password: str
+
+class Settings(BaseModel):
+    authjwt_secret_key: str = "secret"
+
+@AuthJWT.load_config
+def get_config():
+    return Settings()
+
+@app.exception_handler(AuthJWTException)
+def authjwt_exception_handler(request: Request, exc: AuthJWTException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.message}
+    )
+
+# Standard login endpoint. Will return a fresh access token and a refresh token
+@app.post('/login')
+def login(user: User, Authorize: AuthJWT = Depends()):
+    if user.username != "test" and user.password != "test":
+        raise HTTPException(status_code=401,detail="Bad username or password")
+
+    """
+    create_access_token supports an optional 'fresh' argument,
+    which marks the token as fresh or non-fresh accordingly.
+    As we just verified their username and password, we are
+    going to mark the token as fresh here.
+    """
+    access_token = Authorize.create_access_token(subject=user.username,fresh=True)
+    refresh_token = Authorize.create_refresh_token(subject=user.username)
+    return {"access_token": access_token, "refresh_token": refresh_token}
+
+@app.post('/refresh')
+def refresh(Authorize: AuthJWT = Depends()):
+    """
+    Refresh token endpoint. This will generate a new access token from
+    the refresh token, but will mark that access token as non-fresh,
+    as we do not actually verify a password in this endpoint.
+    """
+    Authorize.jwt_refresh_token_required()
+
+    current_user = Authorize.get_jwt_subject()
+    new_access_token = Authorize.create_access_token(subject=current_user,fresh=False)
+    return {"access_token": new_access_token}
+
+@app.post('/fresh-login')
+def fresh_login(user: User, Authorize: AuthJWT = Depends()):
+    """
+    Fresh login endpoint. This is designed to be used if we need to
+    make a fresh token for a user (by verifying they have the
+    correct username and password). Unlike the standard login endpoint,
+    this will only return a new access token, so that we don't keep
+    generating new refresh tokens, which entirely defeats their point.
+    """
+    if user.username != "test" and user.password != "test":
+        raise HTTPException(status_code=401,detail="Bad username or password")
+
+    new_access_token = Authorize.create_access_token(subject=user.username,fresh=True)
+    return {"access_token": new_access_token}
+
+# Any valid JWT access token can access this endpoint
+@app.get('/protected')
+def protected(Authorize: AuthJWT = Depends()):
+    Authorize.jwt_required()
+
+    current_user = Authorize.get_jwt_subject()
+    return {"user": current_user}
+
+# Only fresh JWT access token can access this endpoint
+@app.get('/protected-fresh')
+def protected_fresh(Authorize: AuthJWT = Depends()):
+    Authorize.fresh_jwt_required()
+
+    current_user = Authorize.get_jwt_subject()
+    return {"user": current_user}
+```

docs/usage/optional.md

@@ -0,0 +1,45 @@
+In some cases you want to use one endpoint for both, protected and unprotected. in this situation you can use function <b>jwt_optional()</b>. this will allow the endpoint to be accessed regardless of if a JWT is sent in the request or not. if a JWT get tampering or expired an error will be returned instead of calling the endpoint.
+
+```python
+from fastapi import FastAPI, HTTPException, Depends, Request
+from fastapi.responses import JSONResponse
+from fastapi_jwt_auth import AuthJWT
+from fastapi_jwt_auth.exceptions import AuthJWTException
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class User(BaseModel):
+    username: str
+    password: str
+
+class Settings(BaseModel):
+    authjwt_secret_key: str = "secret"
+
+@AuthJWT.load_config
+def get_config():
+    return Settings()
+
+@app.exception_handler(AuthJWTException)
+def authjwt_exception_handler(request: Request, exc: AuthJWTException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.message}
+    )
+
+@app.post('/login')
+def login(user: User, Authorize: AuthJWT = Depends()):
+    if user.username != "test" and user.password != "test":
+        raise HTTPException(status_code=401,detail="Bad username or password")
+
+    access_token = Authorize.create_access_token(subject=user.username)
+    return {"access_token": access_token}
+
+@app.get('/partially-protected')
+def partially_protected(Authorize: AuthJWT = Depends()):
+    Authorize.jwt_optional()
+
+    # If no jwt is sent in the request, get_jwt_subject() will return None
+    current_user = Authorize.get_jwt_subject() or "anonymous"
+    return {"user": current_user}
+```

docs/usage/refresh.md

@@ -0,0 +1,65 @@
+These are long-lived tokens which can be used to create new access tokens once an old access token has expired. refresh tokens cannot access an endpoint that is protected with <b>jwt_required()</b>, <b>jwt_optional()</b>, and <b>fresh_jwt_required()</b> and access tokens cannot access an endpoint that is protected with <b>jwt_refresh_token_required()</b>.
+
+Utilizing refresh tokens we can help reduce the damage that can be done if an access token is stolen. however, if an attacker gets a refresh token they can keep generating new access tokens and accessing protected endpoints as though he was that user. we can help combat this by using the fresh token pattern, discussed in the next section.
+
+Here is an example of using access and refresh tokens:
+
+```python
+from fastapi import FastAPI, HTTPException, Depends, Request
+from fastapi.responses import JSONResponse
+from fastapi_jwt_auth import AuthJWT
+from fastapi_jwt_auth.exceptions import AuthJWTException
+from pydantic import BaseModel
+
+app = FastAPI()
+
+class User(BaseModel):
+    username: str
+    password: str
+
+class Settings(BaseModel):
+    authjwt_secret_key: str = "secret"
+
+@AuthJWT.load_config
+def get_config():
+    return Settings()
+
+@app.exception_handler(AuthJWTException)
+def authjwt_exception_handler(request: Request, exc: AuthJWTException):
+    return JSONResponse(
+        status_code=exc.status_code,
+        content={"detail": exc.message}
+    )
+
+@app.post('/login')
+def login(user: User, Authorize: AuthJWT = Depends()):
+    if user.username != "test" and user.password != "test":
+        raise HTTPException(status_code=401,detail="Bad username or password")
+
+    # Use create_access_token() and create_refresh_token() to create our
+    # access and refresh tokens
+    access_token = Authorize.create_access_token(subject=user.username)
+    refresh_token = Authorize.create_refresh_token(subject=user.username)
+    return {"access_token": access_token, "refresh_token": refresh_token}
+
+@app.post('/refresh')
+def refresh(Authorize: AuthJWT = Depends()):
+    """
+    The jwt_refresh_token_required() function insures a valid refresh
+    token is present in the request before running any code below that function.
+    we can use the get_jwt_subject() function to get the subject of the refresh
+    token, and use the create_access_token() function again to make a new access token
+    """
+    Authorize.jwt_refresh_token_required()
+
+    current_user = Authorize.get_jwt_subject()
+    new_access_token = Authorize.create_access_token(subject=current_user)
+    return {"access_token": new_access_token}
+
+@app.get('/protected')
+def protected(Authorize: AuthJWT = Depends()):
+    Authorize.jwt_required()
+
+    current_user = Authorize.get_jwt_subject()
+    return {"user": current_user}
+```

docs/usage/revoking.md

@@ -0,0 +1,13 @@
+This will allow you to revoke a specific token so that it can no longer access your endpoints.you will have to choose what token you want to check against the denylist. Denylist works by providing a callback function to this extension, using the <b>token_in_denylist_loader()</b>. This method will be called whenever the specified token <i>(access and/or refresh)</i> is used to access a protected endpoint. If the callback function says that the token is revoked, we will not allow the requester to continue, otherwise we will allow the requester to access the endpoint as normal.
+
+Here is a basic example use token revoking:
+
+```python
+```
+
+In production, you will likely want to use either a database or in-memory store (such as Redis) to store your tokens. memory stores are great if you are wanting to revoke a token when the users log out and you can define timeout to your token in Redis, after the timeout has expired, the token will automatically be deleted.
+
+Here example use Redis for revoking a token:
+
+```python
+```

mkdocs.yml

@@ -5,3 +5,25 @@ theme:
 
 repo_name: IndominusByte/fastapi-jwt-auth
 repo_url: https://github.com/IndominusByte/fastapi-jwt-auth
+
+markdown_extensions:
+  - pymdownx.highlight:
+      linenums_style: pymdownx.inline
+  - pymdownx.superfences
+  - pymdownx.inlinehilite
+
+nav:
+  - About: index.md
+  - Installation: installation.md
+  - Usage:
+    - Basic Usage: usage/basic.md
+    - Partially Protecting: usage/optional.md
+    - Refresh Tokens: usage/refresh.md
+    - Token Freshness: usage/freshness.md
+    - Token Revoking: usage/revoking.md
+  - Configuration Options:
+    - General Options: configuration-options/general.md
+    - Headers Options: configuration-options/headers.md
+    - Cookies Options: configuration-options/cookies.md
+    - CSRF Options: configuration-options/csrf.md
+    - Denylist Options: configuration-options/denylist.md