Zuplo

This policy allows you to delegate authentication and authorization to your gateway without writing any code on your origin service by adding a GCP Issued ID Token to outgoing header allowing the service to be secured with GCP IAM. This is a useful means of securing your origin server so that only your Zuplo gateway can make requests against it.

This policy works with GCP Identity Aware Proxy or services like Cloud Run that natively support IAM authorization.

We recommend reading the serviceAccountJson from environment variables (so it is not checked in to source control) using the $env(ENV_VAR) syntax.

For information on how Google's service based auth works see Authenticating for invocation

Configuration#

{
  "name": "my-upstream-gcp-service-auth-inbound-policy",
  "policyType": "upstream-gcp-service-auth-inbound",
  "handler": {
    "export": "UpstreamGcpServiceAuthInboundPolicy",
    "module": "$import(@zuplo/runtime)",
    "options": {
      "audience": "https://my-service-a2ev-uc.a.run.app",
      "expirationOffsetSeconds": 300,
      "serviceAccountJson": "$env(SERVICE_ACCOUNT_JSON)",
      "tokenRetries": 3
    }
  }
}

Options#

name the name of your policy instance. This is used as a reference in your routes.
policyType the identifier of the policy. This is used by the Zuplo UI. Value should be upstream-gcp-service-auth-inbound.
handler/export The name of the exported type. Value should be UpstreamGcpServiceAuthInboundPolicy.
handler/module the module containing the policy. Value should be $import(@zuplo/runtime).
handler/options The options for this policy:
- audience
  The audience for the service to be called. This is typically the URL of your service endpoint like 'https://my-service-a2ev-uc.a.run.app'
- serviceAccountJson
  The Google Service Account key in JSON format. Note you can load this from environment variables using the $env(ENV_VAR) syntax.
- tokenRetries
  The number of times to retry fetching the token in the event of a failure.
- expirationOffsetSeconds
  The number of seconds less than the token expiration to cache the token.
- useMemoryCacheOnly
  This is an advanced option that should only be used if you do not want to persist information in ZoneCache.

This policy requires a Google Service Account and key that will be used to identify the Zuplo API Gateway. Once this policy is configured you will need to configure your GCP backend to only accept authenticated requests.

Create the GCP Service Account

The first thing you will need to do to use this policy is create a service account. You should create a unique service account for your Zuplo Gateway (i.e. zuplo-gateway).

Give the account permission to call any services you want to proxy with Zuplo.

Next, you will need to create the Service Account key (using the JSON format). The json file will download.

Next, in your Zuplo project, set the SERVICE_ACCOUNT_JSON environment variable as a secret with the value of the downloaded JSON document.

Caution

The value of the private key is a JSON file. Before you save the file to Zuplo's environment variables, you must remove all line breaks and all instances of the \n escape character. The JSON file should be a single line.

Configure the Policy

When using this policy, you need to set the audience to the appropriate value depending on the service you are using.

For backend's secured with Identity Aware Proxy, the value for audience should be the Client ID of your OAuth application.

For backend's using Cloud Run IAM , the value for audience should be the full URL of the Cloud Run instance.

Upstream GCP Service Auth

Configuration#

Options#

Create the GCP Service Account

Configure the Policy

Was this article helpful?