External Authorization Policy
Policy name |
External Authorization |
Summary |
Authenticates requests with an external gRPC or HTTP authorization service |
Category |
Security |
First Flex Gateway version available |
v1.6.0 |
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, Flex Gateway allows the request to pass to the upstream service. For unauthorized accesses, Flex 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.
|
Flex Gateway sends headers to the authorization service encoded in bytes. To send headers encoded in utf8, set the environment variable |
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 Flex Gateway to append to the client HTTP request.
For gRPC authorization servers, if the authorization service returns headers with the authorization response, Flex 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 Flex Gateway is running in:
Flex Gateway Local Mode
In Local Mode, you apply the External Authorization policy to your API instance via YAML 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"
serverVersion: <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
requestTimeout: <number> // REQUIRED, default `5000`
includePeerCertificate: <boolean> // REQUIRED, default `false`
allowedHeaders: <string-array> // OPTIONAL| Parameter | Required or Optional | Default Value | Description |
|---|---|---|---|
|
Required |
N/A |
External authorization service URI. With a gRPC type server, define the URI by using this format: |
|
Required |
|
Type of external server. Supported values are |
|
Optional |
|
Transport protocol API version. Supported values are |
|
Optional |
|
If |
|
Optional |
N/A |
Defines custom headers and their value to inject into the authorization service request. This parameter is available for |
|
Optional |
N/A |
Name of the new header to add. |
|
Optional |
N/A |
Value of the new header to add. |
|
Optional |
N/A |
Specifies the headers from the authorization response to add to the client request to the upstream service. Flex Gateway overwrites coexisting headers. This parameter is available for |
|
Optional |
N/A |
Specifies the headers from the authorization response to add to the client request to the upstream service. Flex Gateway appends coexisting headers. This parameter is available for |
|
Optional |
N/A |
Specifies the headers from the authorization response to add to the client response returned from the upstream service. Flex Gateway overwrites existing headers. This parameter is available for |
|
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. Flex Gateway overwrites existing headers. This parameter is available for |
|
Optional |
|
Maximum time in milliseconds the policy waits for a response from the authentication service. |
|
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-tokenFlex Gateway Connected Mode
When you apply the policy to your API instance from the UI, the following parameters are displayed:
| Parameter | Description |
|---|---|
External authorization service URI |
External authorization service URI. With a gRPC type server, define the URI as |
External authorization server type |
Type of external server. |
Transport protocol API version |
Transport protocol API version. |
Include peer certificates in the authorization server request |
Includes peer certificates in the authorization server request. |
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:
-
The client makes an HTTP request to the API instance exposed by Flex Gateway.
-
Flex 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 Flex Gateway:
-
If the request isn’t authorized, Flex Gateway appends any necessary headers and returns a
403forbidden access code to the client. -
If the request is authorized, Flex Gateway appends the header data to the client request, if necessary, and allows the request to pass to the upstream service.
-
-
Flex Gateway appends any necessary headers and returns the response as normal.