RBAC Best Practices

This guide covers recommended patterns for managing roles and permissions in Rack Gateway.

Principle of Least Privilege

Start Restrictive

Begin with Viewer role and upgrade only when needed. It’s easier to add permissions than to remove them.

Just-In-Time Access

Grant elevated access temporarily when needed, then revoke. Use API tokens with limited scope for automation.

Role Selection Guidelines

User Type	Recommended Role	Rationale
New team member	Viewer	Observe first, learn the system
Developer (feature work)	Deployer	Deploy but not delete
On-call engineer	Ops	Debug without deploy access
CI/CD pipeline	CI/CD (token)	Minimal automation scope
Platform admin	Admin	Full access when needed
External auditor	Viewer	Read-only compliance review

Separation of Duties

Rack Gateway’s role hierarchy naturally separates concerns:

Recommended Team Structure

Typical Setup

For a team of 10 engineers:

• 2-3 Admins (lead engineers, security team)
• 5-6 Deployers (active developers)
• 2-3 Ops (SRE, on-call rotation)
• Remaining as Viewers

Anti-patterns to avoid:

• Making everyone an Admin “for convenience”
• Giving Deployer access to all engineers regardless of responsibility
• Using personal credentials in CI/CD pipelines

API Token Management

Token Role Selection

Use Case	Recommended Role	Why
CI/CD deployment	CI/CD	Limited scope, requires approval
Monitoring/alerting	Viewer	Read-only access to status
Automated testing	Viewer	Just needs to list/read
Emergency scripts	Ops	Restart capability only

Token Lifecycle

1. Create with specific purpose

   Name tokens descriptively: ci-production-deploy, monitoring-datadog, emergency-restart

   rack-gateway api-token create --name "ci-production-deploy" --role cicd

2. Set appropriate role

   Always use the minimum required role. CI/CD tokens should use the cicd role, not deployer.

3. Store securely

   • Use secrets management (AWS Secrets Manager, HashiCorp Vault)
   • Never commit tokens to git
   • Rotate tokens periodically

4. Monitor usage

   Review token activity in audit logs. Investigate tokens that haven’t been used in 90+ days.

5. Revoke when no longer needed

   Delete tokens immediately when pipelines are decommissioned. Give short-lived tokens an expiry (--expires-at).

Token Permissions

A token can only do what both its own permissions and its owner’s current roles allow. An admin can create a viewer-level token; when the owner is demoted or locked, their tokens lose that access too.

Token Best Practices

Do	Don’t
Use CI/CD role for pipelines	Use Deployer role for automation
Name tokens descriptively	Use generic names like “token-1”
Rotate tokens quarterly	Keep tokens indefinitely
Use separate tokens per environment	Share tokens across staging/production
Audit unused tokens monthly	Ignore token activity

Environment Separation

Per-Environment Gateways

Deploy separate gateway instances for each environment:

Production Gateway → Production Rack
Staging Gateway    → Staging Rack
Development Gateway → Dev Rack

Benefits:

• Complete isolation between environments
• Different admin sets per environment
• Independent audit trails
• Separate settings (session timeout, step-up window, deploy approvals)

Role Differences by Environment

Environment	Admin Count	Deployer Scope
Production	2-3 only	Experienced devs
Staging	3-5	All developers
Development	5+	All developers

Keep MFA required everywhere: every gateway requires it for all users by default (mfa_require_all_users), and the CLI requires every user to be enrolled whatever that setting says.

Audit and Review Practices

Regular Access Reviews

1. Monthly: Token audit

   • Review all API tokens
   • Identify unused tokens (>30 days)
   • Verify token roles match current needs

2. Quarterly: Role review

   • Review all user roles
   • Identify users who changed teams
   • Downgrade inactive users to Viewer

3. Annually: Full access audit

   • Document all admin users
   • Review role assignments vs job functions
   • Update for organizational changes

Using Audit Logs

Use the Audit Logs page (admins) to find access patterns. It filters by user, status (for example denied for refused requests), action type, resource type, free text and time range, and exports the results as CSV. The same filters work on the API:

# Requests refused in the last 30 days
curl -b "session_token=$TOKEN" \
  "https://gateway.example.com/api/v1/audit-logs?status=denied&range=30d"

# Everything one user did since July 1, as CSV
curl -b "session_token=$TOKEN" \
  "https://gateway.example.com/api/v1/audit-logs/export?user=developer@example.com&start=2026-07-01T00:00:00Z"

range takes 15m, 1h, 24h (the default), 7d, 30d or all; start and end set a custom range.

Note

Audit logs are essential for SOC 2 compliance. Ensure they’re configured with appropriate retention and stored in immutable storage.

MFA and Roles

MFA requirements belong to permissions, not roles: the same action needs the same MFA whoever performs it. Writes such as restarts, exec and env changes need a recent step-up; deleting apps, changing users or API tokens and approving deploys need MFA on the request itself. See MFA Requirements for the full list. API tokens can’t do MFA, so give them only the permissions their pipeline needs.

Incident Response

Compromised User Account

1. Immediate: Lock the user account (web UI: Users → the user → Lock). Locking signs them out of every session, and their API tokens stop working while they’re locked

2. Check sessions: Confirm on the user’s page that no sessions remain

3. Audit: Review all actions by the user in last 30 days

4. Remediate: Change any secrets the user had access to

5. Investigate: Determine how the compromise occurred

6. Restore: Unlock account after re-verification

Compromised API Token

1. Immediate: Delete the token

   # In web UI: API Tokens → Select Token → Delete

2. Audit: Review all actions by the token

3. Update: Generate new token with fresh credentials

4. Rotate: Update all systems using the old token

5. Investigate: Determine how the token was exposed

Common Patterns

On-Call Rotation

Implementation:

• Base role: Viewer for all engineers
• On-call: Temporary upgrade to Ops
• Escalation: Temporary upgrade to Deployer for hotfixes

Feature Teams

Different teams may need different access levels:

Team	Base Role	Notes
Platform	Admin	Manages infrastructure
Backend	Deployer	Full deploy access
Frontend	Deployer	Full deploy access
QA	Viewer	Read-only for testing
Security	Admin	Audit and review

Contractor Access

For external contractors:

1. Start with Viewer role
2. Upgrade to specific role only for duration of engagement
3. Immediately downgrade when engagement ends
4. Audit all actions during engagement

Checklist

Before going to production:

• No more than 3 admin users
• CI/CD uses dedicated tokens with CI/CD role
• MFA enabled for all admin and deployer users
• API tokens have descriptive names
• Audit logging configured with retention policy
• Access review process documented
• Incident response runbook created
• Unused tokens identified and deleted

Next Steps

• Roles - Detailed role definitions
• Permissions - Complete permission reference
• Audit Trail - Audit logging details