docs: add comprehensive documentation and MIT license

- Add detailed README.md with project overview, setup instructions, and usage guide - Add MIT LICENSE file for open-source distribution - Include .gitignore file for Python and Docker artifacts
2025-08-08 09:29:08 +02:00
parent a4908ac492
commit 7a87af42ab
3 changed files with 171 additions and 0 deletions
@@ -0,0 +1,149 @@
+# OIDC Token Validator
+
+A Python/FastAPI application that implements an OpenID Connect (OIDC) token validator for Infomaniak's authentication system. This application demonstrates how to authenticate users with OIDC, validate their tokens, and provide access to protected resources for authorized users.
+
+## Features
+
+- OpenID Connect Implicit Flow authentication with Infomaniak
+- JWT token validation with signature verification using JWKS
+- Automatic token refresh mechanism
+- Protected resource access for authorized users
+- CORS middleware configuration
+- Docker containerization with multi-stage build
+- Health check endpoint for Kubernetes readiness
+- Responsive web interface with Bootstrap
+
+## Project Structure
+
+```text
+├── main.py              # FastAPI backend application
+├── requirements.txt     # Python dependencies
+├── Dockerfile           # Docker configuration
+├── templates/
+│   ├── index.html       # Frontend HTML/JavaScript client
+│   └── favicon.ico      # Application favicon
+└── README.md            # This file
+```
+
+## Prerequisites
+
+- Python 3.7+
+- Docker (for containerized deployment)
+- An Infomaniak developer account with OIDC client credentials
+
+## Installation
+
+### Local Development
+
+1. Clone the repository:
+
+   ```bash
+   git clone <repository-url>
+   cd oidc-validator
+   ```
+
+2. Install dependencies:
+
+   ```bash
+   pip install -r requirements.txt
+   ```
+
+3. Set environment variables:
+
+   ```bash
+   export CLIENT_ID=your_oidc_client_id
+   export CLIENT_SECRET=your_oidc_client_secret  # Required for token refresh
+   ```
+
+4. Run the application:
+
+   ```bash
+   uvicorn main:app --host 0.0.0.0 --port 8000 --reload
+   ```
+
+### Docker Deployment
+
+1. Build the Docker image:
+
+   ```bash
+   docker build -t oidc-validator .
+   ```
+
+2. Run the container:
+
+   ```bash
+   docker run -p 8000:8000 \
+     -e CLIENT_ID=your_oidc_client_id \
+     -e CLIENT_SECRET=your_oidc_client_secret \
+     oidc-validator
+   ```
+
+## Configuration
+
+The application can be configured using the following environment variables:
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `OIDC_ISSUER` | OIDC issuer URL | `https://login.infomaniak.com` |
+| `CLIENT_ID` | OIDC client ID | Required |
+| `CLIENT_SECRET` | OIDC client secret | Empty string |
+
+## API Endpoints
+
+- `GET /` - Serve the frontend application
+- `GET /health` - Health check endpoint
+- `GET /config` - Serve client configuration to frontend
+- `POST /validate-token` - Validate ID token and return secret phrase for authorized users
+- `POST /refresh-token` - Refresh an access token using a refresh token
+- `GET /favicon.ico` - Serve the favicon
+
+## Usage
+
+1. Access the application at `http://localhost:8000`
+2. Click "Login with Infomaniak" to authenticate
+3. After successful authentication, authorized users will see a secret phrase
+4. The application includes a demo Bitcoin price checker feature
+
+## Security Features
+
+- Uses OAuth 2.0 Implicit Flow with security measures
+- Validates JWT tokens with signature verification using JWKS
+- Implements automatic token refresh mechanism
+- Runs as non-root user in Docker container
+- CORS middleware configuration
+
+## Development
+
+### Running Tests
+
+Currently, there are no automated tests. You can manually test the endpoints using curl:
+
+```bash
+# Health check
+curl http://localhost:8000/health
+
+# Token validation (requires valid JWT token)
+curl -X POST http://localhost:8000/validate-token \
+  -H "Content-Type: application/json" \
+  -d '{"id_token": "your.jwt.token.here"}'
+```
+
+### Deployment Notes
+
+- The application includes Kubernetes readiness through its health check endpoint
+- Docker image uses multi-stage build for smaller footprint
+- Runs as non-root user for security
+- Exposes port 8000
+
+## Dependencies
+
+- [FastAPI](https://fastapi.tiangolo.com/) - Web framework
+- [Uvicorn](https://www.uvicorn.org/) - ASGI server
+- [PyJWT](https://pyjwt.readthedocs.io/) - JWT token handling
+- [Requests](https://docs.python-requests.org/) - HTTP client
+- [Cryptography](https://cryptography.io/) - Cryptographic operations
+- [Python-JOSE](https://python-jose.readthedocs.io/) - JOSE implementation
+
+## License
+
+This project is licensed under the MIT License - see the LICENSE file for details.