---
schema_version: "1"
id: cfe34ef76135124601b76e4bb9f0940a7e8e097000b4a12e93eb860eb265dd71
title: External Authorization Policy
collection: mulesoft
version: current
locale: en-us
portal_url: https://docs.salesforce.com/mulesoft/current/en-us/gateway/1.13/policies-included-external-authorization.md
canonical_url: https://docs.mulesoft.com/gateway/1.13/policies-included-external-authorization
source_site: docs.mulesoft.com
content_type: documentation
content_hash: 3d534018d464b9eb61b5ff0792ed99da1bae00bb09c57884ee0d3ae15daa77ac
description: MuleSoft Documentation Site
release: "1.13"
latest: false
---
---
product: Omni Gateway
version: 1.13
keywords: external authorization, authorization, flex gateway, gateway, policy
---

# External Authorization Policy

> For the full documentation index, see: https://docs.mulesoft.com/llms.txt

<table><colgroup><col> <col></colgroup><tbody><tr><td><p><strong>Policy name</strong></p></td><td><p>External Authorization</p></td></tr><tr><td><p><strong>Summary</strong></p></td><td><p>Authenticates requests with an external gRPC or HTTP authorization service</p></td></tr><tr><td><p><strong>Category</strong></p></td><td><p>Security</p></td></tr><tr><td><p><strong>First Omni Gateway version available</strong></p></td><td><p>v1.6.0</p></td></tr><tr><td><p><strong>Release Notes</strong></p></td><td><p><a href="https://docs.mulesoft.com/release-notes/gateway/policies/external-authorization-release-notes">External Authorization Policy</a></p></td></tr><tr><td><p><strong>Returned Status Codes</strong></p></td><td><p>403 - Forbidden, invalid client application credentials</p></td></tr></tbody></table>

## Summary

The External Authorization policy forwards incoming client HTTP requests to an external gRPC or HTTP
authorization service to determine if the client HTTP request is authorized to access the upstream
service. If the request is authorized, Omni Gateway allows the request to pass to the upstream
service. For unauthorized accesses, Omni Gateway returns a `403` forbidden request error.

To forward request headers, such as an authorization token header, from the client HTTP request to
the authorization service, configure the **Allowed Headers** parameter. Additionally, for HTTP
authorization servers, use the **Headers to add** parameter to inject new headers into the
authorization request.

> [!IMPORTANT] Omni Gateway sends headers to the authorization service encoded in bytes. To send
> headers encoded in utf8, set the environment variable `FLEX_HEADER_RAW_VALUE_ENABLE=false`.

The External Authorization policy can also modify the client HTTP request and response headers with
additional information returned from the authorization service. For example, if an authorized user
makes a request with an access token header that corresponds to a username, the authorization
service can return a `username` header for Omni Gateway to append to the client HTTP request.

For gRPC authorization servers, if the authorization service returns headers with the authorization
response, Omni Gateway either appends these headers to the client HTTP request or overwrites the
header if it is present in the client request.

For HTTP authorization servers, you can configure what headers to append, overwrite, or ignore.
Policies with an HTTP server configured can also modify the client response returned from the
upstream service.

