Module 6 ended on an uncomfortable note: TechCorp's system is now observable, resilient, scalable and operable, but it is still not secure. The first crack is the most visible one: the gateway's requireToken (03-04) only checks that the Authorization header starts with Bearer, and no service yet knows who is calling. This lesson closes that crack: it explains the difference between authenticating and authorizing, why the monolith's in-memory session does not work in a distributed system, how OAuth 2.0 and OpenID Connect work in practice with Keycloak as the identity server, what is inside a JWT and how it is validated with the realm's public keys, and how you then decide whether Ana Ruiz may see order ord-88213. All the code extends what has already been built: the gateway from 03-04, the @techcorp/common-http library and orders-service. Anything that concerns channel encryption (07-02), input validation (07-03) and secrets in Kubernetes (07-04) is only mentioned.

Notice. The flows, configurations and decisions in this lesson are for teaching purposes. Before exposing a real system, the Keycloak configuration, token lifetimes and authorization policies must be reviewed with a security professional and, where personal or payment data is involved, with the compliance officer.

1. Authentication versus authorization, and why the monolith's session does not work
2. OAuth 2.0 and OpenID Connect in practice: roles and flows
3. Anatomy of a JWT: structure, claims and signature with JWKS
4. Keycloak for TechCorp: realm, clients, roles and custom claims
5. Validation at the gateway: the complete requireToken with jose
6. Defense in depth: authenticate() in @techcorp/common-http
7. Authorization: roles, resource owner and scopes
8. Service to service: client credentials and what happens with RabbitMQ
9. 401 and 403 errors, logout and revocation
10. Tests: tokens signed with a local key in Jest

Two different questions that get mixed up every day:

In the techcorp-shop monolith, Ana logged in, Express stored a session in memory (or in Redis) and a connect.sid cookie identified her on every request. That does not work with seven processes: orders-service shares no memory with customers-service; a shared session in Redis couples every service to one store and one format, and every internal request would have to look it up. The alternative the whole industry has adopted is portable identity: a signed token that travels with every request and that any service can verify without asking anyone, using only the issuer's public key. That token is a JWT, and the protocol for obtaining it is OAuth 2.0 / OpenID Connect.

OAuth 2.0 is a framework for delegated authorization; OpenID Connect (OIDC) is the authentication layer on top of OAuth (it adds the ID token and the userinfo endpoint). In practice they are used together, with four roles:

The flows (grants) TechCorp uses, and the one it does not:

Ana's login and her first order, end to end:

Two important details: Ana's password is seen only by Keycloak (the SPA never touches it), and the gateway does not call Keycloak on every request: it verifies the signature locally with the public key it downloaded once.

A JWT is three Base64URL parts separated by dots: header.payload.signature.

• iss (issuer), sub (stable identifier of the subject), aud (who the token is for), exp/iat (expiry and issuance, in Unix seconds) and scope are standard claims (RFC 7519 and OAuth). azp (authorized party: the client that requested it), preferred_username and realm_access.roles are Keycloak's. customerId is a custom claim that we will add in section 4.
• The signature is RS256 (RSA + SHA-256, asymmetric): Keycloak signs with its private key; anyone verifies with the public one. The public keys are published in the JWKS (JSON Web Key Set), whose URL appears in the discovery document https://auth.techcorp.example/realms/techcorp/.well-known/openid-configuration (jwks_uri, token_endpoint, authorization_endpoint...). The kid in the header says which key of the set to use, which is why Keycloak can rotate keys without breaking anything.
• A JWT is not encrypted: anyone holding the token can read the payload (echo <payload> | base64 -d). Sensitive data never goes in it; the signature guarantees integrity, not confidentiality.

The three tokens Keycloak returns:

Short lifetimes are the key decision: a stolen access token is good for five minutes; the client renews it transparently with the refresh token. TechCorp's services do not accept ID tokens (different aud).

Keycloak is deployed in the cluster (official image, its own PostgreSQL, Ingress at auth.techcorp.example; the Platform team operates it). A realm is an isolated space of users, clients and keys; TechCorp uses one: techcorp. Its essential configuration, exportable as JSON and importable at startup (--import-realm):

What each line decides:

• publicClient: true + PKCE S256 for web-store: a SPA cannot keep secrets; PKCE replaces the secret. directAccessGrantsEnabled: false disables the password grant.
• serviceAccountsEnabled: true and standardFlowEnabled: false for orders-service: client credentials only; its service account gets the service role (with kcadm.sh add-roles --uusername service-account-orders-service --rolename service).
• The techcorp-api client scope adds aud: techcorp-api to every token (Keycloak does not set a useful aud by default) and the customerId claim from the customerId user attribute, which customers-service writes at sign-up through Keycloak's admin API (Customers is a conformist with respect to Keycloak, 02-03, and stores keycloak_sub, 02-04). That way no service needs a call to translate sub → customerId.
• The realm roles customer, operator, admin are assigned to people; service, to service accounts. The scopes orders:create, orders:read, products:read, customers:read bound what each client may request, regardless of the user.

