initial commit
This commit is contained in:
gulimabr
243
README.md
Normal file
243
README.md
Normal file
@@ -0,0 +1,243 @@
|
||||
# FastAPI Keycloak Integration with React Frontend
|
||||
|
||||
## Table of Contents
|
||||
|
||||
- [Introduction](#introduction)
|
||||
- [Features](#features)
|
||||
- [Project Structure](#project-structure)
|
||||
- [Prerequisites](#prerequisites)
|
||||
- [Installation](#installation)
|
||||
- [Configuration](#configuration)
|
||||
- [Usage](#usage)
|
||||
- [Authentication Flow](#authentication-flow)
|
||||
- [Development](#development)
|
||||
- [Contributing](#contributing)
|
||||
- [License](#license)
|
||||
|
||||
## Introduction
|
||||
|
||||
This project provides a full-stack authentication solution using FastAPI as the backend, React (with TypeScript and Tailwind CSS) as the frontend, and Keycloak as the identity provider. Authentication is handled securely using HTTP-only cookies to protect tokens from XSS attacks.
|
||||
|
||||
## Features
|
||||
|
||||
- **FastAPI Backend**: A modern, fast web framework for building APIs with Python 3.12+
|
||||
- **React Frontend**: TypeScript-based React application with Tailwind CSS for styling
|
||||
- **Keycloak Integration**: Enterprise-grade identity management with OAuth2/OpenID Connect
|
||||
- **Secure Cookie-Based Auth**: HTTP-only cookies protect access tokens from XSS attacks
|
||||
- **Dockerized Setup**: Full Docker Compose setup including Keycloak, backend, and frontend
|
||||
- **Poetry for Python Dependencies**: Simplified Python dependency management
|
||||
|
||||
## Project Structure
|
||||
|
||||
```
|
||||
.
|
||||
├── .env.example # Environment variables template
|
||||
├── docker-compose.yaml # Production Docker Compose
|
||||
├── docker-compose.dev.yaml # Development Docker Compose
|
||||
├── README.md
|
||||
├── backend/
|
||||
│ ├── Dockerfile
|
||||
│ ├── pyproject.toml
|
||||
│ ├── poetry.lock
|
||||
│ └── src/
|
||||
│ ├── __init__.py
|
||||
│ ├── config.py # Keycloak & cookie settings
|
||||
│ ├── controller.py # Request handlers
|
||||
│ ├── main.py # FastAPI app with CORS
|
||||
│ ├── models.py # Pydantic models
|
||||
│ └── service.py # Keycloak auth service
|
||||
└── frontend/
|
||||
├── Dockerfile
|
||||
├── nginx.conf # Production nginx config
|
||||
├── package.json
|
||||
├── tsconfig.json
|
||||
├── tailwind.config.js
|
||||
├── vite.config.ts
|
||||
└── src/
|
||||
├── App.tsx
|
||||
├── main.tsx
|
||||
├── index.css
|
||||
├── components/ # Reusable UI components
|
||||
├── context/ # React Context (AuthContext)
|
||||
├── hooks/ # Custom hooks (useAuth)
|
||||
├── pages/ # Page components
|
||||
├── services/ # API service layer
|
||||
└── types/ # TypeScript types
|
||||
```
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- [Docker](https://www.docker.com/get-started) and [Docker Compose](https://docs.docker.com/compose/install/)
|
||||
- [Node.js 20+](https://nodejs.org/) (for local frontend development)
|
||||
- [Python 3.12+](https://www.python.org/downloads/) (for local backend development)
|
||||
- [Git](https://git-scm.com/)
|
||||
|
||||
## Installation
|
||||
|
||||
1. **Clone the Repository**
|
||||
|
||||
```bash
|
||||
git clone https://github.com/your-repo/fastapi-keycloak.git
|
||||
cd fastapi-keycloak
|
||||
```
|
||||
|
||||
2. **Copy Environment Variables File**
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
```
|
||||
|
||||
3. **Configure Environment Variables**
|
||||
|
||||
Open the `.env` file and update the following variables:
|
||||
|
||||
```env
|
||||
# Keycloak Configuration
|
||||
KEYCLOAK_SERVER_URL=http://localhost:8081/
|
||||
KEYCLOAK_REALM=your-realm
|
||||
KEYCLOAK_CLIENT_ID=your-client-id
|
||||
KEYCLOAK_CLIENT_SECRET=your-client-secret
|
||||
|
||||
# Frontend URL (for CORS and redirects)
|
||||
FRONTEND_URL=http://localhost:3000
|
||||
|
||||
# Cookie Configuration
|
||||
COOKIE_SECURE=false # Set to true in production with HTTPS
|
||||
COOKIE_SAMESITE=lax
|
||||
COOKIE_MAX_AGE=3600
|
||||
```
|
||||
|
||||
## Configuration
|
||||
|
||||
### Setting Up Keycloak
|
||||
|
||||
1. **Start the Services**
|
||||
|
||||
```bash
|
||||
docker-compose up keycloak -d
|
||||
```
|
||||
|
||||
2. **Access the Keycloak Admin Console**
|
||||
|
||||
Open `http://localhost:8081/` and login with:
|
||||
- Username: `admin`
|
||||
- Password: `admin`
|
||||
|
||||
3. **Create a New Realm**
|
||||
|
||||
- Click "Create Realm"
|
||||
- Name it (e.g., `my-app`)
|
||||
- Click "Create"
|
||||
|
||||
4. **Create a New Client**
|
||||
|
||||
- Go to Clients → Create client
|
||||
- Client ID: e.g., `my-app-client`
|
||||
- Client Protocol: `openid-connect`
|
||||
- Click Next
|
||||
- Enable "Client authentication" (confidential)
|
||||
- Enable "Standard flow" and "Direct access grants"
|
||||
- Click Next
|
||||
- Valid redirect URIs: `http://localhost:8080/*`
|
||||
- Web origins: `http://localhost:3000`
|
||||
- Click Save
|
||||
|
||||
5. **Get Client Secret**
|
||||
|
||||
- Go to Credentials tab
|
||||
- Copy the "Client secret"
|
||||
- Update your `.env` file
|
||||
|
||||
6. **Create a Test User**
|
||||
|
||||
- Go to Users → Add user
|
||||
- Username: `testuser`
|
||||
- Email: `test@example.com`
|
||||
- Click Create
|
||||
- Go to Credentials tab → Set password
|
||||
- Disable "Temporary"
|
||||
|
||||
## Usage
|
||||
|
||||
### Running with Docker (Production)
|
||||
|
||||
```bash
|
||||
# Start all services
|
||||
docker-compose up --build
|
||||
|
||||
# Services will be available at:
|
||||
# - Frontend: http://localhost:3000
|
||||
# - Backend API: http://localhost:8080
|
||||
# - Keycloak: http://localhost:8081
|
||||
```
|
||||
|
||||
### Running with Docker (Development)
|
||||
|
||||
For development with hot-reload on the backend:
|
||||
|
||||
```bash
|
||||
# Start Keycloak and Backend only
|
||||
docker-compose -f docker-compose.dev.yaml up --build
|
||||
|
||||
# In another terminal, start the frontend dev server
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
## Authentication Flow
|
||||
|
||||
1. **User clicks "Login"** → Frontend redirects to `/api/login`
|
||||
2. **Backend redirects to Keycloak** → User authenticates with Keycloak
|
||||
3. **Keycloak redirects back** → Backend receives authorization code at `/api/callback`
|
||||
4. **Backend exchanges code for token** → Sets HTTP-only cookie with access token
|
||||
5. **Backend redirects to frontend** → User lands on `/dashboard`
|
||||
6. **Frontend calls `/api/auth/me`** → Backend validates cookie and returns user info
|
||||
|
||||
### API Endpoints
|
||||
|
||||
| Endpoint | Method | Auth | Description |
|
||||
|----------|--------|------|-------------|
|
||||
| `/api` | GET | No | Welcome message and docs link |
|
||||
| `/api/login` | GET | No | Initiates OAuth2 login flow |
|
||||
| `/api/callback` | GET | No | OAuth2 callback (sets cookie) |
|
||||
| `/api/auth/me` | GET | Cookie | Get current user info |
|
||||
| `/api/auth/logout` | POST | Cookie | Clear auth cookie |
|
||||
| `/api/protected` | GET | Bearer | Protected endpoint (token in header) |
|
||||
| `/docs` | GET | No | Swagger API documentation |
|
||||
|
||||
## Development
|
||||
|
||||
### Backend Development
|
||||
|
||||
```bash
|
||||
cd backend
|
||||
poetry install
|
||||
poetry run uvicorn src.main:app --reload --port 8080
|
||||
```
|
||||
|
||||
### Frontend Development
|
||||
|
||||
```bash
|
||||
cd frontend
|
||||
npm install
|
||||
npm run dev
|
||||
```
|
||||
|
||||
The frontend dev server runs on `http://localhost:3000` and proxies `/api` requests to the backend.
|
||||
|
||||
### Environment Variables
|
||||
|
||||
See `.env.example` for all available configuration options:
|
||||
|
||||
- **Keycloak settings**: Server URL, realm, client ID/secret
|
||||
- **Frontend URL**: For CORS and OAuth redirects
|
||||
- **Cookie settings**: Security options for the auth cookie
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome! Please feel free to submit a pull request or open an issue.
|
||||
|
||||
## License
|
||||
|
||||
This project is licensed under the MIT License.
|
||||
Reference in New Issue
Block a user