omniauth_openid_federation 1.2.0

data/SECURITY.md

@@ -0,0 +1,28 @@
+# SECURITY
+
+## Reporting a Vulnerability
+
+**Do NOT** open a public GitHub issue for security vulnerabilities.
+
+Email security details to: **security@kiskolabs.com**
+
+Include: description, steps to reproduce, potential impact, and suggested fix (if available).
+
+### Response Timeline
+
+- We will acknowledge receipt of your report
+- We will provide an initial assessment
+- We will keep you informed of our progress and resolution timeline
+
+### Disclosure Policy
+
+- We will work with you to understand and resolve the issue
+- We will credit you for the discovery (unless you prefer to remain anonymous)
+- We will publish a security advisory after the vulnerability is patched
+- We will coordinate public disclosure with you
+
+## Automation Security
+
+* **Context Isolation:** It is strictly forbidden to include production credentials, API keys, or Personally Identifiable Information (PII) in prompts sent to third-party LLMs or automation services.
+
+* **Supply Chain:** All automated dependencies must be verified.

data/examples/README_INTEGRATION_TESTING.md

@@ -0,0 +1,399 @@
+# OpenID Federation Integration Testing
+
+This directory contains comprehensive mock servers and integration tests for the complete OpenID Federation flow.
+
+## Architecture
+
+The integration test setup consists of:
+
+1. **Mock OP Server** (`mock_op_server.rb`) - Simulates an OpenID Provider
+2. **Mock RP Server** (`mock_rp_server.rb`) - Simulates a Relying Party (Client)
+3. **Integration Test Flow** (`integration_test_flow.rb`) - Automated tests for the complete flow
+
+## Complete OpenID Federation Flow
+
+### 1. Provider Exposes Entity Statement with JWKS
+
+The OP server exposes its entity configuration at:
+```
+GET /.well-known/openid-federation
+```
+
+Returns a signed JWT containing:
+- Provider metadata (authorization_endpoint, token_endpoint, etc.)
+- JWKS (public keys for signing/encryption)
+- Authority hints (if subordinate to a Trust Anchor)
+
+### 2. Client Exposes Entity Statement with JWKS
+
+The RP server exposes its entity configuration at:
+```
+GET /.well-known/openid-federation
+```
+
+Returns a signed JWT containing:
+- RP metadata (redirect_uris, client_name, etc.)
+- JWKS (public keys for signing request objects)
+- Authority hints (if subordinate to a Trust Anchor)
+
+### 3. Client Fetches Provider Statement with Keys
+
+When the RP initiates login:
+1. RP fetches OP's entity statement from `/.well-known/openid-federation`
+2. RP validates the entity statement signature
+3. RP extracts OP's JWKS for future token validation
+4. RP extracts OP's metadata (endpoints, capabilities)
+
+### 4. Client Sends Login Request
+
+RP generates a signed request object (JWT) containing:
+- `client_id`: RP's Entity ID
+- `redirect_uri`: Callback URL
+- `scope`: Requested scopes
+- `state`: CSRF protection
+- `nonce`: Replay protection
+- `aud`: OP's Entity ID
+
+The request object is:
+- **Always signed** with RP's private key (RFC 9101 requirement)
+- **Optionally encrypted** if OP requires encryption
+
+RP redirects to OP's authorization endpoint:
+```
+GET /auth?request=<signed_jwt>
+```
+
+### 5. Provider Fetches Client Statement and Keys
+
+When OP receives the authorization request:
+1. OP extracts `client_id` from the request object
+2. OP fetches RP's entity statement from `/.well-known/openid-federation`
+3. OP validates RP's entity statement signature
+4. OP extracts RP's JWKS from the entity statement
+5. OP validates the request object signature using RP's public key
+6. OP resolves RP's trust chain (if trust anchors configured)
+7. OP applies metadata policies from trust chain
+8. OP validates `redirect_uri` against RP's allowed redirect URIs
+
+### 6. Exchange and Authenticated Login
+
+After user authorization:
+1. OP redirects back to RP with authorization code
+2. RP exchanges code for tokens at OP's token endpoint
+3. OP returns ID token (signed with OP's private key)
+4. RP validates ID token signature using OP's JWKS
+5. RP validates ID token claims (iss, aud, exp, nonce)
+6. User is authenticated
+
+## Error Scenarios Supported
+
+The mock servers support error injection via `?error_mode=<mode>` parameter:
+
+### Invalid Statement
+```
+GET /.well-known/openid-federation?error_mode=invalid_statement
+```
+Returns malformed JWT to test error handling.
+
+### Wrong Keys
+```
+GET /.well-known/jwks.json?error_mode=wrong_keys
+GET /.well-known/openid-federation?error_mode=wrong_keys
+```
+Returns JWKS with keys that don't match the signing key.
+
+### Invalid Request
+```
+GET /auth?error_mode=invalid_request
+```
+Rejects request object validation to test error handling.
+
+### Invalid Signature
+```
+GET /.well-known/signed-jwks.json?error_mode=invalid_signature
+```
+Returns signed JWKS with invalid signature.
+
+### Expired Statement
+```
+GET /.well-known/openid-federation?error_mode=expired_statement
+```
+Returns expired entity statement to test expiration handling.
+
+### Missing Metadata
+```
+GET /.well-known/openid-federation?error_mode=missing_metadata
+```
+Returns entity statement without metadata to test validation.
+
+## Usage
+
+### Quick Start (Automated - Recommended)
+
+The integration test flow can automatically start servers, generate keys, and run all tests:
+
+```bash
+# Single command - fully automated
+ruby examples/integration_test_flow.rb
+```
+
+This will:
+1. Create temporary directories for keys and configs
+2. Generate RSA keys for both OP and RP (using rake task logic)
+3. Configure and start both servers automatically
+4. Wait for servers to be ready
+5. Run all integration tests
+6. Clean up (kill servers, remove tmp dirs) on exit
+
+### Manual Start (For Debugging)
+
+If you want to start servers manually for debugging:
+
+**Terminal 1 - OP Server:**
+```bash
+ruby examples/mock_op_server.rb
+# Server runs on http://localhost:9292
+```
+
+**Terminal 2 - RP Server:**
+```bash
+ruby examples/mock_rp_server.rb
+# Server runs on http://localhost:9293
+```
+
+**Terminal 3 - Integration Tests:**
+```bash
+# Disable auto-start to use manually started servers
+AUTO_START_SERVERS=false ruby examples/integration_test_flow.rb
+```
+
+### Environment Variables
+
+The integration test flow supports the following environment variables:
+
+```bash
+# Server URLs
+OP_URL=http://localhost:9292          # OP server URL
+RP_URL=http://localhost:9293          # RP server URL
+
+# Server Ports
+OP_PORT=9292                          # OP server port
+RP_PORT=9293                          # RP server port
+
+# Entity IDs
+OP_ENTITY_ID=https://op.example.com   # OP entity identifier
+RP_ENTITY_ID=https://rp.example.com   # RP entity identifier
+
+# Temporary Directory
+TMP_DIR=tmp/integration_test          # Directory for keys/configs (default: tmp/integration_test)
+
+# Auto-start servers (true/false)
+AUTO_START_SERVERS=true               # Auto-start servers (default: true)
+
+# Cleanup on exit (true/false)
+CLEANUP_ON_EXIT=true                  # Clean up tmp dirs on exit (default: true)
+
+# Key Type
+KEY_TYPE=separate                     # 'single' or 'separate' (default: separate)
+```
+
+**Example with custom configuration:**
+```bash
+KEY_TYPE=separate \
+TMP_DIR=/tmp/my_test \
+ruby examples/integration_test_flow.rb
+```
+
+**Note**: By default, the integration test uses localhost URLs for complete isolation:
+- No DNS resolution required
+- No external network dependencies
+- All communication happens on localhost
+- Entity IDs default to `http://localhost:9292` (OP) and `http://localhost:9293` (RP)
+
+This ensures the tests work in any environment without network configuration.
+
+### Manual Testing
+
+**1. Test Provider Entity Statement:**
+```bash
+curl http://localhost:9292/.well-known/openid-federation
+```
+
+**2. Test Client Entity Statement:**
+```bash
+curl http://localhost:9293/.well-known/openid-federation
+```
+
+**3. Test Login Flow:**
+```bash
+# Initiate login (will redirect to OP)
+curl -L "http://localhost:9293/login?provider=https://op.example.com"
+```
+
+**4. Test Error Scenarios:**
+```bash
+# Invalid statement
+curl "http://localhost:9292/.well-known/openid-federation?error_mode=invalid_statement"
+
+# Wrong keys
+curl "http://localhost:9292/.well-known/jwks.json?error_mode=wrong_keys"
+
+# Expired statement
+curl "http://localhost:9292/.well-known/openid-federation?error_mode=expired_statement"
+```
+
+## Configuration
+
+### OP Server Configuration
+
+Create `examples/config/mock_op.yml`:
+
+```yaml
+entity_id: "https://op.example.com"
+server_host: "localhost:9292"
+signing_key: |
+  -----BEGIN RSA PRIVATE KEY-----
+  ...
+  -----END RSA PRIVATE KEY-----
+encryption_key: |  # Optional, defaults to signing_key
+  -----BEGIN RSA PRIVATE KEY-----
+  ...
+  -----END RSA PRIVATE KEY-----
+trust_anchors:
+  - entity_id: "https://ta.example.com"
+    jwks:
+      keys:
+        - kty: "RSA"
+          kid: "ta-key-1"
+          use: "sig"
+          n: "..."
+          e: "AQAB"
+authority_hints:  # Optional, if OP is subordinate
+  - "https://ta.example.com"
+op_metadata:
+  issuer: "https://op.example.com"
+  authorization_endpoint: "https://op.example.com/auth"
+  token_endpoint: "https://op.example.com/token"
+  request_object_encryption_alg_values_supported: ["RSA-OAEP"]
+  request_object_encryption_enc_values_supported: ["A128CBC-HS256"]
+require_request_encryption: false  # Set to true to require encryption
+validate_request_objects: true     # Set to false to skip validation
+```
+
+### RP Server Configuration
+
+Create `examples/config/mock_rp.yml`:
+
+```yaml
+entity_id: "https://rp.example.com"
+server_host: "localhost:9293"
+signing_key: |
+  -----BEGIN RSA PRIVATE KEY-----
+  ...
+  -----END RSA PRIVATE KEY-----
+encryption_key: |  # Optional, for decrypting encrypted ID tokens
+  -----BEGIN RSA PRIVATE KEY-----
+  ...
+  -----END RSA PRIVATE KEY-----
+trust_anchors:
+  - entity_id: "https://ta.example.com"
+    jwks:
+      keys: [...]
+authority_hints:  # Optional, if RP is subordinate
+  - "https://ta.example.com"
+redirect_uris:
+  - "https://rp.example.com/callback"
+```
+
+## Testing Scenarios
+
+### Happy Path
+
+1. Start both servers
+2. Run integration tests: `ruby examples/integration_test_flow.rb`
+3. All tests should pass
+
+### Error Scenarios
+
+1. Test invalid entity statement:
+   ```bash
+   curl "http://localhost:9292/.well-known/openid-federation?error_mode=invalid_statement"
+   ```
+
+2. Test wrong keys:
+   ```bash
+   curl "http://localhost:9292/.well-known/jwks.json?error_mode=wrong_keys"
+   ```
+
+3. Test expired statement:
+   ```bash
+   curl "http://localhost:9292/.well-known/openid-federation?error_mode=expired_statement"
+   ```
+
+### Request Object Validation
+
+1. Test with valid signed request object:
+   ```bash
+   curl "http://localhost:9293/login?provider=https://op.example.com"
+   ```
+
+2. Test with invalid request object:
+   ```bash
+   curl "http://localhost:9292/auth?error_mode=invalid_request&request=invalid.jwt"
+   ```
+
+### Trust Chain Resolution
+
+1. Configure trust anchors in both servers
+2. Ensure RP has authority_hints pointing to trust anchor
+3. OP will resolve RP's trust chain during authorization
+4. OP will apply metadata policies from trust chain
+
+## Security Testing
+
+The mock servers support comprehensive security testing:
+
+- **Algorithm Confusion**: Test rejection of non-RS256 algorithms
+- **Key Confusion**: Test rejection of wrong keys
+- **Signature Verification**: Test rejection of tampered signatures
+- **Path Traversal**: Test rejection of malicious paths
+- **Replay Attacks**: Test nonce validation
+- **Request Object Validation**: Test signature and encryption validation
+- **Trust Chain Validation**: Test authority hints and metadata policy enforcement
+
+## Troubleshooting
+
+### Server Won't Start
+
+- Check if ports 9292 (OP) and 9293 (RP) are available
+- Verify all dependencies are installed: `bundle install`
+- Check configuration files exist and are valid YAML
+
+### Entity Statements Not Validating
+
+- Verify keys are correctly configured
+- Check entity IDs match between servers
+- Ensure trust anchors are configured if using trust chains
+
+### Request Objects Rejected
+
+- Verify RP's entity statement is accessible
+- Check RP's JWKS contains the signing key
+- Ensure request object is properly signed
+- Verify encryption if required by OP
+
+### Trust Chain Resolution Fails
+
+- Verify trust anchors are configured
+- Check authority_hints are correct
+- Ensure all entity statements in chain are valid
+- Verify subordinate statements are available
+
+## Next Steps
+
+1. **Add More Error Scenarios**: Extend error injection modes
+2. **Performance Testing**: Add load testing scenarios
+3. **Security Testing**: Add fuzzing and penetration tests
+4. **Trust Mark Testing**: Add trust mark validation
+5. **Metadata Policy Testing**: Add comprehensive policy merging tests
+

data/examples/README_MOCK_OP.md

@@ -0,0 +1,243 @@
+# Mock OpenID Provider (OP) Server
+
+A standalone Rack/Sinatra application for testing OpenID Federation flows.
+
+## Features
+
+- ✅ Entity Configuration endpoint (`/.well-known/openid-federation`)
+- ✅ Fetch Endpoint (`/.well-known/openid-federation/fetch`) for Subordinate Statements
+- ✅ Authorization Endpoint (`/auth`) with trust chain resolution
+- ✅ Token Endpoint (`/token`) with ID Token signing
+- ✅ JWKS endpoints (standard and signed)
+- ✅ UserInfo endpoint (mock)
+
+## Quick Start
+
+### 1. Install Dependencies
+
+```bash
+bundle install
+```
+
+### 2. Configure
+
+Copy the example configuration:
+
+```bash
+cp examples/config/mock_op.yml.example examples/config/mock_op.yml
+```
+
+Edit `examples/config/mock_op.yml` with your settings:
+
+```yaml
+entity_id: "https://op.example.com"
+server_host: "localhost:9292"
+signing_key: |
+  -----BEGIN RSA PRIVATE KEY-----
+  ...
+  -----END RSA PRIVATE KEY-----
+trust_anchors:
+  - entity_id: "https://ta.example.com"
+    jwks:
+      keys: [...]
+```
+
+### 3. Generate Keys (if needed)
+
+```bash
+# Generate OP signing key
+openssl genrsa -out op-private-key.pem 2048
+openssl rsa -in op-private-key.pem -pubout -out op-public-key.pem
+
+# Extract JWKS from public key (or use the rake task)
+rake openid_federation:prepare_client_keys
+```
+
+### 4. Run Server
+
+```bash
+# Option 1: Direct Ruby execution
+ruby examples/mock_op_server.rb
+
+# Option 2: Using Rack
+rackup examples/mock_op_server.ru
+
+# Option 3: With specific port
+rackup -p 9292 examples/mock_op_server.ru
+```
+
+## Configuration Options
+
+### Environment Variables
+
+Instead of YAML, you can use environment variables:
+
+```bash
+export OP_ENTITY_ID="https://op.example.com"
+export OP_SERVER_HOST="localhost:9292"
+export OP_SIGNING_KEY="$(cat op-private-key.pem)"
+export OP_TRUST_ANCHORS='[{"entity_id":"https://ta.example.com","jwks":{"keys":[...]}}]'
+export OP_AUTHORITY_HINTS="https://federation.example.com"
+```
+
+### YAML Configuration
+
+See `examples/config/mock_op.yml.example` for full configuration options.
+
+## Testing Scenarios
+
+### 1. Direct Entity Statement (No Trust Chain)
+
+```bash
+# Fetch OP's Entity Configuration
+curl http://localhost:9292/.well-known/openid-federation
+
+# Use in RP configuration
+config.omniauth :openid_federation,
+  issuer: "https://op.example.com",
+  entity_statement_url: "http://localhost:9292/.well-known/openid-federation",
+  client_options: { ... }
+```
+
+### 2. Trust Chain Resolution
+
+```bash
+# Configure trust anchors in mock_op.yml
+trust_anchors:
+  - entity_id: "https://ta.example.com"
+    jwks: {...}
+
+# RP with trust chain
+# The OP will resolve the RP's trust chain automatically
+curl "http://localhost:9292/auth?client_id=https://rp.example.com&redirect_uri=https://rp.example.com/callback"
+```
+
+### 3. Subordinate Statements
+
+```bash
+# Configure subordinate statements in mock_op.yml
+subordinate_statements:
+  "https://rp.example.com":
+    metadata: {...}
+    metadata_policy: {...}
+
+# Fetch Subordinate Statement
+curl "http://localhost:9292/.well-known/openid-federation/fetch?sub=https://rp.example.com"
+```
+
+## Endpoints
+
+| Endpoint | Method | Description |
+|----------|--------|-------------|
+| `/.well-known/openid-federation` | GET | Entity Configuration (JWT) |
+| `/.well-known/openid-federation/fetch` | GET | Fetch Subordinate Statement (requires `sub` parameter) |
+| `/.well-known/jwks.json` | GET | Standard JWKS (JSON) |
+| `/.well-known/signed-jwks.json` | GET | Signed JWKS (JWT) |
+| `/auth` | GET | Authorization Endpoint (requires `client_id`, `redirect_uri`) |
+| `/token` | POST | Token Endpoint (requires `code`, `grant_type=authorization_code`) |
+| `/userinfo` | GET | UserInfo Endpoint (mock data) |
+| `/` | GET | Health check and endpoint list |
+
+## Example Flow
+
+### 1. RP Discovers OP
+
+```bash
+# RP fetches OP's Entity Configuration
+curl http://localhost:9292/.well-known/openid-federation
+```
+
+### 2. RP Initiates Authentication
+
+```bash
+# RP redirects user to authorization endpoint
+# client_id is the RP's Entity ID (for automatic registration)
+curl "http://localhost:9292/auth?client_id=https://rp.example.com&redirect_uri=https://rp.example.com/callback&state=xyz&nonce=abc"
+```
+
+### 3. OP Resolves RP's Trust Chain
+
+The OP automatically:
+- Resolves RP's trust chain using `TrustChainResolver`
+- Merges metadata policies using `MetadataPolicyMerger`
+- Validates RP's effective metadata
+- Redirects back to RP with authorization code
+
+### 4. RP Exchanges Code for Tokens
+
+```bash
+curl -X POST http://localhost:9292/token \
+  -d "grant_type=authorization_code" \
+  -d "code=<authorization_code>" \
+  -d "redirect_uri=https://rp.example.com/callback" \
+  -d "client_id=https://rp.example.com"
+```
+
+### 5. RP Validates ID Token
+
+The RP validates the ID Token using the OP's JWKS from the effective metadata.
+
+## Integration with Real RP
+
+To test with a real RP application:
+
+```ruby
+# In RP's config/initializers/devise.rb
+config.omniauth :openid_federation,
+  issuer: "http://localhost:9292",
+  entity_statement_url: "http://localhost:9292/.well-known/openid-federation",
+  trust_anchors: [
+    {
+      entity_id: "https://ta.example.com",
+      jwks: trust_anchor_jwks
+    }
+  ],
+  client_options: {
+    identifier: "https://rp.example.com", # RP's Entity ID
+    redirect_uri: "http://localhost:3000/users/auth/openid_federation/callback",
+    private_key: rp_private_key
+  }
+```
+
+## Limitations
+
+This is a **mock server for testing only**:
+
+- ⚠️ No real user authentication (always returns mock user)
+- ⚠️ Authorization codes stored in memory (lost on restart)
+- ⚠️ No database persistence
+- ⚠️ No production security hardening
+- ⚠️ ID Tokens contain mock user data
+
+## Production Considerations
+
+For production use, you would need:
+
+- Real user authentication system
+- Database for authorization codes and tokens
+- Proper session management
+- Security hardening (rate limiting, CSRF protection, etc.)
+- Real user data in ID Tokens
+- Proper error handling and logging
+
+## Troubleshooting
+
+**"Federation endpoint not configured"**
+- Ensure `signing_key` is provided in config
+- Check that `entity_id` is set
+
+**"Trust chain resolution failed"**
+- Verify `trust_anchors` are correctly configured
+- Ensure trust anchor JWKS are valid
+- Check that RP's Entity ID is resolvable
+
+**"Subordinate Statement not found"**
+- Configure `subordinate_statements` in `mock_op.yml`
+- Ensure subject Entity ID matches exactly
+
+## See Also
+
+- [OpenID Federation 1.0 Specification](https://openid.net/specs/openid-federation-1_0.html)
+- [Main README](../README.md)
+- [Federation Endpoint Documentation](../README.md#publishing-federation-endpoint)
+

data/examples/app/controllers/users/omniauth_callbacks_controller.rb.example

@@ -0,0 +1,37 @@
+# Example OmniAuth callback controller for Devise
+# Copy this to app/controllers/users/omniauth_callbacks_controller.rb
+
+class Users::OmniauthCallbacksController < Devise::OmniauthCallbacksController
+  # Skip Rails CSRF protection for OAuth callbacks
+  # OAuth callbacks from external providers cannot include Rails CSRF tokens
+  # CSRF protection is handled by OAuth state parameter validation in the strategy
+  skip_before_action :verify_authenticity_token, only: [:openid_federation, :failure]
+  skip_before_action :authenticate_user!, only: [:openid_federation, :failure]
+
+  def openid_federation
+    auth = request.env["omniauth.auth"]
+    
+    @user = User.find_or_create_from_omniauth(auth)
+    
+    if @user&.persisted?
+      sign_in_and_redirect @user, event: :authentication
+    else
+      redirect_to root_path, alert: "Authentication failed"
+    end
+  end
+
+  def failure
+    error_type = request.env["omniauth.error.type"] || :unknown
+    error_message = request.env["omniauth.error"]&.message || "Authentication failed"
+    
+    Rails.logger.error({
+      message: "OmniAuth authentication failure",
+      error_type: error_type,
+      error_message: error_message,
+      strategy: request.env["omniauth.strategy"]&.name
+    })
+    
+    redirect_to root_path, alert: "Authentication failed: #{error_type}"
+  end
+end
+