The client_secret of orders-service lives in the Kubernetes Secret orders-oidc (OIDC_CLIENT_SECRET), alongside OIDC_ISSUER and OIDC_TOKEN_URL in the ConfigMap; managing and rotating it belongs to 07-04.

We replace the skeleton from 03-04. jose (npm install jose) is the reference library for JWT/JWK in Node.js; createRemoteJWKSet downloads the JWKS, caches it and refreshes it only if an unknown kid arrives (rotation) or cacheMaxAge elapses.

And in gateway/server.js, propagation inward. Before setting our own headers, any that arrive from outside are removed (nobody should be able to send us X-User-Roles: admin from the Internet):

Warning about X-User-*. These headers are only trustworthy if nobody but the gateway can reach orders-service:3002. On the cluster network that is, today, an assumption, not a guarantee: a compromised pod in the same namespace could call the service directly with whatever header it likes. That is why (a) the services verify the JWT again (section 6) and use the headers only as a convenience for logs, and (b) 07-02 and 07-04 lock down the network with NetworkPolicies, mTLS and control over who talks to whom.

Every service verifies the token again. It costs microseconds (RSA signature with a cached key) and removes blind trust in the network. The library exposes authenticate(), requireRole() and requireScope(), with the JWKS injectable for the tests in section 10:

