Apps & Routes

Applications and routes define the protected resources the Maverics Orchestrator manages. Each application specifies what to protect, how to authenticate users, and what identity information to pass to backend services. Routes determine which incoming traffic matches each application, and policies enforce authentication and authorization at specific URL paths.

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[].

How It Works

Applications are defined under the apps top-level key as an array of application definitions. Each app has a name, a type, and type-specific configuration. The five app types serve different protocols:

proxy — HTTP reverse proxy that forwards requests to a backend after applying auth policies
oidc — OpenID Connect client registered with the Orchestrator’s OIDC Provider
saml — SAML Service Provider registered with the Orchestrator’s SAML Provider
mcpProxy — MCP identity proxy for upstream MCP servers
mcpBridge — REST-to-MCP translation using OpenAPI specifications

For proxy apps, route patterns match incoming traffic by hostname, path, or both. Policies bind to specific URL locations within an app and define which identity connectors handle authentication. Headers inject identity attributes into upstream requests, enabling legacy applications to receive user information without supporting modern authentication protocols.

Key Concepts

App Types

Each app type serves a specific protocol and use case:

proxy is the most common type — an identity-aware reverse proxy that protects backend applications without code modification. Use this for legacy apps, internal portals, and any HTTP application that needs authentication.
oidc registers an OIDC client with the Orchestrator’s built-in OIDC Provider. Use this when downstream applications support OIDC natively and you want the Orchestrator to act as the authorization server.
saml registers a SAML Service Provider with the Orchestrator’s SAML Provider. Use this for applications that require SAML assertions.
MCP Proxy proxies MCP (Model Context Protocol) requests with identity injection. Use this for AI agents that need authenticated access to MCP servers.
MCP Bridge translates REST APIs into MCP tools using an OpenAPI specification. Use this to expose existing APIs as MCP tools for AI agents.

Route Patterns and URL Matching

Route patterns determine which incoming requests an app handles. Patterns support three 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

Authentication Policies and IDP Binding

Policies bind identity connectors to specific URL locations within an app. Each policy specifies which connectors handle authentication for that location, whether unauthenticated access is allowed, and how long authorization decisions are cached.

Header Injection

Headers inject identity attributes into upstream requests using template syntax (e.g., {{ azure.email }}). This enables legacy applications that expect headers like SM_USER or X-Remote-User to receive authenticated user information without code changes.

Attribute Providers

After authentication, attribute providers load additional user attributes from secondary connectors (like LDAP directories or database lookups). These enriched attributes are then available for header injection and authorization decisions.

Configuration Reference

Common App Fields

Every application requires a name and type.

Key	Type	Required	Description
`apps[].name`	string	Yes	Unique application identifier
`apps[].type`	string	Yes	Application type: `proxy`, `oidc`, `saml`, `mcpProxy`, or `mcpBridge`

App Type: proxy

The proxy type is the most common application type. It acts as an identity-aware reverse proxy, forwarding requests to a backend after applying authentication and authorization policies.

