External Authorization Policy

Policy name

External Authorization

Summary

Authenticates requests with an external gRPC or HTTP authorization service

Category

Security

First Omni Gateway version available

v1.6.0

Release Notes

External Authorization Policy

Returned Status Codes

403 - Forbidden, invalid client application credentials

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.

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. Not all External Authorization filter parameters are available to the External Authorization policy. To find what parameters are configurable, see Configuring Policy Parameters.

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.

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
Managed Omni Gateway and Omni Gateway 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:

- 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

Parameter Required or Optional Default Value Description

Parameter	Required or Optional	Default Value	Description
`uri`	Required	N/A	External authorization service URI. With a gRPC type server, define the URI by using this format: `h2://<ext.authz.com>:<port>`.
`serverType`	Required	`grpc`	Type of external server. Supported values are `grpc` and `http`.
`serverApiVersion`	Optional	`v3`	Transport protocol API version. Supported values are `v3` and `v2`.
`includePeerCertificate`	Optional	`false`	If `true`, includes peer certificates in the authorization server request. Supported values are `true` and `false`.
`serviceRequestHeadersToAdd`	Optional	N/A	Defines custom headers and their value to inject into the authorization service request. This parameter is available for `HTTP` type serves.
`serviceRequestHeadersToAdd.key`	Optional	N/A	Name of the new header to add.
`serviceRequestHeadersToAdd.value`	Optional	N/A	Value of the new header to add.
`serviceResponseUpstreamHeaders`	Optional	N/A	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 `HTTP` type serves.
`serviceResponseUpstreamHeadersToAppend`	Optional	N/A	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 `HTTP` type serves.
`serviceResponseClientHeaders`	Optional	N/A	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 `HTTP` type serves.
`serviceResponseClientHeadersOnSuccess`	Optional	N/A	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 `HTTP` type serves.
`pathPrefix`	Optional	N/A	Sets a prefix to the value of the `Path` authorization request header if present.
`requestTimeout`	Optional	`5000`	Maximum time in milliseconds the policy waits for a response from the authentication service.
`allowedHeaders`	Optional	N/A	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.

uri

Required

N/A

External authorization service URI. With a gRPC type server, define the URI by using this format: h2://<ext.authz.com>:<port>.

serverType

Required

grpc

Type of external server. Supported values are grpc and http.

serverApiVersion

Optional

v3

Transport protocol API version. Supported values are v3 and v2.

includePeerCertificate

Optional

false

If true, includes peer certificates in the authorization server request. Supported values are true and false.

serviceRequestHeadersToAdd

Optional

N/A

Defines custom headers and their value to inject into the authorization service request. This parameter is available for HTTP type serves.

serviceRequestHeadersToAdd.key

Optional

N/A

Name of the new header to add.

serviceRequestHeadersToAdd.value

Optional

N/A

Value of the new header to add.

serviceResponseUpstreamHeaders

Optional

N/A

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 HTTP type serves.

serviceResponseUpstreamHeadersToAppend

Optional

N/A

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 HTTP type serves.

serviceResponseClientHeaders

Optional

N/A

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 HTTP type serves.

serviceResponseClientHeadersOnSuccess

Optional

N/A

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 HTTP type serves.

pathPrefix

Optional

N/A

Sets a prefix to the value of the Path authorization request header if present.

requestTimeout

Optional

5000

Maximum time in milliseconds the policy waits for a response from the authentication service.

allowedHeaders

Optional

N/A

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.

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:

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

Parameter Description

Parameter	Description
External authorization service URI	External authorization service URI. With a gRPC type server, define the URI as `\h2://<ext.authz.com>:<port>`.
External authorization server type	Type of external server.
Server API version	Transport protocol API version.
Include peer certificates in the authorization server request	Includes peer certificates in the authorization server request.
Path prefix	Sets a prefix to the value of the `Path` authorization request header if present.
Request timeout	Maximum time in milliseconds the policy waits for a response from the authentication service. By default, the request timeout is 5000 milliseconds.
Allowed headers	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.

External authorization service URI

External authorization service URI. With a gRPC type server, define the URI as \h2://<ext.authz.com>:<port>.

External authorization server type

Type of external server.

Server API version

Transport protocol API version.

Include peer certificates in the authorization server request

Includes peer certificates in the authorization server request.

Path prefix

Sets a prefix to the value of the Path authorization request header if present.

Request timeout

Maximum time in milliseconds the policy waits for a response from the authentication service. By default, the request timeout is 5000 milliseconds.

Allowed headers

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.

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

The client makes an HTTP request to the API instance exposed by Omni Gateway.
Omni Gateway forwards the request consisting of the client’s request and headers to the authorization service.
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.
Omni Gateway appends any necessary headers and returns the response as normal.