IAP JWT Assertion Verification

Overview

The IAP JWT Verifier is a security component responsible for validating JSON Web Token (JWT) assertions provided by an Identity-Aware Proxy (IAP). It ensures that any request to the administrative API is accompanied by a valid identity assertion, which is passed in the X-Goog-IAP-JWT-Assertion HTTP header.

This component solves the problem of authenticating users in environments where access is managed by an IAP. It cryptographically verifies that the JWT was issued by the trusted IAP, has not expired, is intended for the correct backend service, and contains a valid user identity. The verifier's primary input is the JWT string from the header, and its output is the verified user's email address. If verification fails for any reason, access is denied.

How it Works

The verifier processes each IAP assertion through a multi-step validation pipeline. The process is fail-closed, meaning any failure or ambiguity during validation results in the rejection of the assertion.

sequenceDiagram
    participant C as API Consumer
    participant IAP as Identity-Aware Proxy
    participant Admin as Admin API
    participant V as IAP JWT Verifier

    C->>+IAP: Request to Admin API
    IAP->>IAP: Authenticates user
    IAP-->>+Admin: Forward request with<br>X-Goog-IAP-JWT-Assertion header
    Admin->>+V: verifyEmail(JWT)
    V->>V: Parse and validate JWT
    V-->>-Admin: Return verified email or empty
    Admin->>Admin: If email present, authorize user
    Admin-->>-IAP: Process or reject request
    IAP-->>-C: API Response

Verification Steps

When the verifyEmail method is called with a JWT assertion, it performs the following sequence of checks:

1. Parse JWT Header: The verifier first inspects the JWT header to extract the signing algorithm (alg) and the key identifier (kid).
2. Algorithm Check: It confirms the alg is ES256. Assertions signed with any other algorithm are rejected.
3. Public Key Resolution: The kid is used to find the corresponding public key needed to verify the signature.
   • Keys are cached in memory for 6 hours (KEY_TTL_MS).
   • If a key for a given kid is in the cache and not expired, it is used immediately.
   • If the key is not in the cache or the cache is expired, the verifier triggers a refresh from the configured JWKS (JSON Web Key Set) URL.
   • Refresh attempts are rate-limited to at most once every 30 seconds (MIN_REFRESH_INTERVAL_MS).
   • If the JWKS fetch fails, the verifier logs an error but continues to use its last-known-good set of keys to avoid an outage.
4. Signature Verification: The JWT's signature is cryptographically verified against the resolved public key. A mismatch indicates a forged or corrupted token.
5. Standard Claim Validation: The verifier checks the following standard claims in the JWT payload:
   • iss (Issuer): Must be exactly https://cloud.google.com/iap.
   • exp (Expiration Time): Must be in the future.
   • iat (Issued At): Must be in the past.
   • Both exp and iat checks allow for a 30-second clock skew (CLOCK_SKEW_SECONDS) to accommodate minor time differences between servers.
6. Audience Validation: The aud (Audience) claim is validated to ensure the token was intended for this specific API. This validation operates in one of two modes. See Audience Validation Modes for details.
7. Email Extraction and Normalization: If all previous checks pass, the verifier extracts the email claim.
   • It removes the accounts.google.com: prefix if present.
   • For external identities, it may remove the securetoken.google.com/ prefix. See External Identity Normalization for the specific conditions.
   • The resulting string is checked to ensure it contains an @ symbol.
8. Return Value: If all steps succeed, the method returns the normalized email address. If any step fails, it logs a warning and returns an empty result, leading to request rejection.

Audience Validation Modes

The aud claim identifies the recipient for which the JWT is intended. The verifier supports two modes for validating this claim.

Pinned Audience

If the s2r.iap.audience configuration property is set, the verifier operates in a strict "pinned" mode. The JWT's aud claim must be a single string that exactly matches the configured value. This is the most secure configuration.

Dynamic Audience

If s2r.iap.audience is not set, the verifier dynamically validates the audience.

In this mode, the aud claim must be a string matching the pattern /projects/<project_number>/<location>/backendServices/<service_id>. The verifier performs these checks:

1. It determines the platform's own numeric project number. It first consults the s2r.iap.project-number configuration property. If that is not set, it attempts to discover the number from the runtime environment metadata.
2. If the project number cannot be determined, all assertions are rejected (fail-closed).
3. It confirms the aud claim starts with /projects/<own_project_number>/.
4. It validates that the rest of the claim matches the expected format for a backend service.

External Identity Normalization

The platform can process assertions for users from external identity providers. These identities often have a unique prefix in the email claim, such as securetoken.google.com/<PROJECT>/<TENANT>:<user_email>.

Configuration

The IAP JWT Verifier is configured through the following properties.

| Property | Type | Default Value | Description | --- | --- | --- | | s2r.iap.jwks-url | String | https://www.gstatic.com/iap/verify/public_key-jwk | The URL from which to fetch the IAP's ES256 public keys in JWKS format. The key fetch respects proxy settings configured for the platform. | s2r.iap.audience | String | — | The exact audience value expected in the JWT aud claim. If not set, the verifier uses dynamic audience validation. Setting this is highly recommended. | s2r.iap.project-number | String | — | The numeric project number of the deployment. Used for dynamic audience validation if s2r.iap.audience is not set. Must be a string of 1 to 20 digits. If not set, the platform attempts to discover it from the environment. | s2r.iap.external-identity-trusted-tenants | String | "" (empty) | A comma-separated list of trusted external identity issuers. An issuer is a PROJECT or PROJECT/TENANT string. This list is required to normalize emails from external identities.

Troubleshooting

When an IAP assertion is rejected, a warning is logged with a reason. The assertion token itself is never logged.

| Rejection Reason / Log Message | Meaning & Cause | S2R-AUTH IAP assertion rejected: unsupported alg ... | The JWT was signed with an algorithm other than ES256. The IAP should be configured to use ES256. | S2R-AUTH IAP assertion rejected: assertion missing kid header | The JWT header does not contain a kid (Key ID). This indicates a malformed token from the IAP.

| S2R-AUTH IAP assertion rejected: unknown kid | The kid from the JWT header does not match any of the public keys fetched from the JWKS URL. This can happen during a key rotation. The verifier will attempt to fetch new keys. If it persists, check that the s2r.iap.jwks-url is correct. | S2R-AUTH IAP assertion rejected: assertion aud does not match | The aud claim in the JWT does not match what the verifier expects. If s2r.iap.audience is set, ensure it exactly matches the IAP configuration. If it's not set, ensure the IAP is configured for a backend service in the same project as the platform, and that the platform can determine its project number. | S2R-AUTH IAP assertion rejected: ... (other reasons) | Includes assertion missing exp or iat, iat is in the future, missing email claim, etc. These usually indicate a malformed or invalid token. Check for clock synchronization issues between the platform and the identity provider. | S2R-AUTH IAP JWKS fetch failed ... (ERROR log) | The verifier could not connect to or fetch from the s2r.iap.jwks-url. It will continue to use stale keys if any are cached. Check network connectivity, DNS, and any egress proxy configuration between the platform and the JWKS endpoint.

| S2R-AUTH IAP project number unknown ... (ERROR log) | This error is logged once if s2r.iap.audience is not set and the platform could not determine its project number from s2r.iap.project-number or the environment. In this state, all IAP assertions will be denied. To fix, set either s2r.iap.audience or s2r.iap.project-number.

See Also

• Configuring an Egress Proxy: The IAP verifier's key fetching mechanism uses a shared HTTP client that can be configured to use an egress proxy for all outbound traffic.

All SOAP-to-REST docs