HTTP Proxy

The HTTP Proxy mode deploys the Maverics Orchestrator as an identity-aware reverse proxy. It sits in front of your applications — intercepting HTTP traffic to inject authentication headers, manage sessions, and enforce access policies without requiring any changes to the application’s code or configuration.

Console terminology: In the Maverics Console, the combination of applications, policies, headers, and connector bindings is managed through User Flows. In YAML, these elements are configured directly within each app’s configuration block under apps[].policies[].

When to use this mode

HTTP Proxy — Choose this mode when you cannot modify the application’s authentication code. Best for legacy apps, COTS products, and header-based authentication patterns.
OIDC Provider — Choose this mode when the application natively supports OpenID Connect.
SAML Provider — Choose this mode when the application natively supports SAML 2.0.
LDAP Provider — Choose this mode for applications that require an LDAP directory. Often paired with HTTP Proxy for comprehensive legacy app identity.
AI Identity Gateway — Choose this mode for securing AI agent-to-tool communication via MCP.

Use Cases

Protecting legacy apps without code changes — Add modern authentication to legacy applications that rely on form-based login, basic auth, or no authentication at all.
Header-based authentication injection — Inject identity headers (e.g., SM_USER, REMOTE_USER) into upstream requests for applications that expect header-based identity.
Session management for stateless apps — Provide cookie-based session management for applications that do not handle sessions natively.
Combining with LDAP Provider for legacy stacks — Pair HTTP Proxy with LDAP Provider mode to modernize applications that depend on both header-based auth and LDAP directory lookups.

How It Works

The HTTP Proxy request flow follows these steps:

Traffic interception — The Orchestrator listens on configured route patterns (hostname/path combinations) and intercepts all matching HTTP requests before they reach the upstream application.
Policy evaluation — Each request is matched against location-based policies. The Orchestrator determines which authentication and authorization rules apply based on the request path.
User authentication — If the user is not authenticated (no valid session), the Orchestrator redirects them to the configured identity provider. After successful authentication, a session cookie is established.
Authorization check — The Orchestrator evaluates authorization rules against the authenticated user’s attributes. Rules use and/or conditions with operators like equals, contains, etc. Unauthorized users are redirected or receive a 403 response.
Header injection — For authorized requests, the Orchestrator injects identity headers (e.g., SM_USER, X-Remote-User) into the upstream request using template syntax ({{ connector.claim }}). The upstream application receives these headers and uses them for its own identity decisions.
Proxying and response — The request (with injected headers) is forwarded to the upstream backend. The response flows back through the Orchestrator to the client. Optional Service Extensions can modify the request or response at this stage.

Key Concepts

Route Patterns and Upstreams

Route patterns define which traffic the proxy intercepts. Each proxy app maps one or more hostname/path patterns to an upstream backend URL. The Orchestrator acts as a transparent reverse proxy — the client connects to the Orchestrator, and the Orchestrator forwards to the backend.

Header Injection

Header injection is the primary mechanism for passing identity to legacy applications. Using {{ connector.claim }} template syntax, the Orchestrator maps claims from identity providers into HTTP headers that the upstream application expects. This replaces legacy access management products like SiteMinder without changing the application.

Location-Based Policies

Unlike OIDC and SAML modes where authorization is per-app, HTTP Proxy supports location-based policies. Different URL paths within the same application can have different authentication requirements and authorization rules. For example, / might allow all authenticated users while /admin requires a specific role.

Session Management

The Orchestrator manages sessions for proxied applications using cookies. This is critical for applications that lack their own session management. Session configuration (cookie name, lifetime, idle timeout) is defined at the global level and applies to all proxy apps. Some legacy applications have their own login flows in addition to the identity headers. The upstream login feature automates posting credentials to the upstream’s login form after the Orchestrator has authenticated the user, handling the “double login” problem.

Interface

Console UI
Configuration

HTTP Proxy mode does not have deployment-level settings in the Maverics Console. Unlike OIDC Provider, SAML Provider, LDAP Provider, and MCP Provider — which are configured in the Deployment Settings dialog — HTTP Proxy is configured entirely at the application level.To configure an HTTP Proxy application in the Console:

Navigate to Applications in the Maverics Console.
Create or select a proxy application.
Configure route patterns, upstream URL, headers, authentication policies, and authorization rules within the application’s settings.

Each proxy application manages its own routes, header injection, and location-based policies. See the Configuration tab for the complete field reference.

The Deployment Settings dialog does not include an HTTP Proxy section. All HTTP Proxy configuration is done through the Applications section of the Console. Some advanced options (Service Extensions for modifyRequestSE, modifyResponseSE, handleUnauthorizedSE, upstream login) are only available in YAML.

