165 lines
4.9 KiB
Markdown
165 lines
4.9 KiB
Markdown
# User Authentication Service
|
|
|
|
A FastAPI-based user authentication service with JWT token authentication, user management, and token refresh functionality.
|
|
|
|
## Features
|
|
|
|
- User registration and login
|
|
- JWT token-based authentication
|
|
- Token refresh mechanism
|
|
- User profile management
|
|
- Admin user management
|
|
- SQLite database with Alembic migrations
|
|
|
|
## Technology Stack
|
|
|
|
- **Framework**: FastAPI
|
|
- **Database**: SQLite with SQLAlchemy ORM
|
|
- **Migrations**: Alembic
|
|
- **Authentication**: JWT (JSON Web Tokens)
|
|
- **Password Hashing**: Bcrypt
|
|
- **Dependency Management**: pip
|
|
|
|
## Getting Started
|
|
|
|
### Prerequisites
|
|
|
|
- Python 3.8+
|
|
- pip (Python package manager)
|
|
|
|
### Installation
|
|
|
|
1. Clone the repository:
|
|
```bash
|
|
git clone <repository-url>
|
|
cd userauthenticationservice-altocj
|
|
```
|
|
|
|
2. Install dependencies:
|
|
```bash
|
|
pip install -r requirements.txt
|
|
```
|
|
|
|
3. Run database migrations:
|
|
```bash
|
|
alembic upgrade head
|
|
```
|
|
|
|
4. Start the development server:
|
|
```bash
|
|
uvicorn main:app --reload
|
|
```
|
|
|
|
The API will be available at http://localhost:8000.
|
|
API documentation is available at http://localhost:8000/docs or http://localhost:8000/redoc.
|
|
|
|
## Project Structure
|
|
|
|
```
|
|
app/
|
|
├── api/
|
|
│ └── v1/
|
|
│ ├── endpoints/
|
|
│ │ ├── auth.py # Authentication routes
|
|
│ │ └── users.py # User management routes
|
|
│ └── router.py # API router configuration
|
|
├── core/
|
|
│ ├── config.py # Application configuration
|
|
│ ├── database.py # Database connection setup
|
|
│ ├── dependencies.py # Dependency injection
|
|
│ └── security.py # Authentication utilities
|
|
├── models/
|
|
│ ├── token.py # Token database model
|
|
│ └── user.py # User database model
|
|
├── schemas/
|
|
│ ├── message.py # Response message schemas
|
|
│ ├── token.py # Token validation schemas
|
|
│ └── user.py # User validation schemas
|
|
├── services/
|
|
│ ├── token.py # Token service functions
|
|
│ └── user.py # User service functions
|
|
└── utils/ # Utility functions
|
|
migrations/ # Alembic migration files
|
|
main.py # Application entry point
|
|
requirements.txt # Project dependencies
|
|
```
|
|
|
|
## Authentication Flow
|
|
|
|
### Registration
|
|
|
|
1. Client sends a POST request to `/api/v1/auth/register` with email, username, and password
|
|
2. Server validates the request data
|
|
3. If the user doesn't already exist, it creates a new user with a hashed password
|
|
4. Server returns an access token and a refresh token
|
|
|
|
### Login
|
|
|
|
1. Client sends a POST request to `/api/v1/auth/login` with username/email and password
|
|
2. Server authenticates the user
|
|
3. If successful, server returns an access token and a refresh token
|
|
|
|
### Authentication
|
|
|
|
1. Client includes the access token in the Authorization header for protected endpoints:
|
|
```
|
|
Authorization: Bearer {access_token}
|
|
```
|
|
|
|
2. Server validates the token and identifies the user
|
|
|
|
### Token Refresh
|
|
|
|
1. When the access token expires, client sends a POST request to `/api/v1/auth/refresh` with the refresh token
|
|
2. Server validates the refresh token and issues a new access token and refresh token
|
|
3. The old refresh token is revoked
|
|
|
|
### Logout
|
|
|
|
1. Client sends a POST request to `/api/v1/auth/logout` with the refresh token
|
|
2. Server revokes the refresh token, invalidating the session
|
|
|
|
### Logout All Sessions
|
|
|
|
1. Client sends a POST request to `/api/v1/auth/logout-all` with a valid access token
|
|
2. Server revokes all refresh tokens for the user, invalidating all sessions
|
|
|
|
## API Endpoints
|
|
|
|
### Authentication
|
|
|
|
- `POST /api/v1/auth/register` - Register a new user
|
|
- `POST /api/v1/auth/login` - Login with username/email and password
|
|
- `POST /api/v1/auth/refresh` - Refresh access token
|
|
- `POST /api/v1/auth/logout` - Logout (revoke refresh token)
|
|
- `POST /api/v1/auth/logout-all` - Logout from all devices
|
|
|
|
### User Management
|
|
|
|
- `GET /api/v1/users/me` - Get current user profile
|
|
- `PUT /api/v1/users/me` - Update current user profile
|
|
- `GET /api/v1/users` - Get all users (admin only)
|
|
- `POST /api/v1/users` - Create a new user (admin only)
|
|
- `GET /api/v1/users/{user_id}` - Get user by ID (admin or self)
|
|
- `PUT /api/v1/users/{user_id}` - Update user by ID (admin only)
|
|
|
|
### Health Check
|
|
|
|
- `GET /health` - Check API health status
|
|
|
|
## Environment Variables
|
|
|
|
The project uses `.env` file for configuration. Here's an example:
|
|
|
|
```
|
|
SECRET_KEY=your-secret-key
|
|
ACCESS_TOKEN_EXPIRE_MINUTES=1440 # 24 hours
|
|
BACKEND_CORS_ORIGINS=["http://localhost:3000"]
|
|
```
|
|
|
|
## Security Considerations
|
|
|
|
- Passwords are hashed using bcrypt
|
|
- JWT tokens are signed with a secret key
|
|
- Refresh tokens are stored in the database and can be revoked
|
|
- Role-based access control for admin functions |