137 lines
3.3 KiB
Markdown
137 lines
3.3 KiB
Markdown
# OIDC Private Key Setup
|
|
|
|
Your OIDC provider needs an RSA private key to sign ID tokens. **This key must persist across deployments** or all existing tokens will become invalid.
|
|
|
|
## Option 1: Environment Variable (Recommended for Docker/Kamal)
|
|
|
|
### 1. Generate the key
|
|
|
|
```bash
|
|
# Generate a 2048-bit RSA key
|
|
openssl genrsa -out oidc_private_key.pem 2048
|
|
|
|
# View the key (you'll copy this)
|
|
cat oidc_private_key.pem
|
|
```
|
|
|
|
### 2. Store in your `.env` file
|
|
|
|
```bash
|
|
# .env (for local development)
|
|
OIDC_PRIVATE_KEY="-----BEGIN RSA PRIVATE KEY-----
|
|
MIIEpAIBAAKCAQEAyZ0qaICMiLVWSFs+ef9Xok3fzy0p6k/7D5TQzmxf7C2vQG7s
|
|
2Odmi8iAHLoaUBaFj70qTbaconWyMr8s+ah+qZwrwolTLUe23VrceVXvInU57hBL
|
|
...
|
|
-----END RSA PRIVATE KEY-----"
|
|
```
|
|
|
|
**Important:** Keep the quotes and include the full key with `-----BEGIN` and `-----END` lines.
|
|
|
|
### 3. For Kamal deployment
|
|
|
|
Add to your Kamal secrets:
|
|
|
|
```yaml
|
|
# config/deploy.yml
|
|
env:
|
|
secret:
|
|
- OIDC_PRIVATE_KEY
|
|
```
|
|
|
|
Then set it securely:
|
|
|
|
```bash
|
|
# Generate key
|
|
bin/generate_oidc_key > oidc_private_key.pem
|
|
|
|
# Add to .kamal/secrets
|
|
echo "OIDC_PRIVATE_KEY=$(cat oidc_private_key.pem)" >> .kamal/secrets
|
|
```
|
|
|
|
### 4. Verify it's loaded
|
|
|
|
```bash
|
|
# In Rails console
|
|
bin/rails runner "puts OidcJwtService.send(:private_key).present? ? 'Key loaded' : 'Key missing'"
|
|
```
|
|
|
|
---
|
|
|
|
## Comparison
|
|
|
|
| Feature | ENV Variable | Rails Credentials |
|
|
|---------|-------------|-------------------|
|
|
| **Best for** | Docker, Kamal, 12-factor | Simple deployments |
|
|
| **Key rotation** | Easy (just update ENV) | Medium (re-encrypt) |
|
|
| **Per-environment** | Yes (dev/staging/prod can differ) | No (same key everywhere) |
|
|
| **Secrets manager** | Compatible (AWS Secrets, etc.) | Needs RAILS_MASTER_KEY |
|
|
| **Setup complexity** | Low | Medium |
|
|
|
|
**Recommendation:** Use ENV variable (`OIDC_PRIVATE_KEY`) for production with Kamal.
|
|
|
|
---
|
|
|
|
## Security Best Practices
|
|
|
|
### DO:
|
|
- ✅ Generate the key once and keep it forever
|
|
- ✅ Store in secret manager (AWS Secrets Manager, 1Password, etc.)
|
|
- ✅ Use strong key (2048-bit RSA minimum)
|
|
- ✅ Backup the key securely
|
|
- ✅ Restrict access (only ops team)
|
|
|
|
### DON'T:
|
|
- ❌ Commit the key to git (except encrypted credentials)
|
|
- ❌ Share the key in Slack/email
|
|
- ❌ Regenerate the key (invalidates all tokens)
|
|
- ❌ Store in `.env` if it's committed to git
|
|
- ❌ Use the same key for multiple environments
|
|
|
|
---
|
|
|
|
## Key Rotation (Advanced)
|
|
|
|
Todo
|
|
|
|
---
|
|
|
|
## Troubleshooting
|
|
|
|
### "No private key found" warning
|
|
|
|
Check your setup:
|
|
|
|
```bash
|
|
# Is ENV set?
|
|
echo $OIDC_PRIVATE_KEY
|
|
|
|
# Can Rails load it?
|
|
bin/rails runner "puts ENV['OIDC_PRIVATE_KEY'].present? ? 'ENV set' : 'ENV missing'"
|
|
|
|
# Does it load correctly?
|
|
bin/rails runner "puts OidcJwtService.send(:private_key).to_s[0..50]"
|
|
```
|
|
|
|
### "invalid RSA key" error
|
|
|
|
- Make sure you include `-----BEGIN RSA PRIVATE KEY-----` header
|
|
- Ensure newlines are preserved (use quotes in ENV)
|
|
- Check for extra spaces or characters
|
|
|
|
### Different JWKS key ID on each restart
|
|
|
|
This means the key is being regenerated. You need to set `OIDC_PRIVATE_KEY` or add to credentials.
|
|
|
|
### All tokens invalid after deployment
|
|
|
|
The key changed. You either:
|
|
- Regenerated the key (don't do this!)
|
|
- Forgot to set ENV variable in production
|
|
- The key wasn't loaded correctly
|
|
|
|
Check logs for warnings and verify key is loaded:
|
|
|
|
```bash
|
|
kamal app logs --grep "OIDC"
|
|
```
|