Lesson 16 · Senior auth & authz

Debugging auth/authz failures under pressure

A senior debugging frame for auth problems: identify the broken layer first, then ask the shortest question that can falsify it.

Your win: debug authentication and authorization failures systematically instead of bouncing randomly between tokens, roles, handlers, and SQL.

In plain English Plain English: most auth bugs are not “security is broken.” They are one false assumption at one layer of the chain.

Why auth bugs feel more chaotic than they really are

A request can fail because the token is missing, the issuer is wrong, the role gate denies it, the permission lookup resolves no locations, the handler enforces ownership, or RLS filters the row away. From the outside, many of these collapse into the same human complaint: “I logged in, but it still doesn’t work.”

That is why auth debugging often feels emotionally noisier than other debugging. The failure looks small from the outside but the chain behind it is long.

The debugging order Check token presence and verification → claims/context → role gate → permission/location resolution → service ownership logic → repo query shape → RLS/session variables.

Why this order helps

If the JWT never verified, later authorization reasoning is wasted. If the role gate failed, location permission debugging is a distraction. If the row vanished only at query time, RLS may be doing exactly what it was designed to do.

The earlier auth lessons were strongest when they made one structural idea feel obvious. The structural idea here is simple: do not investigate the wrong layer for too long.

The shortest useful question at each layer

Instead of asking “why is auth broken?”, ask a smaller question that can kill one branch fast.

Verification: did we establish identity at all?
Claims/context: do the user, group, and tenant values look right?
Role gate: did the method deny this role immediately?
Permission scope: did the capability resolve at the expected location?
Service logic: is the handler using caller-owned identity or trusting request input?
Repo/RLS: did the row disappear because filters or policies did their job?

Backend use case This is the lesson you want when a user says “I can log in but still can’t see X,” or when a service suddenly starts returning empty data after a security-related change.

Common mistake Jumping straight to the business handler before deciding whether the failure is identity, coarse authorization, scoped authorization, or database filtering.

Use the repo map as a debug map

The same files that teach the auth chain also define the fastest checkpoints when the chain breaks.

→ Repo auth map
→ internal/usermgmt/pkg/interceptors/auth.go

Why this lesson tends to stick

People remember this lesson because it turns a vague security problem into a sequence. That is the same teaching move the best earlier auth lessons use: replace abstract fear with a walkable map.

Check yourself (from memory)

Q1. The best first move in an auth debug session is usually to…

Layer identification turns a vague access failure into a short diagnostic path.

What is the senior debug order for auth/authz failures?

recall, then click to reveal

Token verification, then claims/context, then role gate, then permission/location resolution, then service ownership logic, then repo query shape, then RLS/session-variable behavior.

Want a printable auth-debug checklist for live incidents or PR reviews? Ask me.

Sources. Repo auth map; interceptor and RLS files.