Authentication and permissions, done once

Three rebuilds, and only the last one hurts

The first version is email and password with an is_admin column, and it is the correct thing to build. The second arrives when a buyer's security review asks for single sign-on, and it is annoying but bounded, because authentication lives behind one door. The third is the one that costs a quarter. It arrives when someone asks whether a manager can see their reports' records but not edit them, whether a customer can share one project with an outside auditor, and whether a support engineer can act on behalf of a user without becoming an administrator. By then there are four hundred permission checks scattered through the codebase, no two written the same way, and nobody can answer "who can see this record" without reading code.

The distinction that prevents the third rebuild is old and still gets collapsed: authentication answers who you are, authorization answers what you may do. They have opposite economics. Authentication is a solved, commoditized problem where building your own is nearly always a mistake. Authorization is specific to your domain, cannot be bought outright, and is where the design effort belongs. Teams routinely reverse this, writing their own password reset flow and then expressing a rich permission model as a string column with three values.

What follows is what we would do at the start of a product, and what we do when we are handed a codebase where the third rebuild has already become unavoidable.

Buy authentication. All of it.

Password storage, reset flows, second factors, device sessions, account recovery, brute-force protection, enumeration resistance, breach notification: this is a large surface with well-understood failure modes and no competitive value. Use an identity provider or an established library, and use standard protocols. For business software that means an authorization-code flow with the current recommended proof-key protections, tokens verified against published keys, and no shortcuts for the mobile client.

Two things are worth insisting on when you choose. First, that you can support several identity sources at once. A real product ends up with employees on your own directory, customers on theirs, and a handful of accounts that predate all of it. Second, that user records in your database are keyed by a stable internal identifier rather than by email address. Email addresses change, get reassigned after someone leaves, and differ in case and in plus-addressing. A permission model keyed on email is a data-integrity incident waiting for a marriage or an acquisition.

The one authentication decision genuinely worth your own thought is session lifetime, because it is a tradeoff between how often people are interrupted and how quickly a revoked access actually stops working. Say the numbers out loud rather than accepting a default.

Session mechanism	Fits	Revocation behavior	Cost
Server-side session, cookie reference	Web applications with one backend	Immediate. Delete the record and it is over	A session store on the request path
Short signed token plus refresh	APIs and clients across several services	Delayed by token lifetime, typically 5–15 minutes	Refresh flow, rotation, and reuse detection
Long-lived signed token	Convenient, and hard to undo	Effectively none until it expires	Looks free, then a deny list appears anyway
Opaque token with introspection	Sensitive actions, machine clients	Immediate	A network call per validation, or a short cache

Most products land on short signed tokens with rotating refresh tokens, and that is reasonable if you accept the consequence in writing: when access is revoked, it takes up to the token lifetime to bite. If some action must revoke instantly — suspending an account, removing a departing employee — that path needs a live check rather than a cached claim. Deciding which actions those are is a five-minute conversation that saves an ugly one later.

Three authorization models, and how to tell which one you need

Almost every access question in application software is one of three shapes, and choosing the wrong shape is what forces the rebuild.

Roles. Permission follows a named role: admin, editor, viewer. Simple, easy to explain, and sufficient for a surprising number of products. It fails the first time the answer depends on the specific record rather than the person, which is the moment somebody says "editors should be able to edit their own team's projects, not everyone's."

Attributes. Permission is computed from properties of the user, the resource and the context: department, classification of the record, time of day, network. Expressive, and it fits rules that come from policy rather than from structure. The cost is that the rules are code-like, and asking "who can see this record" means evaluating the policy against every candidate user rather than looking something up.

Relationships. Permission follows a graph: this user is an owner of this folder, this folder is a parent of this document, therefore this user may read the document. This is the model behind most collaborative software, and it is the one that handles sharing, nesting and delegation naturally. It answers both directions well — what may this user see, and who can see this thing — which is precisely what the other two struggle with.

The practical advice: start with roles if your product genuinely has global roles, but write every check through an interface that could later be backed by something else. Adopt relationships when sharing, hierarchy or per-object collaboration appear in the requirements, because retrofitting a graph after four hundred inline checks is the expensive rebuild in question. Reach for attributes for the small set of contextual rules that genuinely are rules, and keep them few.

Centralize the decision, distribute the enforcement

The single most valuable structural property is that there is exactly one place in the codebase that decides whether an action is allowed, and it is called from everywhere. One function, one service, one library — the shape matters less than the singularity. Everything good follows from it: you can log every decision, test the model in isolation, change models without touching feature code, and answer questions about the system without reading it.

Enforcement, by contrast, has to happen at every entry point: HTTP handlers, background jobs, scheduled tasks, message consumers, administrative scripts, the reporting export. Background jobs are where we most often find gaps. A job runs as "the system," inherits everything, and quietly becomes a way for a request to reach data the requesting user could not have reached directly. Give jobs an explicit acting identity, and if the correct answer really is full access, make that an explicit privileged identity that is logged rather than an accident of context.

Do not enforce in the interface alone. Hiding a button is a courtesy to the user; it is not access control, and every so often somebody discovers that the underlying endpoint never checked. If your interface hides an action, the server must refuse it independently.

Machine identity, which is where the real keys leak

Service accounts and API keys usually get less attention than user login and are more often the cause of a bad afternoon. Four habits carry most of the value.

Give every service its own identity. A shared credential across five services means a rotation requires five coordinated deploys, so it never happens, so the key from 2023 is still live.

Scope keys narrowly and say so in the key. A key that can read one dataset is a smaller problem when it appears in a public repository than a key that can do anything. Prefix keys with an identifiable string so automated secret scanners can recognize them, and store only a hash of the key on your side so a database read does not hand over working credentials.

