> ## Documentation Index
> Fetch the complete documentation index at: https://docs.strata.io/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/guides/authentication/overview) 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](/guides/getting-started/quick-start) first.
* **An identity provider connected** -- Your Orchestrator should be authenticating users against an identity provider. The Quick Start or [SSO guides](/guides/authentication/overview) 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](#http-proxy) 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](#oidc-and-saml-provider) 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)](#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](/reference/orchestrator/service-extensions) for the `authenticateSE` and `searchSE` hooks.

Not sure which mode applies? See [Choosing a Mode](/guides/authentication/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.

**1. Define authentication policy binding**

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

**Console UI**

> [!NOTE]
>
> **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](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

Define policies on your app with authentication connector bindings:

```yaml maverics.yaml theme={null}
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.

**2. 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**

> [!NOTE]
>
> **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 definition screen in Maverics Console showing role and attribute condition builders](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

**Allow all authenticated users** (simplest authorization):

```yaml maverics.yaml theme={null}
policies:
  - location: "/"
    authentication:
      idps: ["azure"]
    authorization:
      allowAll: true
```

**Simple role-based rule:**

```yaml maverics.yaml theme={null}
policies:
  - location: "/admin"
    authentication:
      idps: ["azure"]
    authorization:
      rules:
        - and:
            - contains: ["{{ azure.groups }}", "admin-group"]
```

**Nested and/or rules** for complex access control:

```yaml maverics.yaml theme={null}
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](/reference/orchestrator/authorization) for the complete rule syntax and per-mode comparison.

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

**3. 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](/reference/orchestrator/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](/reference/orchestrator/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.

**1. Configure declarative rules**

**Console UI**

> [!NOTE]
>
> **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.

**Configuration**

**Allow all authenticated users:**

```yaml maverics.yaml theme={null}
apps:
  - name: my-oidc-app
    type: oidc
    authorization:
      allowAll: true
```

**Role-based rule at the app level:**

```yaml maverics.yaml theme={null}
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`.

**2. 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.

```yaml maverics.yaml theme={null}
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](#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.

```json theme={null}
{
  "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.

```rego policy.rego theme={null}
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
}
```

**3. 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](/reference/orchestrator/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`.

**1. Configure MCP app inbound authorization policies**

**Console UI**

> [!NOTE]
>
> **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.

![OPA policy configuration screen in Maverics Console](https://mintcdn.com/strataidentity/yo114yy_clZj7p9v/images/placeholder.svg?fit=max\&auto=format\&n=yo114yy_clZj7p9v\&q=85\&s=ea8d2ec72a69d5a8c7955d78abba6a30)

**Configuration**

**Inline OPA policy:**

```yaml maverics.yaml theme={null}
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:**

```yaml maverics.yaml theme={null}
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](/reference/orchestrator/applications/mcp-proxy#tool-filtering-opa).

For the complete per-mode authorization comparison, see the [Authorization Reference](/reference/orchestrator/authorization#per-mode-authorization-differences).

**2. 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](#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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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.

```rego policy.rego theme={null}
package orchestrator

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

# Decode the bearer token's claims. jwt.parse_bearer strips the "Bearer "
# prefix and returns the payload, or undefined if the header is absent or
# does not carry a JWT -- in which case every rule below fails and the
# default deny applies.
jwt_payload := jwt.parse_bearer(input.request.http.headers.Authorization)

# 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.

```rego connection.rego theme={null}
package orchestrator

default result["allowed"] := false

jwt_payload := jwt.parse_bearer(input.request.http.headers.Authorization)

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.

```rego listing.rego theme={null}
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.

```rego listing.rego theme={null}
package orchestrator

default result["allowed"] := false

jwt_payload := jwt.parse_bearer(input.request.http.headers.Authorization)

# 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"]
}
```

### Rego Built-in Functions

In addition to the standard [OPA built-in functions](https://www.openpolicyagent.org/docs/policy-reference#built-in-functions), the Orchestrator registers its own built-ins. These are available in every OPA policy the Orchestrator evaluates -- OIDC token minting, MCP connection, MCP inbound, and MCP tool filtering.

#### `jwt.parse_bearer`

Decodes the claims from a bearer token in a single call, replacing the `startswith` / `substring` / `io.jwt.decode` sequence that policies would otherwise need to extract a JWT from an `Authorization` header.

```rego theme={null}
jwt.parse_bearer(header_value)
```

| Parameter | Type | Description |
| - | - | - |
| `header_value` | String | The full `Authorization` header value, including the `Bearer ` scheme -- typically `input.request.http.headers.Authorization`. |

Returns an object containing the token's payload claims.

The auth-scheme is matched case-insensitively, per [RFC 6750 section 2.1](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1), so `Bearer`, `bearer`, and `BEARER` are all accepted. The credentials that follow are decoded exactly as sent.

**Usage:**

```rego policy.rego theme={null}
package orchestrator

default result["allowed"] := false

claims := jwt.parse_bearer(input.request.http.headers.Authorization)

result["allowed"] if {
	contains(claims.scope, "tickets:read")
}
```

**Undefined results**

The function returns undefined -- rather than an error -- when it cannot produce claims. This happens when:

* The `Authorization` header is missing or empty.
* The header does not use the `Bearer` auth-scheme (for example, `Basic`).
* The value after the scheme is not a well-formed signed JWT.
* The JWT payload is not a JSON object.

Because an undefined value makes any rule referencing it fail, a policy with a `default result["allowed"] := false` rule denies the request in all of these cases. This is the recommended pattern -- write the default deny and let undefined claims fall through to it.

> [!WARNING]
>
> `jwt.parse_bearer` decodes the token payload **without verifying its signature**, its expiry, or any other claim. It is a parsing helper, not a validation step -- a policy that trusts its output alone will accept a forged token.
>
> Token trust is established elsewhere. Configure `mcpProvider.authorization.oauth` with `servers[].tokenValidation` so the Orchestrator validates the bearer token before the request reaches your policy. That OAuth block is optional -- if it is absent, no token validation happens and a policy reading these claims is trusting unverified input. If you need to verify a signature inside the policy itself, use OPA's `io.jwt.decode_verify` instead.

### 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:

```json theme={null}
{
  "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. |

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

**1. Start the Orchestrator**

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

```bash theme={null}
maverics -config /etc/maverics/maverics.yaml
```

**2. Verify allowed access**

Test with a user who should have access:

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

**3. Verify denied access**

Test with a user who should be denied:

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

> [!TIP]
>
> **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](/reference/orchestrator/identity-fabric)
> for details on claim mapping for your specific provider.

## Related Pages

> **[Security Overview](/guides/security/overview)**
>
> Return to the Security guides hub for TLS, secrets, policies, and compliance

> **[Authorization Reference](/reference/orchestrator/authorization)**
>
> Per-mode authorization differences, enforcement behavior, and OPA policy patterns

> **[Applications Reference](/reference/orchestrator/applications)**
>
> Complete configuration reference for authorization rules, operators, and policy syntax

> **[Authentication Guides](/guides/authentication/overview)**
>
> Configure SSO, SAML federation, and identity provider connections that policies build on

> **[Service Extensions](/reference/orchestrator/service-extensions)**
>
> Custom authorization logic via isAuthorizedSE, handleUnauthorizedSE, and other SE hooks

> **[Compliance and Audit](/guides/security/compliance)**
>
> Log policy decisions and authorization events for compliance reporting