Turning an IdP identity into an application principal — the enrichClaims DB-backed seam and its rejection codes, why request validation belongs to protovalidate instead, app-owned provisioning via a public Register RPC, why binding an invitation or membership by email must require devidp.User.EmailVerified, and declaring an owner column so forge fails a build that ships unscoped.
Installs into .claude/skills of the current project.
Sponsors
SSkills DirectorySkills Directory
Know which skills are safe — weekly.
SSkills DirectorySkills Directory
Is that skill safe to install?
Are you the author of Authorization?
Add the live security badge to your README. It updates with every re-scan.
[](https://www.skillsdirectory.com/skills/reliant-labs-authorization)
---
name: authorization
description: Turning an IdP identity into an application principal — the enrichClaims DB-backed seam and its rejection codes, why request validation belongs to protovalidate instead, app-owned provisioning via a public Register RPC, why binding an invitation or membership by email must require devidp.User.EmailVerified, and declaring an owner column so forge fails a build that ships unscoped.
---
# From identity to principal
The token says who the caller is; your database says what they are. `enrichClaims(ctx, claims)` in `pkg/middleware/middleware.go` runs AFTER validation and BEFORE any handler sees the claims — the one chokepoint where an IdP identity becomes an application principal. Hydrate by `claims.Subject`/`UserID`, the stable IdP identifier, never by email (users change it, and two IdPs can assert the same one):
```go
func enrichClaims(ctx context.Context, claims *Claims) (*Claims, error) {
row, err := userStore.BySubject(ctx, claims.UserID)
if errors.Is(err, sql.ErrNoRows) {
// Authenticated by the IdP but unknown here — see Provisioning below.
return nil, connect.NewError(connect.CodeUnauthenticated, errors.New("no local account"))
}
if err != nil { return nil, err } // a DB outage is not a 401
if row.SuspendedAt != nil {
return nil, connect.NewError(connect.CodePermissionDenied, errors.New("account suspended"))
}
claims.OrgID, claims.Roles = row.OrgID, row.Roles
return claims, nil
}
```
**`Enrich` can REJECT, and it is the earliest place you can.** Return a `connect.Error` and its code is preserved verbatim (`PermissionDenied` stays `PermissionDenied`); return a plain error and it becomes `Unauthenticated` wrapped as `identity enrichment failed: …`. Rejecting here stops the request before any handler runs, which is right for whole-principal facts (suspended, no local account, org disabled) and wrong for per-resource decisions — "may this user edit THAT row" needs the row, so it belongs in the handler.
Enrichment runs on every authenticated request, so a query here is on the hot path: index the subject lookup, and cache if it shows up in traces.
**The first sign-in of an invited person is the one time email matters.** The person has a subject the app has never seen and an invitation keyed by address, so `enrichClaims` binds that subject to the invitation once and uses the subject from then on. A managed identity's access token (Zitadel) carries **no `email`**: only `sub`, the audience and roles. The scaffolded `SetupAuth` (`internal/app/auth.go`) therefore installs `authenticator.UseUserInfo(auth.NewUserInfo(...))`, which fills `claims.Email` from the issuer's OIDC userinfo endpoint. It fills only a **verified** address (`email_verified`), looks up only tokens whose `iss` is the configured issuer (a subject is unique only within its issuer), sends the access token over HTTPS only (plain HTTP to a loopback dev issuer excepted, redirects included), caches the answer per subject for five minutes, and leaves `Email` empty instead of failing the request when the lookup fails. A token that carries its own `email` is left as it is, and API keys are never looked up. A project scaffolded before this existed can add the same lines after `auth.NewAuthenticator(validator.Validate)`. Bind on `claims.Email` only when no row has the subject yet; after that, the subject is the key.
**Enrichment that reads the database is a component, not an edit to `enrichClaims`.** The function above is a package function with no `Deps`, so it has no way to reach a store. A package that does database I/O must be a composed component: `requirecontract` refuses a plain helper, and `//forge:exclude-contract` is refused for outbound I/O. So the seam is a component:
1. `forge scaffold package membership`, then put the method on its `Service` interface and implement it over the store:
```go
// internal/membership/contract.go
type Service interface {
EnrichClaims(ctx context.Context, claims *auth.Claims) (*auth.Claims, error)
}
```
`middleware.Claims` is an alias of `github.com/reliant-labs/forge/pkg/auth.Claims`, so the package does not need to import `pkg/middleware`.
2. Run `forge generate`. `UserAuthDeps.Enrich` (`internal/app/providers.go`) is a `// forge:optional-dep` field of type `middleware.ClaimsEnricher`. The graph fills it with the one component whose value implements that interface, and `NewAuthInterceptor` uses `AuthDeps.Enrich` in place of `enrichClaims`. You register nothing, and the component's `Deps` brings the database the way every other component's does. With no such component the field stays nil and `enrichClaims` runs. If two components implement it, generate stops with an ambiguity error; settle it by naming one in `compose.go`.
Projects scaffolded before this have no `ClaimsEnricher` in `pkg/middleware/middleware.go`. Add the interface, the `Enrich ClaimsEnricher` field on `AuthDeps`, and the `deps.Enrich` branch in `NewAuthInterceptor` by hand, then wire `Enrich: d.Enrich` in `NewUserAuth`.
**Request VALIDATION is not `Enrich`'s job.** Field-level input checking is already handled, separately and earlier in the chain, by protovalidate from the `buf.validate` rules on your proto messages:
```proto
string email = 1 [(buf.validate.field).string.email = true];
int32 qty = 2 [(buf.validate.field).int32.gte = 1];
```
That interceptor rejects a malformed request with `InvalidArgument` before your handler runs. Putting field checks in `enrichClaims` would run them on requests that have none of those fields and report a bad email as an authentication failure.
## Provisioning is application code
Your IdP authenticates; it does not populate your `users` table. That first-contact write is yours, and the honest place for it is a **public** RPC the client calls once with an IdP-issued token in hand:
```proto
rpc Register(RegisterRequest) returns (RegisterResponse) {
option (forge.v1.method) = { auth_required: false };
}
```
`auth_required: false` here does NOT mean unauthenticated — it means the allow-list lets the call through so the handler can do the credential work itself, because `enrichClaims` would reject the caller for having no local row and the request would never arrive. The handler validates the presented token (the same validator `SetupAuth` built), takes the **`sub` the IdP asserted**, and inserts on that. Trust the `sub` from the verified token; never a `user_id` from the request body, which is a caller-supplied string and an account-takeover primitive. Make the insert idempotent on `sub` — a retried or double-clicked registration must not create a second account.
## Binding by email requires a verified address
The common invite pattern — an owner adds `alice@example.com` to a tenant, and the first account that signs in with that address claims the membership — is an **account-takeover primitive unless the address is verified**. Whoever registers `alice@example.com` first gets Alice's membership, because the address on an account is whatever was typed when it was created. Public sign-up (`auth_self_signup`, off outside development) creates exactly such accounts: unverified, and signed in immediately.
So every place that binds something to a user BY EMAIL — accepting an invitation, attaching a tenant membership, merging a pre-created record — must first ask the issuer whether this account's address is verified, by the token's `sub`, and refuse otherwise:
```go
// Resolve the caller by the IdP's stable id, never by an email the request
// or the token carries. idp is a devidp.Client built like the broker's.
user, err := idp.FindUserByID(ctx, claims.Subject)
if err != nil {
return nil, err // ErrUserNotFound is a machine account or a deleted user
}
if !user.EmailVerified {
return nil, connect.NewError(connect.CodePermissionDenied,
errors.New("verify your email address before accepting an invitation"))
}
invite, err := invites.PendingFor(ctx, tenantID, user.Email)
```
- Read `EmailVerified` from the issuer at bind time. A boolean you cached at sign-up goes stale the moment the person changes their address.
- Bind ONCE, then key on `sub`. After the membership row holds the subject, later requests hydrate by `sub` (above), and the email is only display data.
- An account created by an invitation (`forge cloud identity invite`, `IdentityService.InviteUser`) or a dev seed is verified by whoever created it. One created through `POST /auth/register` outside development is not, until its owner verifies it.
## Authenticated is not scoped
`auth_required: true` gets you a caller. It does not get you *their* rows. A
generated CRUD delegation reads no claims at all, so the interceptor proves the
caller is signed in and the handler then serves them everyone's data identically.
That is the gap, and it is not hypothetical: a measured downstream app shipped 63
of 74 authenticated RPCs this way, where any authenticated user could read,
update, delete and create rows belonging to every other one.
Forge diagnosed it exactly — and exited 0, because the `unscoped_auth` audit
category was advisory. It was advisory for a real reason: a fresh scaffold is
entirely unscoped by construction, so failing on "unscoped" would mean forge's
own output could never pass forge's own gate.
The way out is that **"unscoped" and "unsafe" are different claims**, and only
you can tell forge which one applies. Declare the owner column and the gate
arms:
```sql
COMMENT ON COLUMN crews.company_id IS 'forge:owner';
```
- **No table declares it** → `unscoped_auth` stays `warn`, exit 0. Fresh
scaffolds and apps whose rows belong to nobody in particular are untouched, and the finding is
still reported.
- **A table declares it** → an authenticated RPC over *that entity* that never
resolves the caller is an `error`, and `forge project audit` fails. Declaring
an owner on `crews` does not fail an unscoped RPC over a global product
catalog; the gate arms per table.
Forge ships no ownership of its own and will not inject a `WHERE` clause at runtime for
you, because only your app knows how a caller's claims map onto that column's
values — a direct user id, a company id read from a membership table, an org
resolved from a subdomain. The marker is a declaration, and what it buys is that
forge stops letting you ship the handler unfinished.
### Scoping a generated CRUD op
**Where the wrapper comes from depends on when you declared the owner column.**
Declare it on the proto field at birth and forge writes it for you:
```proto
// forge:entity
message Crew {
string id = 1;
// forge:read-only forge:owner
string company_id = 2;
}
```
`forge scaffold` births the table with `COMMENT ON COLUMN crews.company_id IS
'forge:owner'` and only then generates `handlers_crud.go`, so the file is born
scoped. `forge:read-only` keeps the column off the Create request; the wrapper
stamps it from the caller, so it needs no `forge:fill=handler`. On `id`
(`string id = 1; // forge:owner`) the marker declares a table owned by itself,
and its Update predicates on the key without stamping it.
The handler file is scaffold-once: forge writes
`internal/handlers/<service>/handlers_crud.go` when it does not yet exist, and
after that only ever appends blocks for RPCs the file has no method for. Its own
header says so — *"yours: scaffolded once, never touched again"*. So there are
two cases:
- **The owner column was declared before that file was born** (the table and its
marker existed at the entity's first `forge generate`). Forge scaffolds the
whole wrapper — the `GetUser` call, the op-seam override, the column named in
the predicate — leaving one placeholder expression.
- **The owner column was declared later** — a `COMMENT ON COLUMN` in a
migration written after the handlers existed. The wrapper is **not**
written, and re-running `forge generate` will not add it: the file is already
there, and the method is already in it. This is not a bug you can generate your
way out of.
In the second case `forge project audit` hands you the code instead. The gating
finding carries the whole wrapper for each failing RPC, rendered from the same
template the scaffolder uses, and prints it under the failure:
> ── DocumentsService.GetDocument — paste into internal/handlers/documents/handlers_crud.go ──
>
> the `GetUser` call, `owner := claims.UserID`, and the `op.Fetch` override
> carrying `orm.WhereEq("org_id", owner)`
Paste it over the existing delegation for that method. `forge project audit
--json` carries the same text per finding under
`details.owner_scoped_unscoped_rpcs[].remediation`, plus a
`details.owner_scoping_hint` explaining the scaffold-once rule above.
Either way the placeholder is the same, and it is the only thing left to do:
```go
// FORGE_SCAFFOLD: `claims.UserID` is forge's placeholder for the value of
// Crew.company_id that belongs to this caller. Only your app knows that
// mapping — replace the expression, then remove this comment.
owner := claims.UserID
```
Replace that expression with your real mapping (a direct user id, an org id read
from a membership table, an org resolved from a subdomain) and delete the marker.
The marker fails `forge lint --scaffolds` and `forge project audit` until you do,
so the gate cannot be satisfied by ignoring it — but satisfying it is one line,
not ten.
**Wrappers appended later follow their siblings.** Once you have replaced the
placeholder, a CRUD RPC that `forge generate` appends to the same
`handlers_crud.go` (a new rpc, or a hand-written method you deleted) reads its
owner from the resolver the file's other wrappers on that column already call
— `owner, err := tenancy.TenantID(ctx)`, not the placeholder. A read copies the
reads and a write the writes, so a write behind `tenancy.RequireAdmin` does not
leak onto a List. A column the file never scopes borrows the project's other
`handlers_crud.go` files. A new entity borrows other entities' wrappers on
the column only when every one of them, reads and writes, agrees on one
resolver. When the siblings disagree, or read the owner from
something forge cannot trace, the appended wrapper calls
`FORGE_TODO_choose_<column>_resolver(ctx)`, declared nowhere, so the build
fails on the line you must decide rather than shipping a guessed principal.
`forge lint` (`forgeconv-crud-owner-resolver`) flags any wrapper whose owner
source disagrees with its siblings'.
One gap worth knowing: a **custom** RPC (`TransferOrder`, `ArchiveWorkspace`)
delegates to no generated op, so there is no `Fetch`/`Filters`/`Persist` seam to
wrap and forge offers no wrapper for it. Such an RPC is reported as a warning and
the scoping is yours to write from scratch.
What the wrapper looks like, per shape:
```go
// List — the predicate goes in the QUERY, never on the returned page. The
// response's total_count comes from a COUNT over these same opts, so
// post-filtering a page reports rows the caller cannot see.
filters := op.Filters // nil when the RPC declares no filter fields
op.Filters = func(ctx context.Context, r *pb.ListCrewsRequest) ([]orm.QueryOption, error) {
var opts []orm.QueryOption
if filters != nil {
var err error
if opts, err = filters(ctx, r); err != nil {
return nil, err
}
}
return append(opts, orm.WhereEq("company_id", owner)), nil
}
// Get — passed INTO the fetch as a query option, not compared after it. A row
// that is not this caller's is never read, and reports NotFound exactly as an
// unknown id does; a distinguishable "exists but is not yours" tells an
// attacker which ids are real.
fetch := op.Fetch
op.Fetch = func(ctx context.Context, id string, opts ...orm.QueryOption) (*db.Crew, error) {
return fetch(ctx, id, append(opts, orm.WhereEq("company_id", owner))...)
}
```
`Delete` mirrors `Get`. `Create` stamps the column from the caller instead of
filtering — never off the wire, or anyone can file a row under anyone else's
name. `Update` gets both halves: the stamp keeps the written row on the same
owner, and the predicate is checked against the **stored** row, so a caller
cannot take ownership by rewriting `company_id` in the request they send.
Because `Filters` returns an error, a closure that cannot determine the scope can
**fail closed**. Return `svcerr.PermissionDenied(...)` rather than returning no
filter — a missing filter is not "no restriction", it is every row.
### When an RPC really is global
An admin console list, a lookup already keyed by something caller-scoped, an RPC
whose scoping lives in a row-level-security policy — these are correct, and must
not be reported forever. Say so in code, above the handler:
```go
// forge:auth-unscoped-ok: operator console; every caller of this RPC is an
// admin, so there is no narrower scope to apply.
func (s *Service) ListAllCrews(...)
```
This suppresses the **error**, not just the warning. The reason after the colon
is mandatory — a bare directive is the unfalsifiable comment the whole check
exists to replace, and it will not silence anything. It lives next to the code so
it shows up in the diff that introduces it, where a reviewer can disagree.
### When your project resolves the caller through its own package
The audit counts a handler as resolving the caller when it reaches forge's seam,
`middleware.GetUser` (or `ClaimsFromContext`). A project that adopted forge with
its own auth package resolves the caller elsewhere, and every handler would read
as unscoped. Mark the accessors instead of suppressing the findings:
```go
// GetUserIDFromContext returns the signed-in user's id.
//
//forge:resolves-caller
func GetUserIDFromContext(ctx context.Context) (string, bool)
```
A handler that calls a marked function, through the import that binds its
package in that file or through a helper in its own package, resolves the
caller. Mark package-level functions only, because a call site does not name a
method's receiver type. The audit reports a marker on a method as ignored, and
lists what it found under `caller_resolvers`.