Key	Type	Default	Required	Description
`upstream`	string	—	Yes	Backend URL to forward requests to (e.g., `https://backend:8080`)
`routePatterns`	array	—	Yes	URL patterns to match — supports hostnames, paths, or hostname/path combinations
`preserveHost`	boolean	`false`	No	Preserve the original Host header when proxying to the upstream
`tls`	string	—	No	TLS profile name for the upstream connection
`headers`	array	—	No	Headers to inject on proxied requests (see Header Injection below)
`policies`	array	—	No	Location-based authentication and authorization policies (see Authentication Policies below)
`attrProviders`	array	—	No	Attribute providers for post-authentication attribute loading from additional connectors
`unauthorizedPage`	string	—	No	Default redirect URL for unauthorized requests
`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

handleUnauthorizedSE is available as an alternative to unauthorizedPage for custom 403 handling. These two fields are mutually exclusive.

App Type: oidc

The OIDC app type defines an OpenID Connect client registered with the Orchestrator’s OIDC Provider. Key fields are listed below; full documentation is available on the OIDC Provider mode reference page.

Key	Type	Required	Description
`clientID`	string	Yes	Unique OIDC client identifier
`public`	boolean	No	Public client — does not require a client secret
`credentials.secrets`	array	No	Client secrets for authentication (array of secret references)
`grantTypes`	array	No	Allowed OAuth grant types: `authorization_code`, `client_credentials`, `refresh_token`, `password`, `urn:ietf:params:oauth:grant-type:token-exchange`
`redirectURLs`	array	No	Allowed redirect URLs for authorization code flow
`claimsMapping`	object	No	Map connector attributes to OIDC claims (e.g., `email: "azure.preferred_username"`)
`accessToken.type`	string	No	Token format: `"jwt"` or `"opaque"`
`accessToken.lifetimeSeconds`	integer	No	Access token lifetime in seconds
`refreshToken.allowOfflineAccess`	boolean	No	Enable refresh tokens for this client
`cors.allowedOrigins`	array	No	CORS allowed origins for this client

Deprecated: clientSecret — use credentials.secrets instead for client authentication.

App Type: saml

The SAML app type defines a SAML Service Provider registered with the Orchestrator’s SAML Provider. Requires samlProvider to be configured. Key fields are listed below; full documentation is available on the SAML Provider mode reference page.

Key	Type	Required	Description
`entityIDs`	array	Yes	SP entity IDs — each entry has `identifier` (string) and `default` (boolean) fields
`consumerServiceURLs`	array	Yes	Assertion Consumer Service URLs — each entry has `url` (string) and `default` (boolean) fields
`logoutServiceURL`	string	No	SP single logout URL
`nameID.format`	string	No	NameID format (e.g., `urn:oasis:names:tc:SAML:1.1:nameid-format:emailAddress`)
`nameID.attrMapping`	string	No	NameID value mapping using template syntax (e.g., `{{ azure.email }}`)
`claimsMapping`	object	No	Map connector attributes to SAML assertion attributes
`signature`	object	No	Per-app signing configuration — overrides SAML Provider defaults
`encryption`	object	No	SAML assertion encryption configuration

Deprecated fields: audience — use entityIDs; consumerServiceURL — use consumerServiceURLs; nameIDFormat — use nameID.format.

App Type: mcpProxy

The MCP Proxy app type proxies MCP (Model Context Protocol) requests to an upstream MCP server with identity injection. Requires the MCP Provider to be configured. Key fields are listed below; full documentation is available on the AI Identity Gateway mode reference page.

Key	Type	Required	Description
`toolNamespace.name`	string	No	Tool namespace prefix — prepended to tool names from the upstream server
`upstream.transport`	string	Yes	Transport type: `"stdio"` for subprocess commands or `"stream"` for HTTP streaming
`upstream.stdio.command`	string	Conditional	Command to execute for stdio transport (required when transport is `stdio`)
`upstream.stream.url`	string	Conditional	Upstream MCP server URL for stream transport (required when transport is `stream`)
`authorization.inbound.opa`	object	No	OPA (Open Policy Agent) policy for inbound request authorization
`authorization.outbound.type`	string	No	Outbound authorization type: `"tokenExchange"` for delegation tokens or `"unprotected"` for no auth

App Type: mcpBridge

The MCP Bridge app type translates REST APIs into MCP tools using an OpenAPI specification. Requires the MCP Provider to be configured. Key fields are listed below; full documentation is available on the AI Identity Gateway mode reference page.

Key	Type	Required	Description
`mode`	string	Yes	Bridge mode — only `"openapi"` is supported
`toolNamespace.name`	string	No	Tool namespace prefix — prepended to generated tool names
`openapi.spec.uri`	string	Conditional	File URI to the OpenAPI spec (e.g., `file:///path/to/openapi.yaml`); mutually exclusive with `openapi.spec.data`
`openapi.spec.data`	string	Conditional	Inline OpenAPI specification content; mutually exclusive with `openapi.spec.uri`
`openapi.baseURL`	string	No	Override the server URL from the OpenAPI spec
`authorization`	object	No	Authorization configuration — same structure as MCP Proxy (`inbound.opa` and `outbound.tokenExchange`)

Authentication Policies

