# JWT Authentication
Create a complete JWT-based authentication system with login/logout endpoints and route protection using special `{auth}` files.
## Overview
When the server detects a file named `{auth}.json`, it automatically:
1. **Loads user credentials** from the JSON array in the file
2. **Creates authentication endpoints** for login and logout
3. **Creates REST endpoints** for user
4. **Generates JWT tokens** with secure cookies
5. **Provides middleware** for protecting routes with authentication
## Authentication File Detection
Only **one authentication route is allowed** per server instance. The `{auth}` file creates authentication endpoints based on its folder location:
| `./mocks/account/{auth}.json` | `POST /account/login`<br>`POST /account/logout`<br>`REST /account/users` | Authentication for account management |
| `./mocks/api/auth/{auth}.json` | `POST /api/auth/login`<br>`POST /api/auth/logout`<br>`REST /api/auth/users` | API authentication endpoints |
| `./mocks/{auth}.json` | `POST /login`<br>`POST /logout`<br>`REST /users` | Root-level authentication |
## Credentials File Format
The `{auth}.json` file should contain an array of user objects with `username` and `password` as required fields:
```json
[
{
"id": "550e8400-e29b-41d4-a716-446655440001",
"username": "admin",
"password": "admin123",
"email": "admin@example.com",
"role": "administrator"
},
{
"id": "550e8400-e29b-41d4-a716-446655440002",
"username": "user",
"password": "user123",
"email": "user@example.com",
"role": "user"
},
{
"id": "550e8400-e29b-41d4-a716-446655440003",
"username": "john.doe",
"password": "password123",
"email": "john.doe@example.com",
"role": "user"
}
]
```
## Authentication Endpoints
### Login Endpoint - `POST /{folder}/login`
**Request:**
```bash
curl -X POST http://localhost:4520/account/login \
-H "Content-Type: application/json" \
-d '{"username": "admin", "password": "admin123"}'
```
**Response:**
```json
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
"user": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"username": "admin",
"email": "admin@example.com",
"role": "administrator"
}
}
```
**Features:**
- **Request**: JSON with `username` and `password`
- **Response**: JWT token and user info (password excluded)
- **Cookie**: Sets HTTP-only `auth_token` cookie for 24 hours
### Logout Endpoint - `POST /{folder}/logout`
**Request:**
```bash
curl -X POST http://localhost:4520/account/logout \
-H "Authorization: Bearer <jwt_token>"
```
**Response:**
```json
{
"message": "Successfully logged out"
}
```
**Features:**
- **Request**: JWT token via Authorization header or cookie
- **Response**: Success message
- **Action**: Revokes the token from valid tokens list
### Users REST Endpoint
The authentication system also creates a full REST API for user management:
- **GET** `/{folder}/users` - List all users (protected)
- **POST** `/{folder}/users` - Create new user (protected)
- **GET** `/{folder}/users/{id}` - Get user by id (protected)
- **PUT** `/{folder}/users/{id}` - Update user (protected)
- **PATCH** `/{folder}/users/{id}` - Partially update user (protected)
- **DELETE** `/{folder}/users/{id}` - Delete user (protected)
**Configuration:**
- **IdType**: None
- **IdKey**: `id`
- **Protected**: All REST endpoints require authentication token
## Route Protection
To protect routes with authentication, prefix folder names or filenames with `$`:
### Protected Files
```
mocks/
├── api/
│ ├── cities/
│ │ └── $get.json # Protected: GET /api/cities
│ └── companies/
│ └── get.json # Public: GET /api/companies
```
### Protected Folders (protects all children)
```
mocks/
├── $admin/ # All routes under /admin are protected
│ ├── repositories/
│ │ └── rest.json # Protected: Full CRUD at /admin/repositories/*
│ └── settings/
│ └── get.json # Protected: GET /admin/settings
└── open/
└── info.json # Public: GET /open/info
```
**Note:** It is not possible to protect a `public` folder.
## Authentication Methods
### Option A: Authorization Header
```bash
curl -H "Authorization: Bearer <jwt_token>" \
http://localhost:4520/admin/repositories
```
### Option B: Cookie (automatic)
```bash
curl -b "auth_token=<jwt_token>" \
http://localhost:4520/admin/repositories
```
**Note:** When using the web interface, cookies are handled automatically.
## Complete Authentication Flow
### 1. Login
**Request:**
```bash
curl -X POST http://localhost:4520/api/auth/login \
-H "Content-Type: application/json" \
-d '{
"username": "admin",
"password": "admin123"
}'
```
**Response:**
```json
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOiJhZG1pbiIsImV4cCI6MTY5NzIyNzIwMH0.abc123",
"user": {
"id": "550e8400-e29b-41d4-a716-446655440001",
"username": "admin",
"email": "admin@example.com",
"role": "administrator"
}
}
```
### 2. Access Protected Route
**Request:**
```bash
curl -H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..." \
http://localhost:4520/admin/settings
```
**Response:**
```json
{
"maintenance_mode": false,
"api_version": "v1.0",
"features": ["uploads", "auth", "rest"]
}
```
### 3. Logout
**Request:**
```bash
curl -X POST http://localhost:4520/api/auth/logout \
-H "Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9..."
```
**Response:**
```json
{
"message": "Successfully logged out"
}
```
## Security Features
### JWT Tokens
- **Expiration**: 24-hour automatic expiration
- **Algorithm**: HS256 signing for security
- **Claims**: Includes username and expiration time
### HTTP-Only Cookies
- **XSS Protection**: Prevents client-side JavaScript access
- **Automatic**: Set on successful login
- **Secure**: Can be configured for HTTPS environments
### Token Revocation
- **Active Tracking**: Server maintains list of valid tokens
- **Logout**: Immediately invalidates tokens
- **Security**: Prevents token reuse after logout
### Password Protection
- **Response Filtering**: Login responses exclude password fields
- **Storage**: Passwords stored in plain text in JSON (for development/testing)
- **Validation**: Username and password required for login
## Error Responses
### Invalid Credentials
```json
{
"error": "Invalid credentials"
}
```
**Status:** `401 Unauthorized`
### Missing Token
```json
{
"error": "Authentication required"
}
```
**Status:** `401 Unauthorized`
### Invalid Token
```json
{
"error": "Invalid or expired token"
}
```
**Status:** `401 Unauthorized`
### Token Expired
```json
{
"error": "Token has expired"
}
```
**Status:** `401 Unauthorized`
## User Management Examples
### List Users (Protected)
```bash
curl -H "Authorization: Bearer <token>" \
http://localhost:4520/api/auth/users
```
### Create User (Protected)
```bash
curl -X POST http://localhost:4520/api/auth/users \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"username": "newuser",
"password": "newpass123",
"email": "newuser@example.com",
"role": "user"
}'
```
### Update User Password (Protected)
```bash
curl -X PATCH http://localhost:4520/api/auth/users/john.doe \
-H "Authorization: Bearer <token>" \
-H "Content-Type: application/json" \
-d '{
"password": "newpassword456"
}'
```
## Integration with Other Features
### REST APIs
Protect your REST APIs by using the `$` prefix:
```
mocks/
├── api/
│ ├── auth/
│ │ └── {auth}.json # Authentication system
│ ├── $products/
│ │ └── rest.json # Protected REST API
│ └── public-data/
│ └── rest.json # Public REST API
```
### File Uploads
Protect upload endpoints:
```
mocks/
├── auth/
│ └── {auth}.json # Authentication
├── ${upload}/ # Protected uploads
└── {upload}-public/ # Public uploads
```
### Static Files
Protect static content:
```
mocks/
├── auth/
│ └── {auth}.json # Authentication
├── $admin/
│ └── dashboard.html # Protected admin dashboard
└── public-assets/
└── logo.png # Public assets
```
## Best Practices
1. **Single Auth System**: Use only one `{auth}` file per server instance
2. **Consistent Location**: Place auth files in logical locations (e.g., `/auth`, `/account`)
3. **Strong Passwords**: Use complex passwords even for development
4. **Token Management**: Always logout when done to revoke tokens
5. **Route Organization**: Group protected routes under `$` prefixed folders
6. **Error Handling**: Implement proper error handling for auth failures
## Next Steps
- Learn about [Route Protection](01-basic-routing.md#route-priority) strategies
- Explore [File Uploads](04-file-uploads.md) with authentication
- See [REST APIs](02-rest-apis.md) for protected CRUD operations
- Try the [Web Interface](07-web-interface.md) for interactive authentication testing