This example shows a proxy app protecting a legacy application with header injection, authentication policy, and logout configuration.

maverics.yaml

connectors:
  - name: my-idp
    type: oidc
    oidcWellKnownURL: https://idp.example.com/.well-known/openid-configuration
    oauthClientID: my-client
    oauthClientSecret: <my_client_secret>
    oauthLoginRedirect:
      urls:
        - https://app.example.com/oidc-callback
    scopes: openid profile email

apps:
  - name: legacy-app
    type: proxy
    routePatterns:
      - app.example.com/
    upstream: https://backend.internal:8443
    tls: upstream
    headers:
      - name: SM_USER
        value: "{{ my-idp.email }}"
      - name: X-User-Name
        value: "{{ my-idp.name }}"
      - name: X-User-Given-Name
        value: "{{ my-idp.given_name }}"
    policies:
      - location: /
        authentication:
          idps:
            - my-idp
        authorization:
          allowAll: true
      - location: /admin
        authentication:
          idps:
            - my-idp
        authorization:
          rules:
            - and:
                - equals: ["{{ my-idp.role }}", "admin"]
          rulesAggregationMethod: "and"
    logout:
      logoutURL: /logout
      postLogoutRedirectURL: https://app.example.com/

Configuration Reference

HTTP Proxy mode does not have a separate provider-level configuration key. The HTTP server settings (listen address, TLS, timeouts) are configured under the http top-level key, documented on the Configuration page. All proxy-specific configuration is at the app level under apps[].type: proxy.

Proxy App Fields

Key	Type	Default	Required	Description
`name`	string	—	Yes	Unique application identifier
`type`	string	—	Yes	Must be `proxy`
`upstream`	string	—	Yes	Backend URL to forward requests to (e.g., `https://backend:8080`)
`routePatterns`	array	—	Yes	URL patterns to match — at least one required
`preserveHost`	boolean	`false`	No	Preserve the original Host header when proxying to the upstream
`tls`	string	—	No	Named TLS profile for the upstream connection
`headers`	array	—	No	Headers to inject on proxied requests
`policies`	array	—	No	Location-based authentication and authorization policies
`attrProviders`	array	—	No	Attribute providers for post-authentication attribute loading
`unauthorizedPage`	string	—	No	Default redirect URL for unauthorized requests
`handleUnauthorizedSE`	object	—	No	Service Extension for custom 403 handling (mutually exclusive with `unauthorizedPage`)
`modifyRequestSE`	object	—	No	Service Extension to modify the request before proxying
`modifyResponseSE`	object	—	No	Service Extension to modify the response before returning to the client
`logout`	object	—	No	Logout configuration

Route pattern formats:

"example.com" — matches all requests to this hostname
"/path" — matches requests to this path on any hostname
"example.com/path" — matches requests to this hostname and path

Header Injection

Headers inject identity attributes into upstream requests using template syntax. This enables legacy applications to receive user information via HTTP headers without supporting modern authentication protocols. Each header entry uses either a name/value pair with template syntax, or a createHeaderSE Service Extension. These two approaches are mutually exclusive per header entry.

Key	Type	Description
`headers[].name`	string	HTTP header name (e.g., `SM_USER`, `X-Remote-User`)
`headers[].value`	string	Value using `{{ connector.claim }}` template syntax
`headers[].createHeaderSE`	object	Service Extension for dynamic header generation (mutually exclusive with `name`/`value`)

Template syntax: {{ connector_name.claim_name }} references a claim from a named connector. The connector name must match a connectors[].name entry, and the claim name must be a valid attribute from that connector.

Console UI
Configuration

In the Maverics Console, headers are configured within each application’s settings under the User Flows section. Each user flow can define headers that inject identity attributes into upstream requests. The Console supports the name/value pair approach. Service Extension-based header generation (createHeaderSE) is configured via YAML only.

headers:
  - name: SM_USER
    value: "{{ my-idp.email }}"
  - name: X-User-Name
    value: "{{ my-idp.name }}"
  - name: X-User-Given-Name
    value: "{{ my-idp.given_name }}"
  - name: X-User-Family-Name
    value: "{{ my-idp.family_name }}"
  - name: X-Forwarded-User
    value: "{{ my-idp.preferred_username }}"

Headers can also be defined at the policy level under policies[].headers, which override app-level headers for that specific location.

Authentication Policies

Policies control authentication and authorization for matched URL locations. Each policy applies to a specific location path within the app’s route patterns.

