demo-oidc/README.md

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.

You can try out a live demo at https://demo-oidc.cl1.parano.ch/

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

├── 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

Creating an OAuth App with Infomaniak

To use this OIDC validator, you need to create an OAuth application with Infomaniak to obtain a Client ID and Client Secret:

1. Go to Infomaniak Developer Portal
2. Sign in with your Infomaniak account or create one if you don't have one
3. Navigate to "Applications" and click "Create an application"
4. Fill in the application details:
   • Name: Choose a name for your application (e.g., "OIDC Validator Demo")
   • Description: Optional description
   • Website: Your website URL (can be localhost for development)
5. In the "Redirect URIs" section, add the callback URL:
   • For local development: http://localhost:8000/callback
   • For production: https://your-domain.com/callback
6. Select the required scopes:
   • At minimum, select openid and profile scopes
   • You may also want to select email scope if you need email information
7. Save the application
8. Once created, you'll see your "Client ID" and "Client Secret"
9. Keep these credentials secure as you'll need them to run the application

Note: For development purposes, you can use http://localhost:8000 as the redirect URI. For production deployments, make sure to use HTTPS URLs.

Installation

Local Development

1. Clone the repository:

   git clone <repository-url>
   cd oidc-validator
   

2. Set up virtual environment and install dependencies:

   ./setup_test_env.sh
   

3. Activate the virtual environment:

   source venv/bin/activate
   

4. Set environment variables:

   export CLIENT_ID=your_oidc_client_id
   export CLIENT_SECRET=your_oidc_client_secret  # Required for token refresh
   

5. Run the application:

   uvicorn main:app --host 0.0.0.0 --port 8000 --reload
   

Docker Deployment

1. Build the Docker image:

   docker build -t oidc-validator .
   

2. Run the container:

   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

This project includes a comprehensive test suite. To run the tests:

1. Set up the virtual environment:

   ./setup_test_env.sh
   

2. Run the tests:

   ./run_tests.sh
   

This will run all tests with coverage reporting and generate an HTML coverage report in the htmlcov/ directory.

The test suite covers:

• API endpoint testing
• Token validation logic
• Error handling
• Utility functions
• Edge cases

For more detailed information about testing, see tests/README.md.

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 - Web framework
• Uvicorn - ASGI server
• PyJWT - JWT token handling
• Requests - HTTP client
• Cryptography - Cryptographic operations
• Python-JOSE - JOSE implementation

License

This project is licensed under the MIT License - see the LICENSE file for details.