Lesson 4 · Authentication — who are you?

The auth interceptor

The checkpoint on every RPC: pull the token, verify it against the key set, and stamp the caller's identity onto the request context.

Your win: trace what the auth interceptor does on every request, explain how a token is verified against the JWKS, and describe the two "skip" lists — one that bypasses auth entirely, one that fakes a JWT for service-to-service calls.

One gate, every request

The token from Lesson 3 is presented in gRPC metadata under the key token. A single unary interceptor — early in every service's interceptor chain — checks it before any handler runs. This is gate ① of the map:

func (a *Auth) UnaryServerInterceptor(ctx, req, info, handler) (interface{}, error) {
    if a.skipAuthMethods[info.FullMethod] {              // ignoreAuthEndpoint → bypass entirely
        return handler(ctx, req)
    }
    claims, err := a.verify(ctx)                        // ① read + verify the JWT
    if err != nil { return nil, err }               //    bad token → Unauthenticated

    ctx = ContextWithUserID(ctx, claims.Subject)        // ② stamp identity onto ctx
    if claims.Manabie != nil && claims.Manabie.UserGroup != "" {
        ctx = ContextWithUserGroup(ctx, claims.Manabie.UserGroup)
    }
    ctx = ContextWithJWTClaims(ctx, claims)             //    (resource_path now reachable)

    groups, err := a.groupDecider.Check(ctx, claims.Subject, info.FullMethod)  // ③ the role gate → Lesson 5
    if err != nil { return nil, err }
    if len(groups) > 0 {
        ctx = ContextWithUserGroup(ctx, groups[0]); ctx = ContextWithUserRoles(ctx, groups)
    }
    return handler(ctx, req)                            // ④ pass to the handler, identity in hand
}

Two things happen here that the rest of the codebase depends on. First, a bad or missing token is rejected right here (codes.Unauthenticated) — no handler ever sees it. Second, the verified claims are put on the context, which is how every downstream layer reads identity: UserIDFromContext(ctx), ResourcePathFromContext(ctx), UserGroupFromContext(ctx). That context is also what the database pool reads to set the RLS tenant variable (Part 3). This interceptor is where the JWT becomes the request's identity.

(Step ③, the role gate, also lives here — but that's authorization, so we unpack it in Lesson 5.)

Verify: signature, issuer, audience, expiry

verify pulls the token from metadata and runs it through a TokenVerifier that fetched Shamir's JWKS (Lesson 3):

parse the signed JWT → find the matching public key in the cached JWKS
verify the RS256 signature
check Issuer, Audience, and Time (expiry)             // jwt.Expected{...}
// on a key miss: re-fetch the JWKS once, then retry (keys rotate)

Those four checks — signature, issuer, audience, expiry — are the canonical JWT validation steps.¹ The service holds multiple verifiers (one per configured issuer: Manabie, Firebase, per-org projects); verify tries each and the first success wins. That's how one gate accepts both freshly-minted Manabie tokens and federated ones.

The two skip lists

Not every endpoint can (or should) require a token. Two per-service lists handle the exceptions — and they mean very different things:

Check yourself (from memory)

1. Curity — validating a token, Firebase verify. In-repo: internal/usermgmt/pkg/interceptors/auth.go:79,120, internal/golibs/interceptors/auth.go:269.

2. Skip lists + service-to-service: internal/golibs/interceptors/internal_api.go:10,32-57, cmd/server/<svc>/auth.go, .claude/rules/security.md.