132 lines
3.3 KiB
Markdown
132 lines
3.3 KiB
Markdown
# Authentication Quick Start Guide
|
|
|
|
## 1. Enable Authentication
|
|
|
|
Update your `config.yaml`:
|
|
|
|
```yaml
|
|
auth:
|
|
enabled: true
|
|
default_rate_limit: 100 # requests/minute
|
|
```
|
|
|
|
## 2. Generate an API Key (Programmatically)
|
|
|
|
```go
|
|
store := auth.NewAPIKeyStore()
|
|
|
|
// Create a key that expires in 30 days
|
|
expiresIn := 30 * 24 * time.Hour
|
|
key, _ := store.CreateKey(
|
|
"my-app", // Client ID
|
|
[]string{"notify-email", "notify-slack"}, // Roles
|
|
100, // Rate limit (req/min)
|
|
&expiresIn, // Expiration
|
|
)
|
|
|
|
fmt.Println(key.Key) // nk_<hex>
|
|
```
|
|
|
|
## 3. Use the Key in REST API
|
|
|
|
```bash
|
|
curl -X POST http://localhost:8080/api/v1/notifications \
|
|
-H "Authorization: Bearer nk_<your-api-key>" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"type": "email",
|
|
"subject": "Test",
|
|
"body": "Hello!",
|
|
"recipients": ["user@example.com"]
|
|
}'
|
|
```
|
|
|
|
## 4. Use the Key in gRPC
|
|
|
|
```go
|
|
md := metadata.New(map[string][]string{
|
|
"authorization": {"bearer nk_<your-api-key>"},
|
|
})
|
|
ctx := metadata.NewOutgoingContext(context.Background(), md)
|
|
|
|
client.SendNotification(ctx, &pb.SendNotificationRequest{...})
|
|
```
|
|
|
|
## 5. Configure Role-Based Access (Optional)
|
|
|
|
In `config.yaml`, restrict which roles can use each notifier:
|
|
|
|
```yaml
|
|
notifiers:
|
|
smtp:
|
|
default:
|
|
host: "smtp.example.com"
|
|
...
|
|
allowed_roles:
|
|
- "notify-email" # Only clients with this role can use
|
|
- "admin"
|
|
|
|
slack:
|
|
default:
|
|
webhook_url: "..."
|
|
allowed_roles:
|
|
- "notify-slack"
|
|
```
|
|
|
|
If `allowed_roles` is empty or omitted, any authenticated user can use the notifier.
|
|
|
|
## 6. Store Keys Securely
|
|
|
|
**Never commit API keys to Git.**
|
|
|
|
Use environment variables:
|
|
|
|
```bash
|
|
# .env (not in Git)
|
|
export NOTIFIER_API_KEY="nk_abc123..."
|
|
|
|
# In your app
|
|
apiKey := os.Getenv("NOTIFIER_API_KEY")
|
|
```
|
|
|
|
Or use a secrets manager (Vault, AWS Secrets Manager, etc.).
|
|
|
|
## 7. Monitor Logs
|
|
|
|
Authentication events are logged. Look for:
|
|
- `auth_success` - Successful API key validation
|
|
- `auth_failure` - Failed authentication attempts
|
|
- `rate_limit_exceeded` - Rate limit violation
|
|
|
|
## Key Concepts
|
|
|
|
| Term | Meaning |
|
|
|------|---------|
|
|
| **API Key** | Token used to authenticate requests (format: `nk_<32-hex>`) |
|
|
| **Client ID** | Identifier for the app/service using the key |
|
|
| **Role** | Permission level (e.g., "notify-email", "admin") |
|
|
| **Rate Limit** | Max requests per minute (0 = unlimited) |
|
|
| **Expiration** | Optional date when key becomes invalid |
|
|
|
|
## Default Configuration (Auth Disabled)
|
|
|
|
If you don't set `auth.enabled: true`, authentication is **not enforced** and API keys are not checked. This is the default for backward compatibility.
|
|
|
|
## Troubleshooting
|
|
|
|
| Error | Cause | Solution |
|
|
|-------|-------|----------|
|
|
| `401 Unauthorized` | Missing/invalid API key | Check header is set correctly |
|
|
| `403 Forbidden` | Role not allowed | Add role to notifier's `allowed_roles` |
|
|
| `429 Too Many Requests` | Rate limit exceeded | Wait 60 seconds or create new key with higher limit |
|
|
| `Invalid API key` | Key doesn't exist or expired | Check key format and expiration date |
|
|
|
|
## Full Documentation
|
|
|
|
See `docs/AUTH.md` for comprehensive documentation including:
|
|
- Credential management best practices
|
|
- Multi-language client examples
|
|
- Configuration examples
|
|
- Monitoring and auditing
|
|
- Advanced scenarios
|