authentikate/docs/TESTING_KEYS.md

Testing RSA Keys Management

This document explains how RSA keys are managed during testing to ensure that running tests doesn't interfere with production keys.

Overview

The application uses RSA keys for OIDC (OpenID Connect) JWT token signing. To prevent tests from deleting or overwriting production keys, we've implemented a separate key management system for testing environments.

Key Features

1. Environment-Aware Key Paths

• Production: storage/oauth/
• Testing: storage/testing/oauth/

2. Enhanced Generate Keys Command

The app:generate-keys command now supports:

# Generate keys in default location (environment-dependent)
php artisan app:generate-keys

# Generate keys in custom location
php artisan app:generate-keys --path=/custom/path

Environment Behavior:

• Production: Uses storage/oauth/
• Testing: Uses storage/testing/oauth/

3. Test Key Management Trait

The ManagesTestKeys trait provides methods for managing test keys:

// Set up test keys before test suite
ManagesTestKeys::setUpTestKeys()

// Clean up test keys after test suite
ManagesTestKeys::tearDownTestKeys()

// Ensure test keys exist for current test
$this->ensureTestKeysExist()

4. CI/CD Script

The scripts/setup-test-keys.sh script provides commands for CI/CD environments:

# Set up test keys
./scripts/setup-test-keys.sh setup

# Clean up test keys
./scripts/setup-test-keys.sh cleanup

# Reset (cleanup and regenerate) test keys
./scripts/setup-test-keys.sh reset

Implementation Details

Files Modified

1. app/Console/Commands/GenerateKeys.php

   • Added --path option
   • Environment-aware default paths
   • Uses storage/testing/oauth/ in testing environment

2. app/Http/Controllers/OIDCController.php

   • Added helper methods getPrivateKeyPath() and getPublicKeyPath()
   • Uses test keys in testing environment

3. tests/Feature/GenerateKeysCommandTest.php

   • Updated to use test directory
   • Added test for custom path option

4. tests/Feature/OIDCControllerTest.php

   • Uses ManagesTestKeys trait
   • Automatically generates test keys before tests

5. .gitignore

   • Added /storage/testing/* to ignore test files

Test Key Management

Automatic Generation

Test keys are automatically generated when needed:

1. When running OIDCControllerTest, keys are generated in beforeEach
2. Keys are only generated if they don't already exist
3. Uses the same RSA 2048-bit specification as production

Cleanup

Test keys are cleaned up:

1. After each test in GenerateKeysCommandTest
2. Can be manually cleaned using the script
3. Not committed to version control (ignored in .gitignore)

GitHub Actions Integration

Example workflow configuration:

- name: Set up test RSA keys
  run: ./scripts/setup-test-keys.sh setup

- name: Run tests
  run: php artisan test --coverage

- name: Clean up test RSA keys
  run: ./scripts/setup-test-keys.sh cleanup
  if: always()

Benefits

1. Safety: Production keys are never affected by tests
2. Isolation: Each test environment has its own keys
3. Consistency: Same key generation process for all environments
4. CI/CD Ready: Works seamlessly in automated environments
5. Flexibility: Custom paths supported for advanced use cases

Usage Examples

Local Development

# Run tests (keys automatically managed)
php artisan test

# Manually generate test keys
php artisan app:generate-keys --path=storage/testing/oauth

CI/CD Environment

# Set up environment
./scripts/setup-test-keys.sh setup

# Run tests
php artisan test

# Clean up
./scripts/setup-test-keys.sh cleanup

Custom Testing Setup

// In a test file
use Tests\Support\ManagesTestKeys;

uses(ManagesTestKeys::class);

beforeEach(function () {
    $this->ensureTestKeysExist();
});

Security Considerations

1. Test keys are generated with the same security parameters as production
2. Test keys are temporary and not persisted
3. Test directories are excluded from version control
4. No hardcoded keys in test files