Learning outcomes
- Trace identity from authentication through assertion creation and upstream validation.
- Validate signature, issuer, audience, time, subject, and trusted delivery.
- Separate identity propagation from application permission.
- Test spoofing, replay, stale identity, wrong audience, and bypass paths.
Protocol roles
The identity provider authenticates the user. The proxy consumes that result, creates or obtains a session, and becomes the issuer of an upstream identity assertion. The upstream application is the relying party. The assertion identifies a subject and carries selected claims. The application remains the authorization owner for its objects and actions.
Define the issuer, relying audience, subject key, signing algorithm, verification keys, key rotation, issue and expiry times, delivery field, and authenticated transport.
Message flow
- The client reaches the intended proxy route.
- The proxy authenticates or resumes a valid session and authorizes the route.
- The proxy removes identity fields supplied by the client.
- The proxy creates a signed assertion for the intended upstream and sends it over an authenticated channel.
- The application extracts the assertion from the trusted field.
- The application restricts algorithms, selects a trusted key, verifies the signature, issuer, audience, time, and required subject claims.
- The application maps the issuer and subject to local state and authorizes the requested object and action.
Validation and failure cases
Reject missing signatures, unapproved algorithms, unknown keys, wrong issuer, wrong audience, expired or premature assertions, absent stable subject, malformed claims, duplicate fields, and untrusted delivery paths. Test a direct origin request, copied unsigned header, replay after expiry, key rotation, and a valid assertion for another upstream.
Do not use an email address as a universal account key without a documented issuer-specific mapping and change process.
Design tradeoffs and residual risk
Signed assertions reduce trust in mutable headers but add key distribution, validation, and clock dependencies. Short lifetimes limit replay but increase rotation and time-synchronization sensitivity. Rich claims reduce lookups but increase staleness, privacy, and token size.
An assertion proves what its issuer states. It does not prove that the application should permit the requested action.
Pomerium boundary
Pomerium can send a signed identity assertion and selected identity headers to a configured upstream. The upstream must validate the assertion using the documented keys and claims, prevent direct bypass, and enforce local authorization. Unsigned convenience headers are not a substitute for signature validation on an untrusted path.
Exercise
Write the validation order for one upstream. Include issuer, audience, algorithm, key source, subject mapping, time, transport, and error behavior. Then send missing, altered, expired, wrong-audience, unknown-key, unsigned-header, and direct-origin requests.
For a valid assertion, request another tenant's record and confirm that the application still denies it.
Evaluation checklist
- Does the application trust a fixed issuer, audience, algorithm set, and key source?
- Is client-supplied identity removed before the proxy sends verified context?
- Does the upstream reject direct and wrong-audience requests?
- Is subject mapping stable within an issuer and safe across account changes?
- Does local object and action authorization run after identity validation?
Next learning unit
Signed Header
Pomerium's signed header is the X-Pomerium-Jwt-Assertion header.
