Custom audiences (services)

This page describes how to use custom audiences for authorization. Set custom audiences on your Cloud Run services that do not allow public (unauthenticated) access and are receiving requests via a custom domain.

Understanding custom audiences

Cloud Run provides an Invoker (roles/run.invoker) role to support access control with IAM. IAM access control makes use of Google-signed ID tokens, which are packaged as JSON Web Tokens (JWTs). The contents of these tokens conform to an OIDC standard.

An audience field is encoded in the token to specify the intended target that can use the token. This limits the risk of a replay attack, where an intercepted token intended for use with one service is replayed against a different service.

By convention, the audience is the full URL of the target service. By default in Cloud Run, this is the Google-generated URL for a service ending in run.app.

However there are several scenarios where a Cloud Run service might sit behind a URL other than the default generated URL:

A custom domain is used to reach a service where the client is unaware of the Google-generated URL.
Multiple services are deployed behind a load-balancer where a client is unable to anticipate which regional service is reached by a request. Note that Google-generated URLs for services are region specific even if the service name is the same.

In these scenarios, you need to configure a service to accept custom audience values that allow additional targets known by a client. The default Google-generated URL will always remain an accepted audience value.

Set and update custom audiences

Setting custom audiences for Cloud Run is at the service level and applies to all serving revisions, similar to IAM authorization membership.

You can set multiple custom audiences so long as JSON encoding of the audiences as a string list does not exceed 32768 bytes.

Any configuration change leads to the creation of a new revision. Subsequent revisions will also automatically get this configuration setting unless you make explicit updates to change it.

Command line

You can set custom audiences on a service using the following command:

gcloud beta run services update SERVICE --add-custom-audiences=AUDIENCE

Replace

SERVICE with the name of your Cloud Run service
AUDIENCE with a string for the custom audience you want to support, for example example.com or aud1

You can remove all custom audiences from a service using the following command:

gcloud beta run services update SERVICE --clear-custom-audiences

YAML

You can download and view existing service configurations using the gcloud run services describe --format export command, which yields cleaned results in YAML format. You can then modify the fields described below and upload the modified YAML using the gcloud run services replace command. Make sure you only modify fields as documented.

To view and download the configuration:

gcloud run services describe SERVICE --format export > service.yaml

Set the run.googleapis.com/custom-audiences annotation on the Service metadata (not on the template metadata):
```
apiVersion: serving.knative.dev/v1
kind: Service
metadata:
  name: SERVICE
  annotations:
    run.googleapis.com/custom-audiences: '["AUDIENCE","AUDIENCE2"]'
    run.googleapis.com/launch-stage: BETA
spec:
  template:
    ...
```
Replace
- SERVICE with the name of your Cloud Run service
- AUDIENCE and AUDIENCE2 with strings for the custom audiences you want to support, for example example.com or aud1
Note that the value of the attribute is a quoted JSON array of strings, requiring the use of both double and single quotes.
Replace the service with its new configuration using the following command:
```
gcloud run services replace service.yaml
```

Verifying custom audiences

Get an ID token for a service account which has IAM permission to invoke the service. Note the use of the custom audience AUDIENCE.
```
export TOKEN=$(gcloud auth print-identity-token --impersonate-service-account SERVICE_ACCOUNT_EMAIL --audiences='AUDIENCE')
```
Replace:
- SERVICE_ACCOUNT_EMAIL with the email of the service account. It ends with .iam.gserviceaccount.com.
- AUDIENCE with the custom audience that you have set on the service.
Call the endpoint of the service with that ID token
```
curl -H "Authorization: Bearer ${TOKEN}" ENDPOINT
```
Replace ENDPOINT with the endpoint to reach your service, for example its custom domain or .run.app URL.
Confirm that the request is authorized and you see the expected response of your service.