Configure Authorization Policies

By the end of this guide, you will have a Maverics Orchestrator enforcing authorization policies on every request — evaluating user attributes, roles, and context to determine whether access is allowed.

Authentication vs. Authorization

Before diving in, it helps to understand the distinction between these two concepts because they are often confused. Authentication answers the question “Who is this user?” — it verifies identity through credentials like passwords, OIDC tokens, or SAML assertions. Authorization answers the question “What is this user allowed to do?” — it checks whether an authenticated user has permission to access a specific resource or perform a specific action. The Maverics Orchestrator handles both. Your authentication configuration verifies user identity. The authorization policies in this guide control what those authenticated users can access. Authentication always happens first — you cannot authorize a user you have not identified.

Prerequisites

A running Maverics Orchestrator — If you have not installed it yet, follow the Quick Start guide first.
An identity provider connected — Your Orchestrator should be authenticating users against an identity provider. The Quick Start or SSO guides cover this.
Users authenticating successfully — Before adding authorization, confirm that users can log in and access your applications without policy restrictions.

Configure Policies

Choose your authorization approach

The Orchestrator provides different authorization mechanisms depending on the mode you are running. Choose the approach that matches your deployment:

HTTP Proxy — Uses location-based policies with declarative and/or rules per URL path. Each policy binds to a route and evaluates user attributes against conditions you define. See HTTP Proxy authorization below.
OIDC Provider and SAML Provider — Uses app-level authorization with declarative rules. OIDC Provider also supports OPA token minting policies. Authorization is configured on the app itself rather than per-location. See OIDC and SAML Provider authorization below.
MCP Bridge and MCP Proxy (AI Identity Gateway) — Uses OPA-based inbound authorization exclusively. Policies written in Rego evaluate per-tool invocations with access to MCP-specific context. See OPA Authorization (AI Identity Gateway) below.
LDAP Provider — Handles authorization entirely through Service Extensions. There are no declarative authorization rules. See the Service Extensions reference for the authenticateSE and searchSE hooks.

Not sure which mode applies? See Choosing a Mode.

HTTP Proxy

In HTTP Proxy mode, authorization is configured per-location within the policies array on each app. Each policy specifies a URL path, the identity providers that handle authentication, and optionally the authorization rules that control access after authentication.

Define authentication policy binding

Before configuring authorization rules, you need a policy that binds your identity provider connectors to application routes.

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.

Define policies on your app with authentication connector bindings:

maverics.yaml

apps:
  - name: my-app
    type: proxy
    upstream: https://backend.example.com
    routePatterns:
      - "app.example.com"
    policies:
      - location: "/"
        authentication:
          idps: ["azure", "ldap"]

Field	Description
`policies[].location`	URL path this policy applies to (must be unique per app)
`policies[].authentication.idps`	Connector names for authentication — must match `connectors[].name` entries
`policies[].authentication.allowUnauthenticated`	Allow unauthenticated access to this location (default: `false`)
`policies[].decision.lifetime`	Authorization decision cache TTL (duration string, e.g., `"5m"`)

The idps array references connectors by name. The Orchestrator will redirect unauthenticated users to the first listed identity provider for login.

Define 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: equals, notEquals, contains, and notContains.The Orchestrator supports multiple access control models, and you can combine them:RBAC (Role-Based Access Control) assigns permissions based on roles. A user has one or more roles (like “admin,” “editor,” or “viewer”), and each role grants access to specific resources. RBAC is straightforward and works well when your access patterns align with job functions.ABAC (Attribute-Based Access Control) makes decisions based on attributes — properties of the user, the resource, or the request context. Attributes can include things like department, location, or any claim from the identity provider.PBAC (Policy-Based Access Control) makes decisions based on centralized policies evaluated against request context, user attributes, and environmental conditions. PBAC generalizes RBAC and ABAC by expressing access rules as policies that can incorporate any combination of roles, attributes, and contextual factors.External PDP (Policy Decision Point) integration delegates authorization decisions to an external policy engine — such as OPA, Cedar, or a custom PDP — for organizations that maintain centralized policy engines across multiple systems.

