In Ktor, authenticate {} proves identity — how do you enforce role checks per route?

## Why there is nothing to configure Ktor's `Authentication` plugin produces a principal and stops. It has no concept of roles, scopes or permissions, and there is no annotation processor to scan. That is deliberate — Ktor is assembled from explicit pieces — but it means every Ktor codebase invents its authorization layer, and interviewers ask this to see which of the three shapes you have actually built. ## Shape 1: inline checks ``` get("/admin/users") { val roles = call.principal<JWTPrincipal>()?.payload?.getClaim("roles")?.asList(String::class.java).orEmpty() if ("ADMIN" !in roles) return@get call.respond(HttpStatusCode.Forbidden) ... } ``` Honest and obvious, and fine for one or two endpoints. It degrades badly: the rule is copied, claim parsing is duplicated, and a new endpoint added by someone in a hurry simply has no check. Nothing in the type system or the build notices. ## Shape 2: a route-scoped plugin (the idiomatic answer) `createRouteScopedPlugin` builds a plugin you install on a specific route subtree rather than on the whole application. Combined with the `AuthenticationChecked` hook — which fires after the authentication providers have run and before the handler — it gives a clean interception point: ``` class RoleConfig { var required: Set<String> = emptySet() } val RequireRole = createRouteScopedPlugin("RequireRole", ::RoleConfig) { val required = pluginConfig.required on(AuthenticationChecked) { call -> val roles = call.principal<JWTPrincipal>() ?.payload?.getClaim("roles")?.asList(String::class.java).orEmpty() if (required.none { it in roles }) call.respond(HttpStatusCode.Forbidden) } } ``` Installed inside an authenticated subtree, `install(RequireRole) { required = setOf("ADMIN") }` now guards every route beneath it. The claim parsing lives in one place, the policy is declarative at the route, and adding an endpoint to that subtree inherits the guard automatically. Wrapping the install in a small extension function — `fun Route.requireRole(vararg roles: String, build: Route.() -> Unit)` that creates a child route, installs the plugin and applies `build` — makes call sites read almost like an annotation. Ordering matters: the plugin must be installed inside the `authenticate` block, otherwise the hook runs where no principal has been produced and every request looks unauthorized. ## Shape 3: authorization in the domain layer Route-level role checks cover "may this kind of user call this endpoint". They cannot express "may this user see *this* record", which is the more dangerous class of bug: the endpoint is allowed, the object is not theirs. That check belongs where the object is loaded — the query is scoped by the caller's tenant or ownership rather than filtered afterwards. A senior answer says both layers exist and that the coarse route guard does not replace the fine-grained one. ## Status codes - **401** — the caller is not authenticated. This is what the provider's challenge produces. - **403** — the caller is authenticated and still refused. This is what your authorization layer produces. Returning 401 for a permission failure sends clients into pointless re-login loops. Deliberately returning 404 to hide the existence of a resource is a legitimate choice for some products, but it must be a decision recorded in the contract, not an accident. ## Fail closed, and prove it Because both authentication and authorization are structural in Ktor, the default state of a newly added route is *unprotected*. Two habits contain that: 1. **One authenticated subtree** with guarded sub-subtrees, rather than `authenticate` blocks scattered through many files. New routes then land inside protection by default. 2. **A route-inventory test.** Enumerate the application's registered routes, call each without credentials and with an under-privileged principal, and assert 401/403 except for an explicit public allowlist. This is the closest Ktor gets to the guarantee an annotation-scanning framework provides, and it is the answer that distinguishes someone who has operated a Ktor service from someone who has read the docs. ## Where the roles come from Roles usually arrive as a claim on a verified token, or from the session's user record. Extract them once — in the provider's `validate` block, into a principal type of your own that already carries `userId`, `tenantId` and `roles` — so the authorization layer reads typed fields instead of re-parsing claims at every check.