Because they throw BusinessError, the errorMiddleware from 04-02 already turns them into problem+json with code UNAUTHENTICATED or FORBIDDEN. In orders-service, createApp receives the OIDC configuration and mounts the middleware before the business routes and after /health/* (Kubernetes probes carry no token):

src/config.js (04-03) gains OIDC_ISSUER: z.string().url() and OIDC_AUDIENCE: z.string().default('techcorp-api'); oidc is built from there in server.js.

Authenticated does not mean authorized. TechCorp combines three layers, from coarsest to finest:

The owner rule in GET /v1/orders/{id} and the 403 or 404 decision:

Why 404 when the order belongs to another customer, if 03-01 said 403? Because a 403 confirms that the identifier exists, and ord-NNNNN ids are easy to enumerate (OWASP calls this BOLA, 07-03): an attacker would learn how many orders there are and which ones are valid. TechCorp's decision: for customers, someone else's order behaves as if it did not exist (404 ORDER_NOT_FOUND); for operators, who do see everything, the case does not arise. 403 FORBIDDEN is reserved for "you are authenticated but your role/scope does not allow this action" (e.g. a customer calling POST /v1/orders/{id}/cancellation on someone else's order: 404 there too, same rule; a customer calling GET /v1/orders?status=PENDING without a customer filter: 403). The OpenAPI contract from 03-01 is updated: the ACCESS_DENIED in its table becomes FORBIDDEN, the only 403 code across the whole platform.

In POST /v1/orders the same idea in reverse: the body carries customerId (03-01), but the token rules. If the user has the customer role, the body's customerId must match req.user.customerId (otherwise 403 FORBIDDEN: there is nothing to hide here); an operator may create orders on behalf of someone else (phone sales). The createOrder use case receives user as part of the request and applies the rule, so the unit test from 04-05 covers it without HTTP.

When orders-service calls GET /v1/customers/c-1024 there is no user in front (or there is, but the order may also be created from a job). Orders authenticates as a service with client credentials, and caches the token until shortly before exp. In @techcorp/common-http:

createHttpClient (06-03) gains a tokenProvider option: if present, it adds Authorization: Bearer <token> to every request. In the Orders server.js:

At the receiving end, customers-service accepts GET /v1/customers/{id} if the token has the service role and the customers:read scope, or if it is the customer themselves (customerId in the token = {id}), or an operator. Catalog keeps GET /v1/products with authenticate({ optional: true }): the route is public through the gateway, but if a token arrives it verifies it and could, for instance, return special prices by role.

What about events over RabbitMQ? An order.created message carries no JWT: there is no "request" to authorize, and a 5-minute token makes no sense in a message that may be processed an hour later from a DLQ (06-03). Authentication is of the service to the broker: user orders with the password in the orders-rabbitmq Secret, permissions per vhost, exchange and queue. What each user may publish and consume, and encryption of the amqps:// channel, are detailed in 07-02. If a consumer needs to know who originated the order, that data travels in the event payload (customerId), not as a credential.

TechCorp's closed convention, in RFC 7807 format with code (03-01):

A 401 with error="invalid_token" is the signal for the SPA to renew with the refresh token and retry; a 403 is not retried.

Logout and revocation. A signed JWT is valid until exp even if the user logs out: the services do not ask Keycloak. TechCorp handles this with short tokens (5 min) plus refresh tokens that Keycloak does revoke (logout via end_session_endpoint, password change, disabled account): after logout, the worst case is five minutes of an already-issued token. For an immediate cut-off (a deprovisioned admin) there are introspection (/token/introspect, one call to Keycloak per request) or a revocation list by jti in Redis, mentioned only: TechCorp does not need them in the first phase.

The tests from 04-05 must not depend on a Keycloak. Since authenticate() accepts the jwks as a dependency, the tests generate a key pair and sign tokens to order:

The Pact contract tests (04-05) stay the same: the provider starts with this local JWKS and the consumer declares the Authorization: Bearer <anything> header with a type matcher; the signature is not part of the contract.

• Accepting any alg. Without algorithms: ['RS256'], an attacker can send alg: none or HS256 signed with the public key. Always pin it.
• Not checking aud. An ID token, or an access token issued for another API of the same Keycloak, would pass. audience is mandatory; that is why the techcorp-api client scope exists.
• Downloading the JWKS on every request or caching it forever. createRemoteJWKSet with cacheMaxAge and cooldownDuration is the middle ground: it rotates keys without restarts and does not turn Keycloak into a single point of failure.
• Trusting X-User-* without verifying the JWT in the service. That is the gap 07-02 and 07-04 narrow; until then, double validation is the safety net.
• Putting the client_secret in the ConfigMap, in the image or in a versioned .env. It goes in the orders-oidc Secret (07-04) and never in logs: add *.client_secret and OIDC_CLIENT_SECRET to the redact from 06-01 and to configForLog() from 04-03.
• Using 403 for other customers' orders and giving away identifier enumeration. Decide the policy and apply it across the whole platform.
• Tip: log userId (the sub) and azp, never preferred_username or email: they identify the person and the redact from 06-01 does not cover them.
• Tip: the /health/* probes and /metrics carry no token; mount authenticate() after them or expose them on another port.

Exercise 1. A developer proposes that bff-mobile use the password grant "because the app has its own login screen and that way we don't open the browser". Write three reasons to reject it and the concrete alternative with Keycloak.

Exercise 2. Implement in customers-service the authorization rule for GET /v1/customers/{id} described in section 8: it can be read by the customer themselves, an operator/admin, or a service token with customers:read. Decide what to return when a customer asks for another customer's profile and justify it.

Exercise 3. The orders-service access token expires every 5 minutes and Orders makes ~2 calls to Customers per order (≈6,000/day). How many requests to the token_endpoint does Orders make per day with createTokenProvider (30 s margin) and how many would it make without a cache? What happens if Keycloak is down for 2 minutes with and without the cache?

Solution 1. (1) The person's password passes through TechCorp code (the BFF and the app), widening the attack surface: any flaw in them exposes it; with Authorization Code + PKCE only Keycloak sees it. (2) You lose Keycloak's MFA, social login, password policies and brute-force detection, which are applied on its form. (3) It is discouraged by RFC 6819 and removed in OAuth 2.1; Keycloak ships with it disabled (directAccessGrantsEnabled: false) and enabling it is an exception that must be justified in an audit. Alternative: Authorization Code + PKCE with the system browser (ASWebAuthenticationSession/Custom Tabs, or the AppAuth library), redirectUri techcorp://callback, and if a "never leave the app" experience is wanted, customize the Keycloak login theme.

Solution 2.

Same policy as in Orders: for a customer, another customer "does not exist" (404), because c-NNNN ids are enumerable and a 403 would confirm which ones are registered; and the check runs before querying the database so that response time does not give away existence either.

Solution 3. With the cache: a token lasts 300 s and is renewed at 270 s (30 s margin); over 24 h that is 86,400 / 270 ≈ 320 requests to the token_endpoint, regardless of traffic. Without the cache: one per outgoing call, ≈ 6,000 (and ×2 during campaigns), plus Keycloak's latency added to every order. If Keycloak is down for 2 minutes: with the cache, Orders keeps working as long as the current token has not expired (up to 4.5 min in the best case; in the worst, if the outage coincides with the renewal, get() fails and createHttpClient translates it into DEPENDENCY_UNAVAILABLE 503 with Retry-After, like any dependency in 06-03); without the cache, every order fails for those 2 minutes. The cache turns Keycloak into a soft dependency for the synchronous flow; tokens already issued to users also remain valid, because the services verify with the cached JWKS.

TechCorp has gone from "there is an Authorization header" to a verifiable identity across the whole system. Keycloak, in the techcorp realm, authenticates people with Authorization Code + PKCE (web-store, bff-mobile) and services with client credentials (orders-service), issues 5-minute RS256 access tokens with iss, aud: techcorp-api, scope, realm_access.roles and the custom customerId claim, and publishes its keys in the JWKS. The gateway validates with jose (cached createRemoteJWKSet, jwtVerify with issuer, audience and algorithms), strips and propagates X-User-Id/X-User-Roles, and answers 401 UNAUTHENTICATED with WWW-Authenticate; every service verifies again with authenticate() from @techcorp/common-http and authorizes with requireRole, requireScope and the owner rule (someone else's order → 404, insufficient role → 403 FORBIDDEN); Orders obtains its token with createTokenProvider and caches it; RabbitMQ authenticates the service, not the message; and the tests sign tokens with a local key. One assumption remains without a guarantee: that internal requests and the X-User-* headers travel over a network where nobody listens or impersonates. Securing the channel — TLS at the edge, mTLS between services, encrypted RabbitMQ and databases, signed webhooks — is the next lesson: communication security.