Make rotation routine before it is urgent. Support two live keys per identity so rotation is issue, deploy, revoke, with no downtime. If rotation requires a maintenance window, it will only ever happen during an incident, which is the worst time to be exercising an untested procedure.

Record last-used timestamps. The cheapest security work available is a monthly list of credentials nobody has used in ninety days. Most of them are safe to delete, and the ones that are not tell you something about your system you did not know.

Provisioning, and the offboarding gap

Access granted by hand is access removed by memory. The gap between someone leaving and their access ending is a number your company has, whether or not anyone has measured it, and in organizations without automated provisioning it is commonly measured in weeks.

Drive membership from groups in your directory rather than from per-user grants, so that a change in one place propagates. Support automated provisioning and deprovisioning from the identity provider for buyers who ask for it; for a business product this is a recurring requirement and it is easier to build once than to negotiate per deal. Then close the gaps automation misses: shared accounts, keys sitting on a laptop, the read-only database credential someone was given during an incident and everyone forgot.

Run an access review on a schedule, and make it cheap enough that it actually happens. A quarterly list of who has elevated access, sent to the person accountable for approving it, with a one-click removal, catches more than an annual exercise nobody has time for.

Audit, break-glass and impersonation

Log the decision, not just the request. An audit trail that records "user 12 called DELETE /records/91" is half a record; what you want later is "user 12 was permitted to delete record 91 because they hold the owner relationship on project 7." Decision logs turn an argument into a lookup, and they are how you debug a permission model that is telling users no.

Support engineers need to see what a customer sees, which means impersonation, which means the two rules that make it safe: every impersonated action is recorded as the operator acting as the user, and the mode is visually unmistakable to whoever is in it. Never let impersonation grant permissions the target user does not have — the point is to reproduce their view, not to become an administrator with a different name on the log line.

Break-glass access is the same discipline: a real path to elevated access when something is broken, with a reason recorded and a notification sent to someone else. The alternative is not that emergencies do not happen; it is that they are handled with a shared credential nobody logs.

Test the denials, because nobody does

Permission test suites are almost always positive: the admin can do the admin thing. The failures that matter are the other direction, and they are rarely tested at all. Write the negative cases explicitly. A user of one customer cannot read another customer's record by guessing an identifier. A viewer cannot reach the write endpoint directly. A revoked user's existing token stops working within the stated window. A background job triggered by a low-privilege user does not perform a high-privilege action. A list endpoint returns no rows the caller may not see, and its total count matches what it returned.

Two practices make this affordable. Write a fixture of users spanning every role and relationship shape, and run the whole endpoint surface against all of them, asserting the expected allow or deny for each pair. And add a test that fails when a new endpoint is registered without an authorization decision attached, so the enforcement gap is caught by continuous integration rather than by a customer. That single test is worth more than most of the suite, because the recurring bug is not a wrong rule, it is a missing check.

What "done once" actually means

Not that you never touch it again. It means the model can absorb new requirements without a migration: one decision point, one vocabulary for resources and actions, identity keyed stably, list queries filtered where the data lives, and enforcement at every entry point rather than in the interface. When a customer asks to share a single project with an outside auditor for thirty days, that should be a new relationship type and an expiry, not a design meeting.

If you are already past that point, the migration is doable and it has an order that works. Introduce the central decision function and route the easiest checks through it. Add decision logging immediately, because it tells you what the current rules actually are, which is invariably different from what anyone believes. Convert endpoints in groups, keeping the old check alongside the new one and logging where they disagree; the disagreements are your real specification. Then remove the old checks once the log is quiet. We have seen this take six to twelve weeks in a mid-size codebase, and the decision log is what makes it possible to do without breaking people.

What goes wrong, specifically

• Building password reset and second factors yourself while expressing permissions as one string column
• Keying users by email address, which changes, gets reassigned, and collides on case
• Permission checks inline in every handler, no two written the same way
• Enforcement in the interface only, with an endpoint that never checked
• Fetching all records and filtering in application code, which breaks pagination and gets slower monthly
• Background jobs running as the system, inheriting access the requesting user never had
• Impersonation that grants administrator rights instead of reproducing the user's view
• Only positive tests, so the missing check ships and a customer finds it

A six-week shape for getting this right

Step four is the one that makes the rest survivable. Running both checks and logging the disagreements turns a rewrite into a measurement, and the disagreements are almost always more interesting than anyone expected: rules nobody remembered, a role that was silently equivalent to another, an endpoint that had been open for a year.

Before you call it done

• Authentication is delegated to an identity provider or an established library
• Users are keyed by a stable internal identifier, never by email address
• Session and token lifetimes are chosen deliberately and written down
• Actions requiring immediate revocation use a live check, not a cached claim
• Exactly one decision point, called from every entry point including jobs
• List queries are filtered in the database, and the total count matches the rows
• Every decision is logged with the reason, not only the request
• Impersonation is logged, visually obvious, and grants no extra permissions
• Service credentials are per-service, scoped, rotatable without downtime, and report last use
• The test suite asserts denials, and CI fails on an endpoint with no decision attached

Bottom line

Spend almost nothing on authentication and almost everything on authorization. The parts that are hard to change later are the model, the singularity of the decision, and whether list queries can be filtered where the data lives. The parts that look intimidating — single sign-on, directory provisioning, second factors — are integrations with a known shape and a couple of weeks of work. Getting this proportion right at the start is worth roughly a quarter of engineering time later, and the tell that you got it wrong is simple: somebody asks who can see a record, and the honest answer requires reading the code.

Frequently asked questions