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
oraud1
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 thetemplate
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
oraud1
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.
- SERVICE_ACCOUNT_EMAIL with the email of the service account. It ends with
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.