Console UI
Configuration

Allow all authenticated users (simplest authorization):

maverics.yaml

policies:
  - location: "/"
    authentication:
      idps: ["azure"]
    authorization:
      allowAll: true

Simple role-based rule:

maverics.yaml

policies:
  - location: "/admin"
    authentication:
      idps: ["azure"]
    authorization:
      rules:
        - and:
            - contains: ["{{ azure.groups }}", "admin-group"]

Nested and/or rules for complex access control:

maverics.yaml

policies:
  - location: "/"
    authentication:
      idps: ["azure", "ldap"]
    authorization:
      rules:
        - and:
            - equals: ["{{ ldap.role }}", "admin"]
            - contains: ["{{ ldap.memberOf }}", "cn=managers"]
        - or:
            - equals: ["{{ http.request.method }}", "GET"]
            - notContains: ["{{ ldap.department }}", "restricted"]
      rulesAggregationMethod: "and"

In this example: the first rule requires the user to be an admin AND a member of the managers group. The second rule allows GET requests OR users not in the restricted department. Both rules must pass (rulesAggregationMethod: "and").Operators:

Operator	Description	Operands
`equals`	Exact string match	2 operands
`notEquals`	Inverse exact match	2 operands
`contains`	Substring or membership check	2 operands
`notContains`	Inverse substring/membership	2 operands

Operand formats:

{{ connector.attribute }} — claim from a named connector (e.g., {{ azure.groups }})
{{ http.request.method }} — HTTP request method
"literal" — static comparison value

See Authorization Reference for the complete rule syntax and per-mode comparison.

Start with broad policies and refine as needed. A common pattern is to require authentication on all routes first, then add access control restrictions to specific paths. You can always tighten access later without disrupting users who already have the right permissions.

Add programmatic authorization (optional)

For authorization logic that goes beyond declarative rules, HTTP Proxy mode supports two Service Extension hooks:

isAuthorizedSE runs after declarative rule evaluation and can override or supplement the result. This lets you implement dynamic authorization checks — for example, querying an external system, checking time-of-day restrictions, or applying business logic that cannot be expressed as and/or rules. Configure at policies[].authorization.isAuthorizedSE. See Service Extensions.
handleUnauthorizedSE customizes the response when authorization is denied. Instead of the default 403 Forbidden page, you can render a custom error page, redirect to a request-access workflow, or log additional context. Configure at apps[].handleUnauthorizedSE. This hook is mutually exclusive with the unauthorizedPage setting. See Service Extensions.

OIDC and SAML Provider

In OIDC Provider and SAML Provider modes, authorization is configured at the app level (apps[].authorization) rather than per-location. The same declarative rule syntax is available — allowAll, rules, and rulesAggregationMethod — but the configuration lives directly on the app instead of inside a policies[] block.

Configure declarative rules

Console UI
Configuration

Allow all authenticated users:

maverics.yaml

apps:
  - name: my-oidc-app
    type: oidc
    authorization:
      allowAll: true

Role-based rule at the app level:

maverics.yaml

apps:
  - name: my-oidc-app
    type: oidc
    authorization:
      rules:
        - and:
            - contains: ["{{ azure.groups }}", "app-users"]
      rulesAggregationMethod: "and"

The rule syntax (and, or, operators, operand formats) is the same as HTTP Proxy. The only difference is the config location: apps[].authorization instead of apps[].policies[].authorization.

Configure OPA token minting policies (OIDC Provider only, optional)

OIDC Provider mode supports OPA policies for token minting authorization. This provides a governance layer over which tokens the Orchestrator issues — you can enforce policies on token exchange based on user attributes, client identity, or environmental conditions. This does not apply to SAML Provider mode, which issues assertions rather than tokens.

maverics.yaml

