Authenticate for invocation
To invoke a authenticated Cloud Function, the underlying principal must have the invoker IAM permission:
cloudfunctions.functions.invoke
for 1st gen functions. This is usually through the Cloud Functions Invoker role.run.routes.invoke
for 2nd gen functions. This is usually through the Cloud Run Invoker role. This permission must be assigned on the Cloud Run service resource.
For permission to create, update, or perform other administrative actions on a function, you must have a principal that has an appropriate role. See Using IAM to Authorize Access for more information.
But invoking a function can be a more complex event. Event-driven functions can only be invoked by the event source to which they are subscribed, but HTTP functions can be invoked by different kinds of identities, originating in different places. The invoker might be a developer who is testing the function or another function or service that wishes to use the function. By default, these identities must provide an ID token with the request to authenticate themselves. In addition, the account being used must also have been granted the appropriate permissions.
Unauthenticated access without an ID token is possible, but must be enabled. See Using IAM to Authorize Access for more information.
Authenticating Developer Testing
As a developer, you need access to create, update, and delete functions, and this is granted using the normal (IAM) process.
But as a developer, you might need to invoke your functions for
testing purposes. To invoke a function using curl
or similar tools, note the
following:
Assign a role to your Cloud Functions user account that contains the invoke permission.
cloudfunctions.functions.invoke
for 1st gen functions. This is usually through the Cloud Functions Invoker role. By default, the Cloud Functions Admin and Cloud Functions Developer roles have this permission. See Cloud Functions IAM Roles for the full list of roles and their associated permissions.run.routes.invoke
for 2nd gen functions. This is usually through the Cloud Run Invoker role. This permission must be assigned on the Cloud Run service resource.
If you are working from your local machine, set up command-line access by initializing the Google Cloud CLI.
Provide your request with authentication credentials as a Google-generated ID token stored in an
Authorization
header. For example, get an ID token usinggcloud
by running the following command:curl -H "Authorization: Bearer $(gcloud auth print-identity-token)" \ https://FUNCTION_URL
where FUNCTION_URL is the URL of your function. Retrieve this URL from the Cloud Functions page of the Google Cloud console or by running the
gcloud functions describe
command as shown in the first step of the Google Cloud CLI deployment command example.
You can use tokens created by gcloud
to invoke HTTP functions in any
project as long as your account has the cloudfunctions.functions.invoke
permission on the function being invoked. For development purposes, use
gcloud
-generated ID tokens. However, note that such tokens lack an audience
claim, which makes them susceptible to relay attacks. In production
environments, use ID tokens issued for a service account with the appropriate
audience specified. This approach enhances security by restricting token usage
to the intended service only.
As always, we recommend that you allocate the minimum set of permissions required to develop and use your functions. Make sure that IAM policies on your functions are limited to the minimum number of users and service accounts.
Authenticating function to function calls
When building services that connect multiple functions, it's a good idea to
ensure that each function can only send requests to a specific subset of your
other functions. For example, if you have a login
function, it should be able
to access the user profiles
function, but it probably shouldn't be able to
access the search
function.
To configure the receiving function to accept requests from a specific calling
function, you need to grant the appropriate invoker role to the calling
function's service account on the receiving function. For 1st gen functions, the
invoker role is Cloud Functions Invoker (roles/cloudfunctions.invoker
).
For 2nd gen functions, the invoker role is Cloud Run Invoker
(roles/run.invoker
) and must be granted
on the underlying service.
Cloud Functions (1st gen):
Console
For 1st gen functions, you use the Cloud Functions Invoker:
Go to the Google Cloud console:
Click the checkbox next to the receiving function. (Don't click the function itself.)
Click Permissions at the top of the screen. The Permissions panel opens.
Click Add principal.
In the New principals field, enter the identity of the calling function. This should be a service account email.
Select the role Cloud Functions > Cloud Functions Invoker from the Select a role drop-down menu.
Click Save.
gcloud
Use the gcloud functions add-invoker-policy-binding
command:
gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \ --member='serviceAccount:CALLING_FUNCTION_IDENTITY' \
The add-invoker-policy-binding
command adds an invoker role IAM policy binding that allows the specified member (principal) to invoke the specified function. gcloud will automatically detect the function generation and add the correct Invoker role (cloudfunctions.invoker
for 1st gen and run.invoker
` for 2nd gen).
Replace the following:
RECEIVING_FUNCTION
: The name of the receiving function.CALLING_FUNCTION_IDENTITY
: The calling function identity, a service account email.
Cloud Functions (2nd gen):
Console
For 2nd gen functions, you use the Cloud Run Invoker:
Go to the Google Cloud console:
In the Cloud Run services list, click the checkbox next to the receiving function. (Don't click the function itself.)
The Permissions panel opens.
Click Add principal.
Enter the identity of the calling service. This is usually an email address, by default
PROJECT_NUMBER-compute@developer.gserviceaccount.com
.Note that the project number is distinct from the project ID and project name. You can find your project number on the Google Cloud console Dashboard page.
Select the
Cloud Run Invoker
role from the Select a role drop-down menu.Click Save.
gcloud
Use the gcloud functions add-invoker-policy-binding
command:
gcloud functions add-invoker-policy-binding RECEIVING_FUNCTION \ --member='serviceAccount:CALLING_FUNCTION_IDENTITY'
Replace the following:
RECEIVING_FUNCTION
: The name of the receiving function.CALLING_FUNCTION_IDENTITY
: The calling function identity, a service account email.
Because it will be invoking the receiving function, the calling function must also provide a Google-signed ID token to authenticate. This is a two step process:
Create a Google-signed ID token with the audience field (
aud
) set to the URL of the receiving function.Include the ID token in an
Authorization: Bearer ID_TOKEN
header in the request to the function.
By far the easiest and most reliable way to manage this process is to use the authentication libraries, as shown below, to generate and employ this token.
Generating tokens programmatically
After the following code generates an ID token, it calls your Cloud Function with that token on your behalf. This code works in any environment where the libraries can obtain authentication credentials, including environments that support local Application Default Credentials.
Node.js
Python
Go
Java
Generating tokens manually
If you're invoking a function and for some reason you cannot use the authentication libraries, there are two ways you can get the ID token manually, either using the Compute metadata server or by creating a self-signed JWT and exchanging it for a Google-signed ID token.
Using the metadata server
You can use the Compute metadata server to fetch ID tokens with a specific audience as follows:
curl "http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/identity?audience=AUDIENCE" \
-H "Metadata-Flavor: Google"
Replace AUDIENCE with the URL of the function you are invoking. You can retrieve this URL as described in the Authenticating developer testing section above.
Exchanging a self-signed JWT for a Google-signed ID token
Grant the Cloud Functions Invoker (
roles/cloudfunctions.invoker
) role to the calling function's service account on the receiving function.Create a service account and a key and download the file with the private key (in JSON format) to the host from which the calling function or service makes its requests.
Create a JWT with the header set to
{"alg":"RS256","typ":"JWT"}
. The payload should include atarget_audience
claim set to the URL of the receiving function andiss
andsub
claims set to the email address of the service account used above. It should also includeexp
, andiat
claims. Theaud
claim should be set tohttps://www.googleapis.com/oauth2/v4/token
.Use the private key downloaded above to sign the JWT.
Using this JWT, send a POST request to https://www.googleapis.com/oauth2/v4/token. Authentication data must be included in the header and the body of the request.
In the header:
Authorization: Bearer $JWT - where $JWT is the JWT you just created Content-Type: application/x-www-form-urlencoded
In the body:
grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer&assertion=$JWT
Replace
$JWT
with the JWT you just createdThis returns another JWT which includes an
id_token
signed by Google.
Send your GET/POST request to the receiving function. Include the Google-signed
ID token in an Authorization: Bearer ID_TOKEN_JWT
header
in the request.
What's next
Learn how to manage access to functions.
Get help with other ways to generate ID tokens.