notifier/docs/RBAC_QUICKSTART.md

RBAC Quick Start

60-Second Overview

Role-Based Access Control (RBAC) restricts which notifiers authenticated users can see and use.

Configuration

notifiers:
  smtp:
    primary:
      host: smtp.example.com
      allowed_roles: [admin, ops]    # Only these roles can use
    support:
      host: smtp.example.com
      allowed_roles: [support]        # Only support can use

Create Keys with Roles

# Admin key - access to all
curl -X POST /api/v1/admin/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d '{"client_id": "admin", "roles": ["admin"]}'

# Support key - limited access
curl -X POST /api/v1/admin/keys \
  -H "Authorization: Bearer $ADMIN_KEY" \
  -d '{"client_id": "support", "roles": ["support"]}'

Get Authorized Notifiers

Admin sees all:

curl -X GET /api/v1/notifiers \
  -H "Authorization: Bearer $ADMIN_KEY"

Returns: ["primary", "support"]

Support sees only theirs:

curl -X GET /api/v1/notifiers \
  -H "Authorization: Bearer $SUPPORT_KEY"

Returns: ["support"]

Send Notifications

Use authorized accounts:

# ✅ Allowed
curl -X POST /api/v1/notifications \
  -H "Authorization: Bearer $SUPPORT_KEY" \
  -d '{"type":"email", "account":"support", ...}'

# ❌ Forbidden
curl -X POST /api/v1/notifications \
  -H "Authorization: Bearer $SUPPORT_KEY" \
  -d '{"type":"email", "account":"primary", ...}'
# 403 Authorization denied

Key Concepts

Term	Meaning
Role	A permission label (e.g., "admin", "support", "engineering")
allowed_roles	Config field listing which roles can use an account
API Key Roles	Roles assigned to a key when created
Authorization	System checks if user's roles match account's allowed_roles

Common Patterns

Pattern 1: By Team

notifiers:
  slack:
    engineering:
      allowed_roles: [engineering]
    marketing:
      allowed_roles: [marketing]
    admin:
      allowed_roles: [admin]

Pattern 2: By Service (Least Privilege)

notifiers:
  smtp:
    alerts:
      allowed_roles: [alerts-service]
    billing:
      allowed_roles: [billing-service]

Pattern 3: Public + Private

notifiers:
  smtp:
    public:
      # No allowed_roles = all authenticated users
    private:
      allowed_roles: [admin]

Authorization Logic (Simple)

User has role "support"

For account "primary":
  allowed_roles: [admin, ops]
  Does "support" match? NO → NOT VISIBLE

For account "support":
  allowed_roles: [support]
  Does "support" match? YES → VISIBLE

Troubleshooting

User Sees No Notifiers

• Check user's key roles: curl /api/v1/admin/keys -H "Authorization: Bearer $KEY"
• Check notifier config: grep allowed_roles config.yaml
• Ensure at least one role matches

403 When Sending Notification

• Check account name in request
• Verify that account's allowed_roles include your key's roles
• Or try without specifying account (uses default)

Default Account Not Working

• If user not authorized for default, first authorized account is used
• Or specify the account explicitly

Real-World Example

Config (config.yaml):

notifiers:
  smtp:
    prod-alerts:
      host: smtp.example.com
      from: alerts@example.com
      allowed_roles: [ops, admin]  # Only ops and admin

    support-email:
      host: smtp.example.com
      from: support@example.com
      allowed_roles: [support]     # Only support

Create Keys:

# Ops team
curl -X POST /api/v1/admin/keys -d '{
  "client_id": "ops-monitor",
  "roles": ["ops"]
}'

# Support team
curl -X POST /api/v1/admin/keys -d '{
  "client_id": "support-alerts",
  "roles": ["support"]
}'

Usage:

# Ops can send prod alerts
curl -X POST /api/v1/notifications \
  -H "Authorization: Bearer $OPS_KEY" \
  -d '{
    "type": "email",
    "account": "prod-alerts",
    "recipients": ["ops@example.com"]
  }'
# ✅ Works

# Support can send support emails
curl -X POST /api/v1/notifications \
  -H "Authorization: Bearer $SUPPORT_KEY" \
  -d '{
    "type": "email",
    "account": "support-email",
    "recipients": ["customer@example.com"]
  }'
# ✅ Works

# Support cannot send prod alerts
curl -X POST /api/v1/notifications \
  -H "Authorization: Bearer $SUPPORT_KEY" \
  -d '{
    "type": "email",
    "account": "prod-alerts",
    "recipients": ["ops@example.com"]
  }'
# ❌ 403 Forbidden

Security Tips

✅ DO:

• Create specific roles for each team/service
• Grant minimal required roles to each key
• Use "admin" only when necessary
• Rotate keys regularly

❌ DON'T:

• Give everyone "admin" role
• Share keys between services
• Leave restrictions empty if you want to restrict
• Grant roles you don't need

Full Docs

See docs/RBAC.md for complete documentation.