apps:
  - name: my-oidc-app
    type: oidc
    authorization:
      tokenMinting:
        accessToken:
          policies:
            - name: token-governance
              rego: |
                package orchestrator

                default result := {"allowed": true}

                # Deny tokens requested with the client_credentials grant type
                result := {"allowed": false, "internal_message": "client_credentials not permitted"} {
                  input.request.oauth.grant_type == "client_credentials"
                }

OPA token minting policies must define a result object containing an allowed field. The Orchestrator denies token issuance if allowed is false. You can optionally include internal_message (logged server-side) and external_message (returned to the client) fields. See OPA Policy Output Schema for the full output format.

OIDC app input schema

The following JSON shows the complete data available under input when evaluating an OIDC token minting policy. Values are demonstrative.

{
  "source": {
    "ip": "192.168.1.100"
  },
  "request": {
    "http": {
      "host": "idp.example.com",
      "method": "POST",
      "path": "/token",
      "headers": {
        "Content-Type": "application/x-www-form-urlencoded",
        "User-Agent": "Go-http-client/1.1"
      }
    },
    "oauth": {
      "client_id": "325859cf-5bbe-492f-b9e7-929f2bed1230",
      "scope": "read:users write:settings",
      "grant_type": "urn:ietf:params:oauth:grant-type:token-exchange",
      "subject_token": {
        "claims": {
          "scope": "api:read api:write"
        }
      },
      "actor_token": {
        "claims": {
          "scope": "openid"
        }
      },
      "response": {
        "access_token": {
          "claims": {
            "scope": "read:users write:settings",
            "aud": "https://api.example.com",
            "client_id": "325859cf-5bbe-492f-b9e7-929f2bed1230"
          }
        },
        "scope": "read:users write:settings",
        "expires_in": 3600
      }
    }
  }
}

OIDC app example: enforce scope reduction on token exchange

The following policy ensures that scopes are only reduced during token exchange flows. The requested scopes in the token exchange request must be a subset of the scopes in the subject_token. All other grant types are allowed without restriction.

policy.rego

package orchestrator

default result["allowed"] := false

# Allow all non-token-exchange grant types.
result["allowed"] if {
	input.request.oauth.grant_type != "urn:ietf:params:oauth:grant-type:token-exchange"
}

# Parse scopes from space-separated strings into sets.
requested_scopes := {s | some s in split(input.request.oauth.scope, " "); s != ""}
subject_scopes := {s | some s in split(input.request.oauth.subject_token.claims.scope, " "); s != ""}

# For token exchange grants, allow if requested scopes are a subset of subject token scopes.
result["allowed"] if {
	input.request.oauth.grant_type == "urn:ietf:params:oauth:grant-type:token-exchange"
	print("requested_scopes:", requested_scopes)
	print("subject_scopes:", subject_scopes)
	count(requested_scopes - subject_scopes) == 0
}

result["internal_message"] := "requested scopes exceed subject_token scopes" if {
	not result.allowed
}

result["external_message"] := "invalid_scope" if {
	not result.allowed
}

Add programmatic authorization (optional)

The isAuthorizedSE Service Extension hook is also available in OIDC Provider and SAML Provider modes. Configure at apps[].authorization.isAuthorizedSE. See Service Extensions.

AI Identity Gateway (OPA Authorization)

In MCP Bridge and MCP Proxy modes (AI Identity Gateway), OPA is the only authorization mechanism. There are no declarative and/or rules. All authorization is handled through Rego policies that evaluate per-tool invocations with access to MCP-specific context such as tool name and arguments. Configure OPA via authorization.inbound.opa with a policy name and either file (path to a .rego file) or inline rego.

Configure MCP app inbound authorization policies

Console UI
Configuration

Inline OPA policy:

maverics.yaml

authorization:
  inbound:
    type: opa
    opa:
      name: my-auth-policy
      rego: |
        package orchestrator

        default result := {"allowed": false}

        # Allow the listUsers tool
        result := {"allowed": true} {
          input.request.mcp.type == "tool"
          input.request.mcp.tool.params.name == "listUsers"
        }

        # Allow the getUser tool
        result := {"allowed": true} {
          input.request.mcp.type == "tool"
          input.request.mcp.tool.params.name == "getUser"
        }

