---
layout: docs
page_title: Delegate authorization to Apigee
description: Learn how to use the `ext-authz` Envoy extension to delegate data plane authorization requests to Apigee. 
---

# Delegate authorization to Apigee

This topic describes how to use the external authorization Envoy extension to delegate data plane authorization requests to Apigee.

For more detailed guidance, refer to the [`learn-consul-apigee-external-authz` repository](https://github.com/hashicorp-education/learn-consul-apigee-external-authz) on GitHub.

## Workflow

Complete the following steps to use the external authorization extension with Apigee:

1. Deploy the Apigee Adapter for Envoy and register the service in Consul.
1. Configure the `EnvoyExtensions` block in a service defaults or proxy defaults configuration entry.
1. Apply the configuration entry.

## Deploy the Apigee Adapter for Envoy

The [Apigee Adapter for Envoy](https://cloud.google.com/apigee/docs/api-platform/envoy-adapter/v2.0.x/concepts) is an Apigee-managed API gateway that uses Envoy to proxy API traffic.

To download and install Apigee Adapter for Envoy, refer to the [getting started documentation](https://cloud.google.com/apigee/docs/api-platform/envoy-adapter/v2.0.x/getting-started) or follow along with the [`learn-consul-apigee-external-authz` GitHub repository](https://github.com/hashicorp-education/learn-consul-apigee-external-authz).

After you deploy the service in your desired runtime, create a service defaults configuration entry for the service's gRPC protocol.

<CodeTabs tabs={[ "HCL", "JSON", "YAML" ]}>
<CodeBlockConfig filename="apigee-remote-service-envoy.hcl">

```hcl
Kind = "service-defaults"
Name = "apigee-remote-service-envoy"
Protocol = "grpc"
```

</CodeBlockConfig>
<CodeBlockConfig filename="apigee-remote-service-envoy.json">

```json
{
  "kind": "service-defaults",
  "name": "apigee-remote-service-envoy",
  "protocol": "grpc"
}
```

</CodeBlockConfig>
<CodeBlockConfig filename="apigee-remote-service-envoy.yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: apigee-remote-service-envoy
  namespace: apigee
spec:
  protocol: grpc
```

</CodeBlockConfig>
</CodeTabs>

## Configure the `EnvoyExtensions`

Add Envoy extension configurations to a proxy defaults or service defaults configuration entry. Place the extension configuration in an `EnvoyExtensions` block in the configuration entry.

- When you configure Envoy extensions on proxy defaults, they apply to every service.
- When you configure Envoy extensions on service defaults, they apply to all instances of a service with that name.

<Warning>
  Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring `EnvoyExtensions` in service defaults configuration entries in most cases.
</Warning>

Consul applies Envoy extensions configured in proxy defaults before it applies extensions in service defaults. As a result, the Envoy extension configuration in service defaults may override configurations in proxy defaults.

The following example configures the default behavior for all services named `api` so that the Envoy proxies running as sidecars for those service instances target the apigee-remote-service-envoy service for gRPC authorization requests:

<CodeTabs tabs={[ "HCL", "JSON", "YAML" ]}>
<CodeBlockConfig filename="api-auth-service-defaults.hcl">

```hcl
Kind = "service-defaults"
Name = "api"
EnvoyExtensions = [
  {
    Name = "builtin/ext-authz"
    Arguments = {
      ProxyType = "connect-proxy"
      Config = {
        GrpcService = {
          Target = {
            Service = {
              Name = "apigee-remote-service-envoy"
            }
          }
        }
      }
    }
  }
]
```
</CodeBlockConfig>
<CodeBlockConfig filename="api-auth-service-defaults.json">

```json
{
  "Kind": "service-defaults",
  "Name": "api",
  "EnvoyExtensions": [{
    "Name": "builtin/ext-authz",
    "Arguments": {
      "ProxyType": "connect-proxy",
      "Config": {
        "GrpcService": {
          "Target": {
            "Service": {
              "Name": "apigee-remote-service-envoy"
              }
            }
          }
        }
      }
    }
  ]
}
```

</CodeBlockConfig>
<CodeBlockConfig filename="api-auth-service-defaults.yaml">

```yaml
apiVersion: consul.hashicorp.com/v1alpha1
kind: ServiceDefaults
metadata:
  name: api
  namespace: default
spec:
  envoyExtensions:
  - name: builtin/ext-authz
    arguments:
      proxyType: connect-proxy
      config:
        grpcService:
          target:
            service:
              name: apigee-remote-service-envoy
              namespace: apigee
```
</CodeBlockConfig>
</CodeTabs>

Refer to the [external authorization extension configuration reference](/consul/docs/reference/proxy/extensions/ext-authz) for details on how to configure the extension. 

Refer to the [proxy defaults configuration entry reference](/consul/docs/reference/config-entry/proxy-defaults) and [service defaults configuration entry reference](/consul/docs/reference/config-entry/service-defaults) for details on how to define the configuration entries. 

<Warning>
  Adding Envoy extensions default proxy configurations may have unintended consequences. We recommend configuring `EnvoyExtensions` in service defaults configuration entries in most cases.
</Warning>

## Apply the configuration entry

On the CLI, you can use the `consul config write` command and specify the names of the configuration entries to apply them to Consul. For Kubernetes-orchestrated networks, use the `kubectl apply` command to update the relevant CRD.

<CodeTabs tabs={[ "HCL", "JSON", "YAML" ]}>

```shell-session
$ consul config write apigee-remote-service-envoy.hcl
$ consul config write api-auth-service-defaults.hcl
```

```shell-session
$ consul config write apigee-remote-service-envoy.json
$ consul config write api-auth-service-defaults.json
```

```shell-session
$ kubectl apply -f apigee-remote-service-envoy.yaml
$ kubectl apply -f api-auth-service-defaults.yaml
```

</CodeTabs>