The External Authorization policy is an extension of the External Authorization filter native to
Envoy. To learn more about the External Authorization filter, see
[External Authorization Filter](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_filters/ext_authz_filter).
Not all External Authorization filter parameters are available to the External Authorization policy.
To find what parameters are configurable, see
[Configuring Policy Parameters](#configuring-policy-parameters).

> [!NOTE] If other policies modify the incoming HTTP request, ensure that you order the policies
> depending on if these modification must be present before sending the request to the authorization
> service. For more information about ordering policies, see [Ordering Policies](https://docs.mulesoft.com/gateway/1.13/policies-reorder).

## Configuring Policy Parameters

To configure your policy parameters, see the following parameter references for the mode your Omni
Gateway is running in:

- [Omni Gateway Local Mode](#local-mode)

- [Managed Omni Gateway and Omni Gateway Connected Mode](#connected-mode)

### Omni Gateway Local Mode

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

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: <string> // REQUIRED
    serverType: <string> // REQUIRED, default "grpc"
    serverApiVersion: <string> // REQUIRED, default `v3`
    serviceRequestHeadersToAdd: <object-array> // OPTIONAL
      - key: <string>
        value: <string>
    serviceResponseUpstreamHeaders: <string-array> // OPTIONAL
    serviceResponseUpstreamHeadersToAppend: <string-array> // OPTIONAL
    serviceResponseClientHeaders: <string-array> // OPTIONAL
    serviceResponseClientHeadersOnSuccess: <string-array> // OPTIONAL
    pathPrefix: <string> // OPTIONAL
    requestTimeout: <number> // REQUIRED, default `5000`
    includePeerCertificate: <boolean> // REQUIRED, default `false`
    allowedHeaders: <string-array> // OPTIONAL
```

<table><colgroup><col> <col> <col> <col></colgroup><thead><tr><th>Parameter</th><th>Required or Optional</th><th>Default Value</th><th>Description</th></tr></thead><tbody><tr><td><div><div><p><code>uri</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI by using this format: <code>h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverType</code></p></div></div></td><td><div><div><p>Required</p></div></div></td><td><div><div><p><code>grpc</code></p></div></div></td><td><div><div><p>Type of external server. Supported values are <code>grpc</code> and <code>http</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serverApiVersion</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>v3</code></p></div></div></td><td><div><div><p>Transport protocol API version. Supported values are <code>v3</code> and <code>v2</code>.</p></div></div></td></tr><tr><td><div><div><p><code>includePeerCertificate</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>false</code></p></div></div></td><td><div><div><p>If <code>true</code>, includes peer certificates in the authorization server request. Supported values are <code>true</code> and <code>false</code>.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Defines custom headers and their value to inject into the authorization service request. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.key</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Name of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceRequestHeadersToAdd.value</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Value of the new header to add.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Omni Gateway overwrites coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseUpstreamHeadersToAppend</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client request to the upstream service. Omni Gateway appends coexisting headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service. Omni Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>serviceResponseClientHeadersOnSuccess</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the authorization response to add to the client response returned from the upstream service if the request is successfully authorized. Omni Gateway overwrites existing headers. This parameter is available for <code>HTTP</code> type serves.</p></div></div></td></tr><tr><td><div><div><p><code>pathPrefix</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p><code>requestTimeout</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p><code>5000</code></p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service.</p></div></div></td></tr><tr><td><div><div><p><code>allowedHeaders</code></p></div></div></td><td><div><div><p>Optional</p></div></div></td><td><div><div><p>N/A</p></div></div></td><td><div><div><p>Specifies the headers from the client HTTP request to propagate to authorization request. By default, requests sent to gRPC servers include all client headers. Requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

> [!NOTE] Leaving a required value blank configures the parameter as the default value. No value is
> configured for optional values left blank.

### Resource Configuration Example

In the following configuration, a gRPC authorization service receives a request that includes the
peer certificates and authorization token header:

```yaml
- policyRef:
    name: native-ext-authz-flex
  config:
    uri: h2://ext-authz-grpc-service:9001
    serverType: "grpc"
    includePeerCertificate: "true"
    allowedHeaders:
      - access-token
```

### Managed Omni Gateway and Omni Gateway Connected Mode

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

<table><colgroup><col> <col></colgroup><thead><tr><th><strong>Parameter</strong></th><th><strong>Description</strong></th></tr></thead><tbody><tr><td><div><div><p>External authorization service URI</p></div></div></td><td><div><div><p>External authorization service URI. With a gRPC type server, define the URI as <code>\h2://&lt;ext.authz.com&gt;:&lt;port&gt;</code>.</p></div></div></td></tr><tr><td><div><div><p>External authorization server type</p></div></div></td><td><div><div><p>Type of external server.</p></div></div></td></tr><tr><td><div><div><p>Server API version</p></div></div></td><td><div><div><p>Transport protocol API version.</p></div></div></td></tr><tr><td><div><div><p>Include peer certificates in the authorization server request</p></div></div></td><td><div><div><p>Includes peer certificates in the authorization server request.</p></div></div></td></tr><tr><td><div><div><p>Path prefix</p></div></div></td><td><div><div><p>Sets a prefix to the value of the <code>Path</code> authorization request header if present.</p></div></div></td></tr><tr><td><div><div><p>Request timeout</p></div></div></td><td><div><div><p>Maximum time in milliseconds the policy waits for a response from the authentication service. By default, the request timeout is 5000 milliseconds.</p></div></div></td></tr><tr><td><div><div><p>Allowed headers</p></div></div></td><td><div><div><p>By default, requests sent to gRPC servers include all client headers and requests sent to HTTP servers don’t include any client headers. If you list allowed headers for either server type, requests include only the listed headers.</p></div></div></td></tr></tbody></table>

## How This Policy Works

The following diagram demonstrates the order in which requests and responses flow during the
External Authorization policy execution:

![A sequence diagram that illustrates the interaction between a user, an API gateway, a database, and an API](/mulesoft/current/en-us/gateway/1.13/_images/ext-auth-policy.png)

1.  The client makes an HTTP request to the API instance exposed by Omni Gateway.

2.  Omni Gateway forwards the request consisting of the client’s request and headers to the
    authorization service.

3.  The authorization services sends the authorization response back to Omni Gateway:

    - If the request isn’t authorized, Omni Gateway appends any necessary headers and returns a
      `403` forbidden access code to the client.

    - If the request is authorized, Omni Gateway appends the header data to the client request, if
      necessary, and allows the request to pass to the upstream service.

4.  Omni Gateway appends any necessary headers and returns the response as normal.