Key	Type	Default	Description
`policies[].location`	string	—	Resource path this policy applies to (required, must be unique per app)
`policies[].authentication.idps`	array	—	Connector names for authentication
`policies[].authentication.allowUnauthenticated`	boolean	`false`	Allow unauthenticated access to this location
`policies[].authentication.isAuthenticatedSE`	object	—	Service Extension for custom authentication check (must pair with `authenticateSE`)
`policies[].authentication.authenticateSE`	object	—	Service Extension for custom authentication flow (must pair with `isAuthenticatedSE`)
`policies[].authorization.allowAll`	boolean	—	Allow all authenticated users
`policies[].authorization.rules`	array	—	Authorization rules with `and`/`or` conditions
`policies[].authorization.rulesAggregationMethod`	string	—	How top-level rules combine: `"and"` or `"or"`
`policies[].authorization.isAuthorizedSE`	object	—	Service Extension for custom authorization
`policies[].authorization.unauthorizedPage`	string	—	Redirect URL for unauthorized requests on this location
`policies[].authorization.tokenMinting`	object	—	Token minting policy with OPA access token policies
`policies[].decision.lifetime`	string	—	Decision cache TTL (duration string, e.g., `5m`)
`policies[].headers`	array	—	Policy-level headers (override app-level headers for this location)
`policies[].useQueryParamsMatching`	boolean	`false`	Enable query parameter matching for this location

SE-based authentication (isAuthenticatedSE + authenticateSE) cannot be mixed with idps or allowUnauthenticated on the same policy. Use one approach or the other.

For details on authorization rule operators (equals, notEquals, contains, notContains) and nested and/or conditions, see the Apps & Routes reference.

Attribute Providers

Attribute providers load additional attributes from connectors after authentication. This is useful when you need claims from a second identity source (e.g., loading LDAP attributes after OIDC authentication).

Key	Type	Description
`attrProviders[].name`	string	Connector name to load attributes from
`attrProviders[].usernameMapping`	string	Template to map the authenticated user to the connector’s lookup key (e.g., `{{ azure.sub }}`)

Upstream login automates authentication to the backend application after the Orchestrator has authenticated the user. This is useful when the upstream application has its own login flow that must be completed.

Key	Type	Description
`upstreamLogin.isLoggedInSE`	object	Service Extension to check if the user is logged in to the upstream (required with `loginSE`)
`upstreamLogin.loginSE`	object	Service Extension to perform the upstream login (required with `isLoggedInSE`)

Logout

Key	Type	Description
`logout.logoutURL`	string	URL path that triggers logout (required for logout to function)
`logout.postLogoutRedirectURL`	string	URL to redirect the user to after logout

Service Extension Hooks

The proxy app type supports several Service Extension hooks for custom behavior. Service Extensions are referenced by file path and function name.

Hook	Purpose
`modifyRequestSE`	Modify the HTTP request before it is forwarded to the upstream
`modifyResponseSE`	Modify the HTTP response before it is returned to the client
`handleUnauthorizedSE`	Custom handler for 403 unauthorized responses (mutually exclusive with `unauthorizedPage`)
`createHeaderSE`	Generate headers dynamically (per-header, mutually exclusive with `name`/`value`)
`loadAttrsSE`	Custom attribute loading logic
`isLoggedInSE`	Check upstream login status (part of `upstreamLogin`)
`loginSE`	Perform upstream login (part of `upstreamLogin`)
`isAuthenticatedSE`	Custom authentication check (per-policy, must pair with `authenticateSE`)
`authenticateSE`	Custom authentication flow (per-policy, must pair with `isAuthenticatedSE`)
`isAuthorizedSE`	Custom authorization logic (per-policy)

The HTTP Proxy mode works with all Identity Fabric connectors. The Orchestrator authenticates users via any upstream IdP and injects identity headers into proxied requests. These are the most commonly used pairings:

Azure AD

Microsoft Entra ID for enterprise SSO

Okta

Okta SSO consolidation

LDAP

Directory attributes for header enrichment

Custom OIDC

Any OIDC-compliant provider

See the connector compatibility matrix for all supported pairings and the Identity Fabric overview for the full connector list. The HTTP Proxy also pairs with:

LDAP Provider — Pair with LDAP Provider mode for applications that need both header-based auth and LDAP directory access
Caches — Distributed session storage with Redis for multi-instance deployments

Troubleshooting

Headers not arriving at the upstream application

Symptoms: The upstream application does not see injected headers. User identity is missing from the request.Causes:

Header template syntax error — missing {{ }} delimiters or incorrect spacing.
Connector name typo in the template (e.g., {{ my_idp.email }} when the connector is named my-idp).
The upstream application or an intermediate proxy is stripping custom or X- headers.

