generated from thegrind/laravel-dockerized
171 lines
4.1 KiB
Markdown
171 lines
4.1 KiB
Markdown
# 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```php
|
|
// 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:
|
|
|
|
```bash
|
|
# 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:
|
|
|
|
```yaml
|
|
- 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
|
|
|
|
```bash
|
|
# Run tests (keys automatically managed)
|
|
php artisan test
|
|
|
|
# Manually generate test keys
|
|
php artisan app:generate-keys --path=storage/testing/oauth
|
|
```
|
|
|
|
### CI/CD Environment
|
|
|
|
```bash
|
|
# 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
|
|
|
|
```php
|
|
// 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 |