302 lines
12 KiB
Markdown
302 lines
12 KiB
Markdown
# Sensor Authentication Overview
|
|
|
|
**Version:** 1.0
|
|
**Last Updated:** 2025-01-27
|
|
|
|
## Quick Summary
|
|
|
|
This document provides a quick overview of how sensors authenticate with Attune. For full details, see:
|
|
|
|
- **[Sensor Interface Specification](./sensor-interface.md)** - Complete sensor implementation guide
|
|
- **[Service Accounts](./service-accounts.md)** - Token creation and management
|
|
|
|
## How It Works
|
|
|
|
1. **Admin creates sensor service account** via API:
|
|
```bash
|
|
POST /service-accounts
|
|
{
|
|
"name": "sensor:core.timer",
|
|
"scope": "sensor",
|
|
"ttl_days": 90
|
|
}
|
|
```
|
|
|
|
2. **Admin receives long-lived token** (shown only once):
|
|
```json
|
|
{
|
|
"identity_id": 123,
|
|
"token": "eyJhbGci...",
|
|
"expires_at": "2025-04-27T12:34:56Z"
|
|
}
|
|
```
|
|
|
|
3. **Token is deployed with sensor** via environment variable:
|
|
```bash
|
|
export ATTUNE_API_TOKEN="eyJhbGci..."
|
|
export ATTUNE_API_URL="http://localhost:8080"
|
|
export ATTUNE_SENSOR_REF="core.timer"
|
|
./attune-sensor
|
|
```
|
|
|
|
4. **Sensor uses token for all API calls**:
|
|
- Fetch active rules: `GET /rules?trigger_type=core.timer`
|
|
- Create events: `POST /events`
|
|
- Fetch trigger metadata: `GET /triggers/{ref}`
|
|
|
|
## Token Properties
|
|
|
|
| Property | Value |
|
|
|----------|-------|
|
|
| **Type** | JWT (stateless) |
|
|
| **Lifetime** | 24-72 hours (auto-expires, REQUIRED) |
|
|
| **Scope** | `sensor` |
|
|
| **Permissions** | Create events, read rules/triggers (restricted to declared trigger types) |
|
|
| **Revocable** | Yes (via `/service-accounts/{id}` DELETE) |
|
|
| **Rotation** | Manual every 24-72 hours (sensor restart required) |
|
|
| **Expiration** | All tokens MUST have `exp` claim to prevent revocation table bloat |
|
|
|
|
## Security Best Practices
|
|
|
|
### DO:
|
|
- ✅ Store tokens in environment variables or secure config management
|
|
- ✅ Use HTTPS for API calls in production
|
|
- ✅ Redact tokens in logs (show only last 4 characters)
|
|
- ✅ Revoke tokens immediately if compromised
|
|
- ✅ Use separate tokens for each sensor type
|
|
- ✅ Set TTL to 24-72 hours for sensors (requires periodic rotation)
|
|
- ✅ Monitor token expiration and rotate before expiry
|
|
|
|
### DON'T:
|
|
- ❌ Commit tokens to version control
|
|
- ❌ Log full token values
|
|
- ❌ Share tokens between sensors
|
|
- ❌ Send tokens over unencrypted connections
|
|
- ❌ Store tokens on disk unencrypted
|
|
- ❌ Pass tokens in URL query parameters
|
|
|
|
## Configuration Methods
|
|
|
|
### Method 1: Environment Variables (Recommended)
|
|
|
|
```bash
|
|
export ATTUNE_API_URL="http://localhost:8080"
|
|
export ATTUNE_API_TOKEN="eyJhbGci..."
|
|
export ATTUNE_SENSOR_REF="core.timer"
|
|
export ATTUNE_MQ_URL="amqp://localhost:5672"
|
|
|
|
./attune-sensor
|
|
```
|
|
|
|
### Method 2: stdin JSON
|
|
|
|
```bash
|
|
echo '{
|
|
"api_url": "http://localhost:8080",
|
|
"api_token": "eyJhbGci...",
|
|
"sensor_ref": "core.timer",
|
|
"mq_url": "amqp://localhost:5672"
|
|
}' | ./attune-sensor
|
|
```
|
|
|
|
### Method 3: Configuration File + Environment Override
|
|
|
|
```yaml
|
|
# sensor.yaml
|
|
api_url: http://localhost:8080
|
|
sensor_ref: core.timer
|
|
mq_url: amqp://localhost:5672
|
|
# Token provided via environment for security
|
|
```
|
|
|
|
```bash
|
|
export ATTUNE_API_TOKEN="eyJhbGci..."
|
|
./attune-sensor --config sensor.yaml
|
|
```
|
|
|
|
## Token Lifecycle
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 1. Admin creates service account │
|
|
│ POST /service-accounts │
|
|
└─────────────────┬───────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 2. API generates JWT token │
|
|
│ - Sets scope: "sensor" │
|
|
│ - Sets expiration (e.g., 90 days) │
|
|
│ - Includes identity_id, trigger_types │
|
|
└─────────────────┬───────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 3. Token stored securely by admin │
|
|
│ - Environment variable │
|
|
│ - Secret management system (Vault, k8s secrets) │
|
|
└─────────────────┬───────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 4. Sensor starts and reads token │
|
|
│ - From ATTUNE_API_TOKEN env var │
|
|
│ - Or from stdin JSON │
|
|
└─────────────────┬───────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 5. Sensor makes API calls with token │
|
|
│ Authorization: Bearer eyJhbGci... │
|
|
└─────────────────┬───────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 6. API validates token on each request │
|
|
│ - Verify JWT signature │
|
|
│ - Check expiration │
|
|
│ - Check revocation list │
|
|
│ - Verify scope matches endpoint requirements │
|
|
└─────────────────┬───────────────────────────────────────────┘
|
|
│
|
|
▼
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ 7. Token eventually expires or is revoked │
|
|
│ - Auto-expires after TTL │
|
|
│ - Or admin revokes: DELETE /service-accounts/{id} │
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
## JWT Token Structure
|
|
|
|
```json
|
|
{
|
|
"sub": "sensor:core.timer",
|
|
"jti": "abc123...",
|
|
"iat": 1706356496,
|
|
"exp": 1714132496,
|
|
"identity_id": 123,
|
|
"identity_type": "service_account",
|
|
"scope": "sensor",
|
|
"metadata": {
|
|
"trigger_types": ["core.timer"]
|
|
}
|
|
}
|
|
```
|
|
|
|
## Permissions by Scope
|
|
|
|
| Scope | Create Events | Read Rules | Read Triggers | Read Keys | Update Execution |
|
|
|-------|---------------|------------|---------------|-----------|------------------|
|
|
| `sensor` | ✅ (restricted)* | ✅ | ✅ | ❌ | ❌ |
|
|
| `action_execution` | ❌ | ❌ | ❌ | ✅ | ✅ |
|
|
| `webhook` | ✅ | ❌ | ❌ | ❌ | ❌ |
|
|
| `user` | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
| `admin` | ✅ | ✅ | ✅ | ✅ | ✅ |
|
|
|
|
**\* Sensor tokens can only create events for trigger types declared in their token's `metadata.trigger_types`. The API enforces this restriction and returns `403 Forbidden` for unauthorized trigger types.**
|
|
|
|
## Example: Creating a Sensor Token
|
|
|
|
```bash
|
|
# 1. Create service account (admin only)
|
|
curl -X POST http://localhost:8080/service-accounts \
|
|
-H "Authorization: Bearer ${ADMIN_TOKEN}" \
|
|
-H "Content-Type: application/json" \
|
|
-d '{
|
|
"name": "sensor:core.timer",
|
|
"scope": "sensor",
|
|
"description": "Timer sensor for interval-based triggers",
|
|
"ttl_hours": 72,
|
|
"metadata": {
|
|
"trigger_types": ["core.timer"]
|
|
}
|
|
}'
|
|
|
|
# Note: This token can ONLY create events for "core.timer" trigger type.
|
|
# Attempting to create events for other trigger types will fail with 403 Forbidden.
|
|
|
|
# Response (SAVE THE TOKEN - shown only once):
|
|
{
|
|
"identity_id": 123,
|
|
"name": "sensor:core.timer",
|
|
"scope": "sensor",
|
|
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJzZW5zb3I6Y29yZS50aW1lciIsImp0aSI6ImFiYzEyMyIsImlhdCI6MTcwNjM1NjQ5NiwiZXhwIjoxNzA2NjE1Njk2LCJpZGVudGl0eV9pZCI6MTIzLCJpZGVudGl0eV90eXBlIjoic2VydmljZV9hY2NvdW50Iiwic2NvcGUiOiJzZW5zb3IiLCJtZXRhZGF0YSI6eyJ0cmlnZ2VyX3R5cGVzIjpbImNvcmUudGltZXIiXX19.signature",
|
|
"expires_at": "2025-01-30T12:34:56Z"
|
|
}
|
|
|
|
# 2. Deploy token with sensor
|
|
export ATTUNE_API_TOKEN="eyJhbGci..."
|
|
export ATTUNE_API_URL="http://localhost:8080"
|
|
export ATTUNE_SENSOR_REF="core.timer"
|
|
export ATTUNE_MQ_URL="amqp://localhost:5672"
|
|
|
|
./attune-sensor
|
|
|
|
# 3. Rotate token before expiration (every 24-72 hours)
|
|
# - Create new service account
|
|
# - Update ATTUNE_API_TOKEN
|
|
# - Restart sensor
|
|
```
|
|
|
|
## Troubleshooting
|
|
|
|
### Token Validation Errors
|
|
|
|
**Error: "Token expired"**
|
|
- Token has exceeded its TTL
|
|
- Solution: Create a new service account and token
|
|
|
|
**Error: "Token revoked"**
|
|
- Token was manually revoked by admin
|
|
- Solution: Create a new service account and token
|
|
|
|
**Error: "Invalid signature"**
|
|
- JWT_SECRET mismatch between token creation and validation
|
|
- Solution: Ensure all services use the same JWT_SECRET
|
|
|
|
**Error: "Insufficient permissions"**
|
|
- Token scope doesn't match required endpoint permissions
|
|
- For sensors: Attempting to create event for trigger type not in `metadata.trigger_types`
|
|
- Solution: Create token with correct scope and trigger types (e.g., "sensor" scope with ["core.timer"])
|
|
|
|
### Common Mistakes
|
|
|
|
1. **Using user token for sensor**: User tokens have different scope, create a service account instead
|
|
2. **Hardcoding token in code**: Use environment variables or config management
|
|
3. **Sharing token between sensors**: Each sensor should have its own token
|
|
4. **Not revoking compromised tokens**: Use DELETE /service-accounts/{id} immediately
|
|
|
|
## Implementation Status
|
|
|
|
- [ ] Database schema for service accounts (`identity_type` column)
|
|
- [ ] Database schema for token revocation (`token_revocation` table with `token_exp` column)
|
|
- [ ] API endpoint: POST /service-accounts (with TTL parameter)
|
|
- [ ] API endpoint: GET /service-accounts
|
|
- [ ] API endpoint: DELETE /service-accounts/{id}
|
|
- [ ] Middleware for token validation (check expiration)
|
|
- [ ] Middleware for revocation checking (skip expired tokens)
|
|
- [ ] Executor creates execution tokens (TTL = action timeout)
|
|
- [ ] Worker passes execution tokens to actions
|
|
- [ ] CLI commands for service account management
|
|
- [ ] Sensor accepts and uses tokens
|
|
- [ ] Cleanup job for expired token revocations (hourly cron)
|
|
- [ ] Monitoring alerts for token expiration (6 hours before)
|
|
|
|
## Next Steps
|
|
|
|
1. Implement database migrations for service accounts
|
|
2. Add service account CRUD endpoints to API (with TTL parameters)
|
|
3. Update sensor to accept and use API tokens
|
|
4. Add token creation to executor for action executions (TTL = action timeout)
|
|
5. Implement cleanup job for expired token revocations
|
|
6. Document token rotation procedures (manual every 24-72 hours)
|
|
7. Add monitoring for token expiration warnings (alert 6 hours before)
|
|
8. Add graceful handling of token expiration in sensors
|
|
|
|
## Related Documentation
|
|
|
|
- [Sensor Interface Specification](./sensor-interface.md) - Full sensor implementation guide
|
|
- [Service Accounts](./service-accounts.md) - Detailed token management
|
|
- [API Architecture](./api-architecture.md) - API design and authentication
|
|
- [Security Best Practices](./security.md) - Security guidelines (future) |