Resolution:

Verify template syntax uses the {{ connector.attribute }} format exactly, with double curly braces and a dot separator.
Confirm the connector name in the template matches a connectors[].name entry in your configuration.
Check whether the upstream application or any intermediate load balancer strips custom headers. Some application servers discard headers with underscores or specific prefixes by default.

Authentication redirect loop

Symptoms: The browser loops endlessly between the Orchestrator and the identity provider, never completing authentication.Causes:

Session cookie domain mismatch — the cookie is set for a domain that does not cover the Orchestrator’s hostname.
The IdP callback URL does not match the oauthLoginRedirect.urls configured on the connector.
The routePatterns do not cover the callback path, so the Orchestrator does not intercept the callback.

Resolution:

Verify session.cookie.domain covers the Orchestrator’s hostname (e.g., .example.com for app.example.com).
Ensure the callback URL registered at the IdP is listed in oauthLoginRedirect.urls on the connector.
Check that routePatterns include the callback path so the Orchestrator can process the authentication response.

403 Forbidden for authorized users

Symptoms: The user authenticates successfully but receives a 403 response on specific paths.Causes:

Location-based policy mismatch — the location path in the policy does not match the actual request path.
Authorization rules reference a connector attribute that does not return the expected value.
rulesAggregationMethod is set to and when or is needed (all rules must pass vs. any rule).

Resolution:

Verify the location path in the policy matches the request path. Location matching is prefix-based.
Check that the connector.attribute references in rules return expected values by inspecting the connector’s claims.
Review the rulesAggregationMethod setting — use or if any single rule should grant access, or and if all rules must pass.

Upstream connection refused or timeout

Symptoms: 502 Bad Gateway or connection timeout after the user successfully authenticates.Causes:

The upstream URL is unreachable from the Orchestrator host.
TLS certificate mismatch on the upstream — the Orchestrator cannot verify the upstream’s certificate.
Wrong port in the upstream URL.

Resolution:

Verify the Orchestrator can reach the upstream URL from its host (test with curl or equivalent).
If using HTTPS for the upstream, check the TLS profile configuration and ensure the upstream’s certificate is trusted.
Confirm the port in the upstream URL matches the port the backend application is listening on.

Session expires too quickly

Symptoms: Users are forced to re-authenticate frequently, even during active use.Causes:

session.lifetime.idleTimeout or maxTimeout is set too low for the expected user activity pattern.
A load balancer in front of multiple Orchestrator instances is not using sticky sessions, causing requests to hit instances that do not have the user’s session.

Resolution:

Adjust session.lifetime.idleTimeout and session.lifetime.maxTimeout to match your expected user session duration.
Configure sticky sessions on the load balancer using the maverics_session cookie so that requests from the same user are routed to the same Orchestrator instance.

LDAP Provider

Virtualize LDAP directories for legacy applications — often paired with HTTP Proxy

OIDC Provider

Configure the Orchestrator as an OpenID Connect authorization server

Identity Fabric

Connect upstream identity providers to the Orchestrator

Architecture and Concepts

Understand how modes fit into the Orchestrator architecture

Console Administration

Orchestration

Use Cases

How It Works

Key Concepts

Route Patterns and Upstreams

Header Injection

Location-Based Policies

Session Management

Interface

Configuration Reference

Proxy App Fields

Header Injection

Authentication Policies

Attribute Providers

Logout

Service Extension Hooks

Azure AD

Okta

LDAP

Custom OIDC

Troubleshooting

LDAP Provider

OIDC Provider

Identity Fabric

Architecture and Concepts

Console Administration

Orchestration

​Use Cases

​How It Works

​Key Concepts

​Route Patterns and Upstreams

​Header Injection

​Location-Based Policies

​Session Management

​Upstream Login

​Interface

​Configuration Reference

​Proxy App Fields

​Header Injection

​Authentication Policies

​Attribute Providers

​Upstream Login

​Logout

​Service Extension Hooks

​Related Integrations

Azure AD

Okta

LDAP

Custom OIDC

​Troubleshooting

​Related Pages

LDAP Provider

OIDC Provider

Identity Fabric

Architecture and Concepts

Use Cases

How It Works

Key Concepts

Route Patterns and Upstreams

Header Injection

Location-Based Policies

Session Management

Upstream Login

Interface

Configuration Reference

Proxy App Fields

Header Injection

Authentication Policies

Attribute Providers

Upstream Login

Logout

Service Extension Hooks

Related Integrations

Troubleshooting

Related Pages