Contact Us 1-800-596-4880
  1. Homepage
  2. Omni Gateway (1.14)
  3. Securing Omni Gateway Instances with Policies
  4. Inbound Policies Directory

  5. GraphQL Access Control

GraphQL Access Control Policy

Policy Name

GraphQL Access Control

Summary

Authorizes incoming GraphQL requests by evaluating Cedar rules

Category

Security

First Omni Gateway version available

v1.14.0

Release Notes

GraphQL Access Control

Returned status codes

403 Forbidden — No rule authorizes the request. The response body is a JSON object with an error message such as GraphQL request denied by access control policy.

Summary

The GraphQL Access Control policy authorizes each incoming GraphQL request against a set of Cedar rules that you define. Cedar is an open-source policy language that expresses authorization as permit and forbid statements. Omni Gateway allows a request only when at least one permit rule matches it and no forbid rule matches.

Use this policy to enforce fine-grained, attribute-based authorization on GraphQL traffic. For example, you can restrict mutations to privileged clients, allow specific named operations, or gate access by request header, SLA tier, or source IP address.

To make identity-based decisions, apply an upstream authentication policy, such as Basic Authentication, Client ID Enforcement, JWT Validation, OAuth 2.0 Token Introspection, or OpenID Connect, before this policy. The authentication policy populates the principal that the rules evaluate. When no authentication policy runs, Omni Gateway evaluates the request against the Client::"None" principal. For the attributes that each authentication policy provides, see Attributes Available to Cedar Rules.

After Omni Gateway extracts the GraphQL operation text, the policy evaluates your rules against the request. The policy skips persisted queries and passes them to the upstream service without authorization checks, because Omni Gateway doesn’t inspect their operation text. Non-GraphQL requests also pass through.

Configuring Policy Parameters

Omni Gateway Local Mode

When you apply the policy via declarative configuration files, Refer to the following policy definition and table of parameters:

- policyRef:
    name: graphql-access-control-flex
  config:
    rules: <array> // REQUIRED, list of Cedar policy statements; can't be empty
Parameter Required Default Value Description

rules

Yes

None

A list of Cedar policy statements that authorize requests. Each statement must be a valid Cedar permit or forbid rule that ends with a semicolon. The list can’t be empty.

Managed Omni Gateway and Omni Gateway Connected Mode

When you apply the policy from the UI, the following parameters are displayed:

Field Description Default Value Required

Rules

The list of Cedar policy statements that authorize requests. Add one entry per permit or forbid rule. Each rule must be valid Cedar and end with a semicolon.

None

Yes

Attributes Available to Cedar Rules

Cedar rules authorize a request by matching against attributes of the principal, which is the authenticated client, and the request context. Use these attributes in the when clause of a rule to make fine-grained decisions.

Cedar rules can match requests against these context attributes:

Attribute Description

context.headers["<name>"]

The value of a request header. Use bracket notation to access header names that contain characters such as dashes, for example, context.headers["x-internal"].

context.graphqlQuery

The raw GraphQL operation text.

context.operationName

The name of the resolved operation. If the request provides an operationName, Omni Gateway resolves that operation. Otherwise, Omni Gateway resolves the first operation in the document. Empty when the operation is anonymous.

context.operationType

The type of the resolved operation: query, mutation, or subscription. Shorthand documents resolve to query.

context.rootField

The name of the first top-level field in the resolved operation.

context.ipAddress

The source IP address of the request, when available.

Cedar rules can also match requests against these principal attributes. You must apply an authentication policy before the GraphQL Access Control policy to populate these values. To learn what policies update which attributes, see Authentication Policies Principal Attributes.

Attribute Description

principal.principal

The authenticated principal identifier, such as the Basic Authentication username or the raw token.

principal.client_id

The client ID resolved by the upstream authentication policy, when available.

principal.client_name

The client application name resolved by the upstream authentication policy, when available.

principal.properties.<name>

Additional properties published by the upstream authentication policy. For example, JWT Validation exposes principal.properties.claims.<claim>, and OAuth 2.0 Token Introspection exposes principal.properties.scope.

principal.properties.slaId

The SLA tier ID of the client, when an upstream policy publishes it.

principal.properties.slaName

The human-readable SLA tier name that corresponds to slaId, resolved from the API instance metadata.

When no authentication policy runs, Omni Gateway evaluates the request against the Client::"None" principal, and these principal attributes are empty.

Authentication Policies Principal Attributes

Apply an authentication policy before this policy to populate the principal attributes that your Cedar rules evaluate.

Included Authentication Policies

The authentication policy you apply affects the available Cedar principal bindings:

Custom Authentication Policies

For custom authentication policies, the custom policy must authenticate by using the Authentication injectable. To configure the Authentication injectable, see Accessing Request Authentication Information.

For the Rust AuthenticationData structure:

pub struct AuthenticationData {
    pub principal: Option<String>,
    pub client_id: Option<String>,
    pub client_name: Option<String>,
    pub properties: Value,
}

The AuthenticationData parameters map to these Cedar bindings:

  • principal: principal.principal

  • client_name: principal.client_name

  • properties: principal.properties.*

Configuration Examples

These examples are valid whether you configure the policy in a Local Mode resource file or through the Omni Gateway UI.

This example permits queries from any client but restricts mutations to clients that authenticate as admin:

- policyRef:
    name: graphql-access-control-flex
  config:
    rules:
      - permit(principal, action, resource) when { context.operationType == "query" };
      - permit(principal, action, resource) when { principal.principal == "admin" };

This example permits requests only from internal callers that a request header identifies, and blocks introspection-style queries against the __schema root field:

- policyRef:
    name: graphql-access-control-flex
  config:
    rules:
      - permit(principal, action, resource) when { context.headers["x-internal"] == "true" };
      - forbid(principal, action, resource) when { context.rootField == "__schema" };

See Also