Policies control authentication and authorization for matched requests. They are shared across proxy, oidc, and saml app types.

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 — must match `connectors[].name` entries
`policies[].authentication.allowUnauthenticated`	boolean	`false`	Allow unauthenticated access to this location
`policies[].decision.lifetime`	string	—	Decision cache TTL — how long authorization decisions are cached (duration string)

Authorization Rules

Authorization rules determine whether an authenticated user is allowed to access a resource. Rules support nested and/or conditions with four comparison operators. For the complete authorization rules reference — operators, operand formats, and rule aggregation — see Authorization.

Header Injection

Headers inject identity attributes into upstream requests, allowing legacy applications to receive user information without supporting modern authentication protocols. Headers are defined as an array of objects at the app level or policy level.

Key	Type	Description
`headers[].name`	string	HTTP header name (e.g., `X-Remote-User`, `SM_USER`)
`headers[].value`	string	Value using `{{ connector.claim }}` template syntax (e.g., `{{ azure.email }}`)

Alternatively, headers[].createHeaderSE can be used instead of name/value for dynamic header generation via a Service Extension. The name/value pair and createHeaderSE are mutually exclusive.

Example

Console UI
Configuration

Console UI documentation is coming soon. This section will walk you through configuring this component using the Maverics Console’s visual interface, including step-by-step screenshots and field descriptions.

maverics.yaml

apps:
  - name: legacy-hr-portal
    type: proxy
    upstream: https://internal-hr.example.com
    routePatterns:
      - "hr.example.com"
    preserveHost: true
    policies:
      - location: "/"
        authentication:
          idps: ["azure"]
        authorization:
          rules:
            - or:
                - contains: ["{{ azure.groups }}", "hr-staff"]
                - contains: ["{{ azure.groups }}", "hr-managers"]
          rulesAggregationMethod: "or"
        decision:
          lifetime: "5m"
    headers:
      - name: "X-Remote-User"
        value: "{{ azure.email }}"
      - name: "X-Remote-Name"
        value: "{{ azure.name }}"
      - name: "X-Remote-Groups"
        value: "{{ azure.groups }}"
    attrProviders:
      - name: "corporate-ldap"
        usernameMapping: "{{ azure.sub }}"

Identity Fabric

Configure the identity providers referenced in app policies

Transport Layer Security (TLS)

Named TLS profiles for upstream connections and IdP communication

Authorization

Authorization rules, operators, and rule aggregation

Service Extensions

Custom request/response modification and API endpoints

OIDC Provider

OIDC Provider mode for apps with type oidc

SAML Provider

SAML Provider mode for apps with type saml

HTTP Proxy

HTTP Proxy mode for apps with type proxy

AI Identity Gateway

AI Identity Gateway for MCP Proxy and MCP Bridge app types

Console Administration

Orchestration

How It Works

Key Concepts

App Types

Route Patterns and URL Matching

Authentication Policies and IDP Binding

Header Injection

Attribute Providers

Configuration Reference

Common App Fields

App Type: proxy

App Type: oidc

App Type: saml

App Type: mcpProxy

App Type: mcpBridge

Authentication Policies

Authorization Rules

Header Injection

Example

Identity Fabric

Transport Layer Security (TLS)

Authorization

Service Extensions

OIDC Provider

SAML Provider

HTTP Proxy

AI Identity Gateway

Console Administration

Orchestration

​How It Works

​Key Concepts

​App Types

​Route Patterns and URL Matching

​Authentication Policies and IDP Binding

​Header Injection

​Attribute Providers

​Configuration Reference

​Common App Fields

​App Type: proxy

​App Type: oidc

​App Type: saml

​App Type: mcpProxy

​App Type: mcpBridge

​Authentication Policies

​Authorization Rules

​Header Injection

​Example

​Related Pages

Identity Fabric

Transport Layer Security (TLS)

Authorization

Service Extensions

OIDC Provider

SAML Provider

HTTP Proxy

AI Identity Gateway

How It Works

Key Concepts

App Types

Route Patterns and URL Matching

Authentication Policies and IDP Binding

Header Injection

Attribute Providers

Configuration Reference

Common App Fields

App Type: proxy

App Type: oidc

App Type: saml

App Type: mcpProxy

App Type: mcpBridge

Authentication Policies

Authorization Rules

Header Injection

Example

Related Pages