Team Aryana & Ashkan

We will implement authentication using the FastAPI framework and JSON Web Tokens (JWT). The design uses symmetric signing (a shared secret) for tokens so the same secret/key is used to both sign and verify JWTs.

Goals

• Use FastAPI to expose authentication endpoints (login, token refresh if needed) and to protect application routes.
• Use symmetric JWT (e.g., HS256) for signing access tokens.
• Keep secrets (JWT_SECRET_KEY, algorithm, token expiry) in environment variables or a secure vault.

Key concepts and implementation notes

• Token creation: on successful login, issue a JWT signed with a symmetric key (HS256). Include standard claims like "sub" (user id) and "exp" (expiration).
• Token verification: FastAPI dependencies (e.g., OAuth2PasswordBearer) will extract the bearer token from requests; use the same secret to verify and decode the token.
• Expiry and refresh: issue short-lived access tokens (e.g., minutes to hours). Optionally implement refresh tokens with longer lifetime and stricter storage/usage rules.
• Passwords: we will store hashed passwords using a secure hashing algorithm (bcrypt / passlib).
• Error handling: return appropriate HTTP 401/403 responses for invalid/expired tokens.
• Secure transport: always run behind HTTPS to protect tokens in transit.

As for the database we will only save the user information such as username, hashed password, email, and any other important details, but we will not save their specific roles or jobs in our service.

JWT Structure The JWTs will have the following structure:

Header: {
  "alg": "HS256",
  "typ": "JWT"
}

Payload = {
        "iss": auth_service,
        "sub": user_guid,
        "iat": now,
        "exp": expire_date,
        "email": email_address,
        "type": "access/refresh",
    }

Setup

1. Clone the repository
2. Copy .env.example to .env and configure your settings
3. Run docker compose up -d
4. Run migrations: docker compose exec web alembic upgrade head
5. Access API at http://localhost:8000