diff --git a/docs/get-started/basic-usage.md b/docs/get-started/basic-usage.md new file mode 100644 index 00000000..1e97f2e5 --- /dev/null +++ b/docs/get-started/basic-usage.md @@ -0,0 +1,96 @@ +# Basic Usage + +The core concept of Authx relies on generating access tokens and protecting routes. The following examples demonstrate how to use Authx to quickly integrate those systems within your FastAPI application. + +```py +from fastapi import FastAPI, Depends, HTTPException +from authx import AuthX, AuthXConfig + +app = FastAPI(title="My Base App") + +config = AuthXConfig() +config.JWT_ALGORITHM = "HS256" +config.JWT_SECRET_KEY = "SECRET_KEY" + +security = AuthX(config=config) + +@app.get('/login') +def login(username: str, password: str): + if username == "test" and password == "test": + token = security.create_access_token(uid=username) + return {"access_token": token} + raise HTTPException(401, detail={"message": "Bad credentials"}) + +@app.get("/protected", dependencies=[Depends(security.access_token_required)]) +def get_protected(): + return {"message": "Hello World"} +``` + +## Getting Started + +Let's build our first FastAPI application with Authx. + +As usual, you create your application with the `fastapi.FastAPI` object + +```py hl_lines="1 4" +from fastapi import FastAPI, Depends, HTTPException +from authx import AuthX, AuthXConfig + +app = FastAPI(title="My Base App") + +config = AuthXConfig() +config.JWT_ALGORITHM = "HS256" +config.JWT_SECRET_KEY = "SECRET_KEY" + +security = AuthX(config=config) +``` + +### Create the `AuthXConfig` Instance + +```py hl_lines="2 6-7" +from fastapi import FastAPI, Depends, HTTPException +from authx import AuthX, AuthXConfig + +app = FastAPI(title="My Base App") + +config = AuthXConfig() +config.JWT_ALGORITHM = "HS256" +config.JWT_SECRET_KEY = "SECRET_KEY" + +security = AuthX(config=config) +``` + +AuthX provides an `AuthXConfig` object (based on Pydantic's `BaseSettings`) to customize the behavior of JWT management. + +Here, we enforce a **symmetric** encryption algorithm, specifically `"HS256"`, and set the `SECRET_KEY` as the key for encoding and decoding. + +#### Handling Secrets with `AuthXConfig` + +By design, JSON Web Tokens are not encrypted; you can try your own JWT on [https://jwt.io/](https://jwt.io/). However, your server will need secrets to sign tokens. + +```py hl_lines="8" +from fastapi import FastAPI +from authx import AuthX, AuthXConfig + +app = FastAPI(title="My Base App") + +config = AuthXConfig() +config.JWT_ALGORITHM = "HS256" +config.JWT_SECRET_KEY = "SECRET_KEY" + +security = AuthX(config=config) +``` + +!!! warning "Secrets Location" + As a best practice, do not use explicit secrets within your code. It is recommended to use environment variables to avoid any credential leakage. + ```py + import os + from authx import AuthXConfig + + config = AuthXConfig() + config.JWT_SECRET_KEY = os.getenv("SECRET_KEY") + ``` + +!!! info "Note on Algorithm" + For demonstration ease, we use a **symmetric** algorithm. Note that an **asymmetric** algorithm offers additional layers of protection. + `"RS256"` is the recommended algorithm when signing JWTs. diff --git a/mkdocs.yml b/mkdocs.yml index 52e9e838..352e6f74 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -65,6 +65,8 @@ markdown_extensions: nav: - About: index.md - installation.md + - Get Started: + - get-started/basic-usage.md - Extra: - extra/OAuth2.md - extra/Metrics.md