File-based OPA policy:

maverics.yaml

authorization:
  inbound:
    type: opa
    opa:
      name: my-auth-policy
      file: /etc/maverics/policies/auth.rego

For tool filtering configuration — controlling which tools are exposed to MCP clients during tools/list — see the MCP Proxy App reference.

For the complete per-mode authorization comparison, see the Authorization Reference.

OPA input schema and example policy

OPA policies must define a result object containing an allowed field. The Orchestrator denies the request if allowed is false. You can optionally include internal_message (logged server-side) and external_message (returned to the client) fields. See OPA Policy Output Schema for the full output format.

MCP app input schema

The input schema varies by policy type. Connection policies receive only the HTTP request context; inbound and listing policies additionally receive input.request.mcp with the request type in mcp.type.Connection admission — evaluated by the connection policy when the proxy establishes a new upstream session. No mcp context is present because no tool has been invoked yet:

{
  "source": {
    "ip": "192.168.1.100"
  },
  "request": {
    "http": {
      "host": "mcp.example.com",
      "method": "POST",
      "path": "/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "Content-Type": "application/json",
        "User-Agent": "MCP-Client/1.0"
      }
    }
  }
}

Tool call (mcp.type: "tool") — evaluated by the inbound policy on every tool invocation:

{
  "source": {
    "ip": "192.168.1.100"
  },
  "request": {
    "http": {
      "host": "mcp.example.com",
      "method": "POST",
      "path": "/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "Content-Type": "application/json",
        "User-Agent": "MCP-Client/1.0"
      }
    },
    "mcp": {
      "type": "tool",
      "tool": {
        "params": {
          "name": "listUsers",
          "arguments": {
            "exampleBodyKeyAlpha": 10,
            "exampleBodyKeyBeta": true
          }
        }
      }
    }
  }
}

Tool listing (mcp.type: "tools_list") — evaluated by the listing policy once per tool during a tools/list request. The policy runs for each tool individually; tools the policy denies are removed before the response reaches the MCP client:

{
  "source": {
    "ip": "192.168.1.100"
  },
  "request": {
    "http": {
      "host": "mcp.example.com",
      "method": "POST",
      "path": "/mcp",
      "headers": {
        "Authorization": "Bearer eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
        "Content-Type": "application/json",
        "User-Agent": "MCP-Client/1.0"
      }
    },
    "mcp": {
      "type": "tools_list",
      "response": {
        "tools_list": {
          "name": "listUsers"
        }
      }
    }
  }
}

MCP app example: JWT-based tool authorization

The following policy grants access to the get_ticket_price tool only if the Authorization header contains a JWT with the tickets:read scope. All other tools and requests are denied by default.

policy.rego

package orchestrator

# Default deny policy - all requests are denied unless explicitly allowed
default result["allowed"] := false

# Helper rule to extract and decode JWT from Authorization header.
# Parses the Bearer token and returns the decoded payload for policy evaluation.
jwt_payload := payload if {
	auth_header := input.request.http.headers.Authorization
	startswith(auth_header, "Bearer ")
	token := substring(auth_header, 7, -1)
	[_, payload, _] := io.jwt.decode(token)
}

# Allows access to the get_ticket_price tool if the token contains
# the tickets:read scope. Logs the tool name, client ID, and subject
# for audit purposes.
result["allowed"] if {
	print("request made to tool: ", input.request.mcp.tool.params.name)
	input.request.mcp.tool.params.name == "get_ticket_price"

	print("request made with client of: ", jwt_payload.client_id)
	contains(jwt_payload.scope, "tickets:read")

	print("access granted to subject:", jwt_payload.sub)
}

result["internal_message"] := "access is only permitted to the 'get_ticket_price' tool with tickets:read scope" if {
	not result.allowed
}

result["external_message"] := "unauthorized, contact support@example.com" if {
	not result.allowed
}

Connection admission example: check permitted MCP servers claim

