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
--- a/.gitignore
+++ b/.gitignore
@@ -0,0 +1 @@
+.envrc
--- a/21
+++ b/21
@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 OIDC Token Validator
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
--- a/README.md
+++ b/README.md
@@ -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.