Identity Provider (IdP) Authentication Filter

Overview

The IdpAuthFilter is a request-level authentication component that enables API consumers to authenticate using OIDC Bearer tokens issued by an external Identity Provider (IdP). It acts as a gatekeeper for the Admin API, intercepting incoming requests to verify credentials before they reach the application logic.

This filter solves the problem of integrating with customer-managed identity systems. Instead of relying solely on the platform's default Identity-Aware Proxy (IAP) authentication, API publishers can configure the platform to trust tokens from providers such as Azure AD, Okta, Keycloak, or any generic OIDC-compliant provider.

The filter runs early in the request processing pipeline, with a higher precedence than the AdminAuthorizationFilter. Its primary input is the Authorization HTTP header. Upon successful token validation, it enriches the request with the authenticated user's identity and passes it to the next component in the filter chain. If validation fails, it terminates the request with an HTTP 401 Unauthorized error.

How it works

The IdpAuthFilter inspects every incoming request for an Authorization header containing a Bearer token. Its behavior depends on the presence of this header and the system's IdP configuration.

flowchart TD
    subgraph IdpAuthFilter
        A[API Request In] --> B{Has 'Authorization: Bearer' header?};
        B -- No --> C[Pass to IAP Auth];
        B -- Yes --> D[Extract Token];
        D --> E{Load active IdP configs};
        E --> F{Any OIDC IdPs configured?};
        F -- No --> G["Log informational message (Y #77)<br>Pass to IAP Auth"];
        F -- Yes --> H[Attempt token verification];
        H --> I{Try Azure AD config};
        I -- Success --> L{Token Valid?};
        I -- Fail/Not Configured --> J{Try Okta config};
        J -- Success --> L;
        J -- Fail/Not Configured --> K{Try Keycloak config};
        K -- Success --> L;
        K -- Fail/Not Configured --> K2{Try Generic OIDC config};
        K2 -- Success --> L;
        K2 -- Fail/Not Configured --> L;
        L -- No --> M[Return HTTP 401<br>S2R-AUTH-0401];
        L -- Yes --> N{Email domain in 'allowed_email_domains'?};
        N -- No --> M;
        N -- Yes --> O[Set request identity attributes];
        O --> P[Forward to next filter];
    end

    subgraph Downstream
      C --> Z[IAP Authentication Handler]
      G --> Z
      P --> Y[Admin Authorization Filter]
    end

    subgraph API Consumer
      X[API Consumer] --> A
    end

    subgraph System
      E --> DB[(s2r_idp_config table)]
    end

    style M fill:#f99,stroke:#333,stroke-width:2px

Request Processing Flow

1. Header Check: The filter first checks for an Authorization header starting with Bearer . If the header is missing, empty, or malformed, the filter takes no action and passes the request to the next filter in the chain, effectively falling back to the default IAP-based authentication mechanism.

2. Configuration Loading: If a Bearer token is present, the filter loads all active IdP configurations for the current installation tenant from the s2r_idp_config database table.

   • Caching: To improve performance, these configurations are cached in memory for 30 seconds. The cache is keyed by tenant ID to ensure tenant data isolation. A configuration change made in the system may take up to 30 seconds to be reflected, unless the cache is explicitly invalidated.
   • No IdPs Configured: If no IdPs are configured for the installation, the filter logs an informational message and passes the request on to the IAP authentication path. This allows clients that defensively attach tokens to still function with IAP-only installations.

3. Token Verification: The filter attempts to verify the token against each configured and supported OIDC provider. The supported provider types are azure-ad, okta, keycloak, and oidc-generic.

   NOTE

   SAML-based IdPs are not handled by this filter. SAML assertions are processed via a separate /saml/acs callback endpoint.

   The filter tries providers in sequence. The first provider that successfully validates the token is chosen. A token is considered valid if it can be parsed and its signature, issuer (issuerUrl), and audience (clientId) match the IdP's configuration.

4. Domain Validation: Upon successful token verification, the filter extracts the user's email address from the token. If the IdP configuration includes a non-empty allowed_email_domains list, the filter checks if the user's email domain is present in that list. If the domain is not in the list, the request is rejected. If the list is empty, all email domains are permitted.

5. Identity Injection: If the token is valid and the email domain is allowed, the filter considers the user authenticated. It performs two actions before passing the request onward:

   • It sets the request attribute IdentityResolver.ATTR_IDP_VERIFIED_EMAIL to the user's verified email. This is the primary mechanism for passing the user's identity to downstream components like the IdentityResolver.
   • For backward compatibility, it wraps the HttpServletRequest to inject a synthetic X-Goog-Authenticated-User-Email header containing the same email address.

6. Failure Handling: If token verification fails for any reason (e.g., invalid signature, expired token, unknown issuer) across all configured IdPs, or if the user's email domain is not allowed, the filter immediately halts the request. It responds to the client with an HTTP 401 Unauthorized status and a JSON error payload.

Cache Invalidation

The IdpAuthFilter provides an invalidateCache() method. When called, it clears the entire in-memory cache of IdP configurations. This forces the filter to re-query the database on the next request that requires IdP validation. This mechanism is used internally to ensure that changes to IdP settings are applied promptly.

IdP Configuration

The filter's behavior is driven by records in the s2r_idp_config database table. While the platform provides a UI for managing these settings, understanding the underlying fields is useful for troubleshooting.

Error Responses

When authentication fails, the IdpAuthFilter returns an HTTP 401 Unauthorized status code and a JSON response body. This provides a consistent error-reporting mechanism for API consumers.

Error Response Format

{
  "error": {
    "code": "S2R-AUTH-0401",
    "message": "A human-readable error description."
  }
}

Common Error Messages

Troubleshooting

Bearer Token is Ignored If you send a request with a Bearer token but it seems to be ignored (e.g., you receive an error related to IAP authentication), it is likely because no IdPs are configured for your installation. In this scenario, the filter intentionally passes the request to the next authentication mechanism. The system logs will contain an INFO level message starting with Y #77: Bearer header present but no IdP configured.... To resolve this, configure an IdP in the platform settings.

HTTP 401 S2R-AUTH-0401 Errors This error code indicates a definitive failure within the IdpAuthFilter.

• Check that the Bearer token is valid, not expired, and was issued for the correct audience (clientId).
• Verify that the issuerUrl and clientId in your IdP configuration exactly match the values provided by your IdP.
• If you have configured allowedEmailDomains, ensure the user's email domain is in the list. Remember that the domain is the part of the email after the @ symbol.

Configuration Changes Not Taking Effect Due to the 30-second caching of IdP configurations, changes made to IdP settings may not be immediately active. Wait for the cache to expire or, if the system's management plane allows, trigger an action that invalidates the cache.

See Also

• Admin Authorization: After successful authentication by this filter, requests are passed to the AdminAuthorizationFilter to determine if the identified user has permission to perform the requested action.
• IAP Authentication: This is the platform's default authentication method, which is used when no Bearer token is provided or when no IdPs are configured.
• SAML Authentication: A separate authentication flow for IdPs that use the SAML protocol. It does not involve Bearer tokens and is handled by a different component.

All SOAP-to-REST docs