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.

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

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.

Policy model overview screen in Maverics Console showing access control configuration options

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

Policy definition screen in Maverics Console showing role and attribute condition builders

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 maverics.authz
                default allow = true

                # Deny tokens for users without verified email
                allow = false {
                  not input.session.email_verified
                }

OPA token minting policies must define an allow rule. The Orchestrator denies token issuance if allow is false.

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.

OPA Authorization (AI Identity Gateway)

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 OPA policies

Console UI
Configuration

OPA policy configuration screen in Maverics Console

Inline OPA policy:

maverics.yaml

authorization:
  inbound:
    type: opa
    opa:
      name: my-auth-policy
      rego: |
        package maverics.authz

        default allow = false

        allow {
          input.session.roles[_] == "admin"
        }

        allow {
          input.request.method == "GET"
          input.session.department == "engineering"
        }

File-based OPA policy:

maverics.yaml

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

Available OPA input fields:

Input Path	Description
`input.source`	Request source information
`input.request`	HTTP request details (method, path, headers)
`input.session`	User session attributes
`input.oauth`	OAuth token claims
`input.mcp`	MCP-specific context (tool name, arguments)

OPA policies must define an allow rule that evaluates to true or false. The Orchestrator denies the request if allow is false.

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

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

Apps and Routes 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

Operations

Security

Authentication vs. Authorization

Prerequisites

Configure Policies

Choose your authorization approach

HTTP Proxy

OIDC and SAML Provider

OPA Authorization (AI Identity Gateway)

Test policy enforcement

Troubleshooting

Security Overview

Authorization Reference

Apps and Routes Reference

Authentication Guides

Service Extensions

Compliance and Audit

Getting Started

Authentication

AI Identity

Operations

Security

​Authentication vs. Authorization

​Prerequisites

​Configure Policies

​Choose your authorization approach

​HTTP Proxy

​OIDC and SAML Provider

​OPA Authorization (AI Identity Gateway)

​Test policy enforcement

​Troubleshooting

​Related Pages

Security Overview

Authorization Reference

Apps and Routes Reference

Authentication Guides

Service Extensions

Compliance and Audit

Authentication vs. Authorization

Prerequisites

Configure Policies

Choose your authorization approach

HTTP Proxy

OIDC and SAML Provider

OPA Authorization (AI Identity Gateway)

Test policy enforcement

Troubleshooting

Related Pages