The following policy gates upstream session establishment to bearers whose JWT contains a custom permitted_mcp_servers claim that includes the target server name. An IdP stamps this claim with the list of MCP servers the agent is authorized to reach; the policy checks membership before the session is opened. Because the admission decision is sticky for the lifetime of the session, this check runs once at connect time rather than on every tool call.

connection.rego

package orchestrator

default result["allowed"] := false

jwt_payload := payload if {
	auth_header := input.request.http.headers.Authorization
	startswith(auth_header, "Bearer ")
	token := substring(auth_header, 7, -1)
	[_, payload, _] := io.jwt.decode(token)
}

result["allowed"] if {
	"mission-control" in jwt_payload.permitted_mcp_servers
}

result["internal_message"] := "bearer token does not permit access to this MCP server" if {
	not result["allowed"]
}

result["external_message"] := "unauthorized: MCP server access not granted" if {
	not result["allowed"]
}

Tool Filtering example: allowlist tools exposed to the MCP client

The following policy exposes only the tools in the permitted set. The MCP client receives only these tools in its tools/list response — everything else is hidden, reducing the capabilities available to the AI agent.

listing.rego

package orchestrator

default result["allowed"] := false

# Tools visible to downstream MCP clients
allowed_tools := {"listUsers", "getUser", "searchUsers"}

result["allowed"] if {
	input.request.mcp.type == "tools_list"
	input.request.mcp.response.tools_list.name in allowed_tools
}

result["internal_message"] := "tool is not in the allowed set" if {
	not result["allowed"]
}

Tool Filtering example: scope-based tool exposure

The following policy exposes a different set of tools depending on the agent’s JWT scopes. ticketService:write is a superset of ticketService:read: agents with only ticketService:read see read-only tools; agents with ticketService:write see both read and write tools. This narrows each agent’s attack surface to exactly what it needs.

listing.rego

package orchestrator

default result["allowed"] := false

jwt_payload := payload if {
	auth_header := input.request.http.headers.Authorization
	startswith(auth_header, "Bearer ")
	token := substring(auth_header, 7, -1)
	[_, payload, _] := io.jwt.decode(token)
}

# Read-only tools available to agents with ticketService:read or ticketService:write
read_tools := {"listTickets", "getTicket", "searchTickets"}

# Write tools restricted to agents with the ticketService:write scope
write_tools := {"createTicket", "updateTicket", "closeTicket"}

result["allowed"] if {
	input.request.mcp.type == "tools_list"
	input.request.mcp.response.tools_list.name in read_tools
	some s in ["ticketService:read", "ticketService:write"]
	contains(jwt_payload.scope, s)
}

result["allowed"] if {
	input.request.mcp.type == "tools_list"
	input.request.mcp.response.tools_list.name in write_tools
	contains(jwt_payload.scope, "ticketService:write")
}

result["internal_message"] := "tool not permitted for this agent's scope" if {
	not result["allowed"]
}

OPA Policy Output Schema

All OPA policies — whether for OIDC token minting or MCP inbound authorization — must return a result object with the following structure:

{
  "result": {
    "allowed": true,
    "internal_message": "user does not have necessary group membership: missing admin membership",
    "external_message": "unauthorized"
  }
}

Field	Required	Description
`result.allowed`	Yes	Whether access should be granted (`true`) or denied (`false`)
`result.internal_message`	No	Details about the decision for server-side logs only. Not returned to clients.
`result.external_message`	No	Details returned to the client and also logged. Use for user-facing error messages.

Use print() statements in your Rego policies to emit debug output to Orchestrator logs. This is useful for tracing which rules matched and inspecting input values during policy development.

Test policy enforcement

With policies defined and applied, test that they work as expected by making requests as users with different roles and attributes. Testing both the “allowed” and “denied” paths confirms that your policies are enforced correctly.

Start the Orchestrator

Start (or restart) the Orchestrator to load your policy configuration:

maverics -config /etc/maverics/maverics.yaml

Verify allowed access

Test with a user who should have access:

Log in as a user whose roles or attributes satisfy the policy conditions
Navigate to the protected resource — you should see the application content
Verify the request reached your upstream application (check application logs)

