# Admin Access Control Specification

> Specify admin roles, permissions, and every admin-facing control in a system - a full role-permission matrix (RBAC), the principle of least privilege applied concretely, admin action audit logging, and emergency/break-glass access procedures. Use whenever a system has more than one privilege level, before building the admin panel or access-control logic.

- Skill: `fattain-naime/admin-access-control-specification` (Agent Skill, multi-file: 2 files)
- Install (CLI): `npx skillmds@latest add fattain-naime/admin-access-control-specification`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fattain-naime/admin-access-control-specification/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Security
- License: MIT
- Author: fattain-naime (https://skillmd.com/u/fattain-naime)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fattain-naime/admin-access-control-specification

---


## Purpose

Produce an access control specification that defines every privilege level in a system, exactly what each one can and cannot do, how admin actions are logged, and what happens when access is needed outside the normal process.

**"If user.is_admin" is not an access control design - it's the absence of one.** This document forces every permission to be a deliberate decision, written down once, instead of discovered by testing what an admin account happens to be able to click.

## Input

**Works best with:** The name of the system and the roles that already exist or are anticipated (even informally - "there's regular users and then there's us").
**Also valuable:** Any compliance requirements (SOC 2, PCI-DSS, GDPR), known sensitive actions (refunds, data export, user impersonation), and whether multiple organizations/tenants share the system.

**Example invocation:** `Define the access control specification for our project-management SaaS. Roles so far: workspace owner, admin, regular member, and a guest role with view-only access. We also have an internal support team that needs to see customer data to help with tickets.`

## Key Concepts

### Role-Based Access Control (RBAC)
Define roles as named bundles of permissions, and assign roles to users - never assign individual permissions directly to a user. This keeps the system auditable: "what can an Admin do" has one answer, not one answer per admin.

### Principle of Least Privilege
Every role gets the minimum permissions required for its purpose, not the maximum that seems convenient. A support role that needs to view account data to help with tickets does not also need permission to change billing - even if the same person happens to also hold a role that can.

### Permission Matrix
The core artifact: a table of every role against every protected action/resource, with an explicit `Allow`/`Deny` for each cell. No cell should be left undecided - an undecided permission becomes a bug (either a silent block or a silent hole) the first time someone hits it.

### Separation of Duties
For sufficiently sensitive actions (e.g., approving a large refund, deleting an organization), require two different people - one to propose, one to approve - so a single compromised or malicious account cannot act alone.

### Admin Action Audit Logging
Every privileged action must be logged with: who performed it, what it was, what/who it affected, and when - immutable and readable by someone other than the actor. This is what turns "we think an admin did X" into "we can prove admin Y did X at this timestamp."

### Break-Glass / Emergency Access
Define a documented, logged, alerting procedure for emergency access outside the normal flow (e.g., the on-call engineer needs temporary elevated access at 3 AM to fix a production issue). Undocumented emergency access is indistinguishable from a compromise after the fact.

### Attribute-Based Access Control (ABAC)
RBAC covers most cases, but some permissions depend on context, not just role. ABAC evaluates attributes such as:
- **Resource attributes:** "Users can edit only their own posts" (ownership)
- **Environmental attributes:** "Admin panel access is restricted to office IP ranges" (context)
- **Temporal attributes:** "Finance team can approve invoices only during business hours" (time)
- **User attributes:** "Users with verified email can access premium features" (user state)

When specifying ABAC rules, define: the attribute, the condition, and the resource/action it gates. ABAC complements RBAC — use RBAC for coarse-grained role assignments and ABAC for fine-grained, context-dependent rules.

### API vs UI Enforcement
Access control must be enforced at BOTH the API layer and the UI layer — never assume that hiding a button means the action is protected:
- **API enforcement (mandatory):** Every API endpoint must validate the caller's permissions before executing. This is the true security boundary.
- **UI enforcement (usability):** Hide or disable UI elements the user cannot access. This prevents confusion and accidental permission-denied errors, but is NOT a security measure.
- **Consistency rule:** If the API allows an action, the UI must present it. If the API denies an action, the UI must not offer it. Mismatches create either security holes or user frustration.

### Role Inheritance
When roles form a hierarchy, define inheritance explicitly:
- **Inheritance model:** Does a higher role inherit all permissions of lower roles? (e.g., Admin inherits all Member permissions, plus additional admin-only permissions)
- **Override rules:** Can a higher role's inherited permission be restricted? (e.g., an Admin cannot do something a Member can, in rare cases)
- **Depth limit:** How deep can inheritance go? Deep hierarchies (5+ levels) become unmanageable — recommend flattening to 2-3 levels maximum.
- **Conflict resolution:** When inherited permissions conflict with explicit deny, explicit deny wins (deny-overrides).

### Permission Caching and Invalidation
Caching permissions improves performance but creates staleness risk:
- **Cache strategy:** Where are permissions cached? (in-memory per request, Redis, JWT claims)
- **TTL:** How long is a cached permission valid? (e.g., 5 minutes, until next request, until session end)
- **Invalidation triggers:** What events force cache refresh? (role change, permission update, organization membership change)
- **Propagation delay:** What is the maximum time a permission change takes to take effect? Document this — it is a known security window.
- **Revocation urgency:** For high-security actions (e.g., revoking a compromised admin), define an emergency cache-bypass mechanism.

### Multi-Tenant Isolation
When multiple organizations share a system, enforce strict data isolation:
- **Tenant boundary:** Every data query must be scoped to the tenant. No query should return data across tenant boundaries.
- **Admin isolation:** A tenant admin can only see and manage their own tenant's users and data — never another tenant's.
- **Platform admin:** The platform-level super-admin can see across tenants but every cross-tenant action is logged and requires justification.
- **Shared resources:** If any resource is shared across tenants (e.g., a template library), explicitly define what is shared and what is isolated.
- **Testing requirement:** Include a test case that attempts cross-tenant data access and verifies it is blocked.

### Service-to-Service Auth (Machine Identities)
Not all access is by humans. Define how services authenticate to each other:
- **Machine identity model:** How are services identified? (mTLS certificates, API keys, OAuth2 client credentials, service mesh identity)
- **Permission scope:** What can each service do? Define a permission matrix for services, same as for human roles.
- **Rotation policy:** How often are service credentials rotated? What is the process?
- **Audit logging:** Service-to-service calls must be logged with the same rigor as human actions — who (service ID), what (action), when, and what it affected.

### Permission Testing Strategy
Access control is only as good as its verification:
- **Positive tests:** For each role, verify every allowed action succeeds.
- **Negative tests:** For each role, verify every denied action returns the correct error (403 Forbidden, not 404 or 500).
- **Privilege escalation tests:** Attempt to perform actions above the current role. Verify denial.
- **Boundary tests:** Test at the edges — what happens when a role is changed while a user is mid-action? What happens when a permission is revoked during an active session?
- **Matrix completeness test:** Automatically verify that every cell in the permission matrix has a corresponding test case.

### Document Length

Target length: **5-8 pages** (excluding appendices).

Shorter is better than longer. If the document exceeds the target, check for:
- Redundant content that can be cut
- Overly verbose explanations
- Content that belongs in a separate reference document
- Material the agent already knows (don't explain what HTTP is)

If the document is significantly shorter than the target, check for:
- Missing sections
- Insufficient detail in critical areas
- Unaddressed edge cases

### Conflict Resolution

When your analysis conflicts with the user's stated preference:

1. **Present both positions** — show your analysis and their preference side by side
2. **Explain the trade-off** — what are the consequences of each choice?
3. **Recommend with reasoning** — state your recommendation and why
4. **Respect the user's decision** — they own the final call
5. **Document the decision** — record it as an `[owner-specified]` override with reasoning

## Application

### Phase 1: Socratic Clarification & Brainstorming (Mandatory Interview)

**Interview Mechanism:** Use tool calls (e.g., `AskUserQuestion`) to present questions — do NOT ask inline in the conversation. The user selects from options rather than typing responses. One question per tool call, multiple-choice options preferred, with "I don't know, you decide" as an escape hatch.

**Context Loading:** Before asking ANY questions, read ALL prior documents in `.engineering-docs/` to extract already-known information. Look for:
- Team size, budget, timeline (from business-plan)
- Tech stack, hosting (from system-architecture)
- Target users, JTBD (from user-personas)
- Constraints, regulatory requirements (from business-plan)
- Scope, features (from technical-specification)

**If information exists in a prior document, USE IT — do not re-ask.**

**Maximum 2-3 questions per skill.** Only ask about:
- Skill-specific details not covered in prior documents
- Technical decisions that affect this specific document
- Clarifications on ambiguous requirements

Ask questions to resolve:
1. **Sensitive actions**: What actions, if misused, would cause the most damage (data export, refunds, impersonation, deletion, permission changes themselves)?
2. **Multi-tenancy**: Does this system serve multiple separate organizations/customers who must never see each other's data, even to admins of the underlying platform?

*Wait for the user's response to these questions before drafting the final specification.*

### Phase 2: Role Inventory (40-60 min)
Enumerate every role, including any implicit ones (system/service accounts, support staff, platform-level super-admins).

### Phase 3: Resource and Action Inventory (60-90 min)
List every protected resource and action in the system that access control must govern.

### Phase 4: Permission Matrix (1.5-2 hrs)
Build the complete role x action matrix. Leave no cell undecided. Apply least privilege - justify any broad grant.

### Phase 5: Separation of Duties and Sensitive Actions (40-60 min)
Identify actions requiring dual approval or additional verification, and specify the approval flow.

### Phase 6: Audit Logging Specification (40-60 min)
Define exactly what gets logged for privileged actions, retention period, and who can read the log (and who explicitly cannot, to prevent tampering by the actor themselves).

### Phase 7: Break-Glass Procedure (30-45 min)
Define the emergency access process: who can invoke it, what triggers automatic alerting when it's used, and the mandatory post-use review.

### Phase 8: Revision (After User Review)

If the user requests changes after reviewing the specification:

1. **Read the user's feedback carefully** — understand what they want changed
2. **Check for conflicts** — does the requested change violate least privilege, create permission gaps, or break separation of duties?
3. **Apply changes** — update the document, cascading changes through the permission matrix, audit logging, and break-glass procedure
4. **Re-run consistency check** — verify zero blank cells in the permission matrix and all sensitive actions still have dual-approval requirements
5. **Update metadata** — set `last_updated` to today's date
6. **Confirm with user** — show the changes and get approval

## Gotchas

- **Leaving permission matrix cells blank or implicit.** An undecided permission is not "deny by default" - it is a bug that will surface as either a silent block or a silent security hole. Every cell must be explicitly `Allow` or `Deny`.
- **Granting permissions directly to users instead of roles.** This defeats the purpose of RBAC and makes the system unauditable. Always assign permissions to roles, then assign roles to users.
- **Skipping audit logging for "read-only" actions.** Accessing sensitive data (viewing PII, exporting records, impersonating users) is a privileged action even if it does not mutate data. Log it.
- **Defining break-glass access without automatic alerting or expiry.** Emergency access that does not auto-revoke and does not alert is just a backdoor. Every break-glass grant must have a time limit and a notification.
- **Ignoring separation of duties for destructive actions.** Letting a single admin delete an organization or issue large refunds without a second approver creates a single point of compromise. Require dual approval for irreversible, high-impact actions.

## Handoff

**Reads from:**
- `4-technical-specification.md` — functional requirements, user roles
- `7-system-architecture.md` — system components, services, trust zones
- `8-database-design-document.md` — data entities that permissions govern
- `9-api-design-document.md` — API actions that require access control

**Feeds into:**
- `12-security-threat-model.md` — privilege model and trust boundaries for threat analysis
- `14-technical-blueprint.md` — access control requirements for feature designs
- `15-implementation-plan.md` — auth/permissions as foundation phase

## Quality Gate

Before marking this document as `final`, verify:
- [ ] Every role in the inventory has a clear description and defined assignment criteria
- [ ] The permission matrix has zero blank cells - every role/action intersection is explicitly `Allow` or `Deny`
- [ ] Every sensitive action (data export, impersonation, deletion, financial operations) is listed in the Separation of Duties table
- [ ] Audit logging specification covers who, what, when, and target for every privileged action, and specifies who cannot alter logs
- [ ] Break-glass procedure includes trigger conditions, invocation authority, auto-expiry, alerting, and mandatory post-use review

## Next Steps

After this document is complete, proceed to:
- **`security-threat-model`** — threat-model the access control surface and privilege escalation paths
- **`technical-blueprint`** — design the implementation of the permission system
- Or invoke `using-engineering-docs` to continue the pipeline