salesforce Dreamforce On-Demand
Contact Us 1-800-596-4880
  1. Homepage
  2. Flex Gateway (1.6)
  3. Included Policies Directory

  4. External Authorization

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 of HTTP authorization service to determine if the client HTTP request is authorized to access the upstream service. In 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, to the authorization service, use the Allowed Headers parameter to configure which headers from the client HTTP requests to send to the authorization service.

When using a gRPC external authorization service, the External Authorization policy can also modify the client HTTP requests header with additional information returned from the authorization service. 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 already present in the client HTTP request. 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. When using the policy with an HTTP external authorization service, the policy cannot modify the client HTTP request.

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 should be present when the request is sent 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`
    includePeerCertificate: <boolean> // REQUIRED, default `false`
    allowedHeaders: <array> // OPTIONAL
Parameter Required or Optional Default Value Description

uri

Required

NA

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.

serverVersion

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.

allowedHeaders

Optional

NA

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

Flex 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 \h2://<ext.authz.com>:<port>.

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.

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 when the External Authorization policy is applied:

80%

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

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

  3. The authorization services sends a response back to Flex Gateway. The response indicates whether the client HTTP request is authorized and also indicates which headers to append or to edit:

    • If the request isn’t authorized, Flex Gateway returns a 403 forbidden 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.

  4. Flex Gateway returns the response as normal.

Envoy Policy Limitations

Policies that extend filters native to Envoy have certain monitoring limitations when running in connected mode.

Policy Violation Metrics

Envoy filter policies do not support the Policy Violations metric in either the API instance Key Metrics or Anypoint Monitoring. However, Envoy filter policies do support the Response Code metric.

Applying an Envoy filter policy does not affect the Policy Violations metrics for other policies applied to the API instance. Flex Gateway reports the Policy Violations metrics for non-Envoy filter policies as normal, but these metrics are incomplete as they do not include Envoy filter policy violations.

To learn more about Flex Gateway Metrics, refer to Viewing Key Metrics for Flex Gateway APIs.

API Alerts

Envoy filter policies do not support policy violation API alerts. To monitor an Envoy filter policy with an API alert, add an alert that monitors response codes and specify the response error code of your policy.

To learn more about adding alerts, refer to Using Flex Gateway API Alerts.