Verify denied access

Test with a user who should be denied:

Log in as a user who does not meet the policy conditions
Navigate to the same resource — you should receive a 403 Forbidden response
Verify the request did not reach your upstream application

Success! Your Orchestrator is enforcing authorization policies. Requests from authorized users proceed to your applications, and unauthorized requests are blocked before they ever reach your upstream services.

Troubleshooting

Policy not being evaluated

If a policy does not seem to take effect, verify that it is attached to the correct application route. A defined but unattached policy is inert — it exists in the configuration but does not affect any traffic. Also check that the route path pattern matches the URLs you are testing. The Orchestrator logs which policies are evaluated on each request when debug logging is enabled.

Unexpected access denied

If a user is denied access when you expect them to be allowed, check the user’s claims from the identity provider. The most common cause is a mismatch between the role or attribute name in your policy and the actual claim value from the IdP. For example, your policy may check for a role called “admin” but the IdP sends “Admin” (case matters). Enable debug logging to see the exact claims the Orchestrator receives and the policy evaluation result.

Attribute not available for policy evaluation

If a policy references an attribute that the identity provider does not include in its token or assertion, the policy evaluation fails because the attribute is missing. Verify that your identity provider is configured to include the needed claims (roles, groups, department, or custom attributes) in the token it sends to the Orchestrator. Check the Identity Fabric reference for details on claim mapping for your specific provider.

Security Overview

Return to the Security guides hub for TLS, secrets, policies, and compliance

Authorization Reference

Per-mode authorization differences, enforcement behavior, and OPA policy patterns

Applications Reference

Complete configuration reference for authorization rules, operators, and policy syntax

Authentication Guides

Configure SSO, SAML federation, and identity provider connections that policies build on

Service Extensions

Custom authorization logic via isAuthorizedSE, handleUnauthorizedSE, and other SE hooks

Compliance and Audit

Log policy decisions and authorization events for compliance reporting

Getting Started

Authentication

AI Identity

Identity Continuity

Operations

Security

Authentication vs. Authorization

Prerequisites

Configure Policies

Choose your authorization approach

HTTP Proxy

OIDC and SAML Provider

OIDC app input schema

OIDC app example: enforce scope reduction on token exchange

AI Identity Gateway (OPA Authorization)

MCP app input schema

MCP app example: JWT-based tool authorization

Connection admission example: check permitted MCP servers claim

Tool Filtering example: allowlist tools exposed to the MCP client

Tool Filtering example: scope-based tool exposure

OPA Policy Output Schema

Test policy enforcement

Troubleshooting

Security Overview

Authorization Reference

Applications Reference

Authentication Guides

Service Extensions

Compliance and Audit

​Authentication vs. Authorization

​Prerequisites

​Configure Policies

​Choose your authorization approach

​HTTP Proxy

​OIDC and SAML Provider

​OIDC app input schema

​OIDC app example: enforce scope reduction on token exchange

​AI Identity Gateway (OPA Authorization)

​MCP app input schema

​MCP app example: JWT-based tool authorization

​Connection admission example: check permitted MCP servers claim

​Tool Filtering example: allowlist tools exposed to the MCP client

​Tool Filtering example: scope-based tool exposure

​OPA Policy Output Schema

​Test policy enforcement

​Troubleshooting

​Related Pages

Security Overview

Authorization Reference

Applications Reference

Authentication Guides

Service Extensions

Compliance and Audit

Authentication vs. Authorization

Prerequisites

Configure Policies

Choose your authorization approach

HTTP Proxy

OIDC and SAML Provider

OIDC app input schema

OIDC app example: enforce scope reduction on token exchange

AI Identity Gateway (OPA Authorization)

MCP app input schema

MCP app example: JWT-based tool authorization

Connection admission example: check permitted MCP servers claim

Tool Filtering example: allowlist tools exposed to the MCP client

Tool Filtering example: scope-based tool exposure

OPA Policy Output Schema

Test policy enforcement

Troubleshooting

Related Pages