Use authentication with HTTP targets

Cloud Scheduler can call HTTP targets that require authentication if you have set up an associated service account that has the appropriate credentials.

Set up the service account

1. If you don't already have a service account that you want to use for Cloud Scheduler jobs with HTTP targets, create a new service account. Note the following:

   • The service account must belong to the project in which the Cloud Scheduler job is created.

   • Do not use the Cloud Scheduler service agent (service-YOUR_PROJECT_NUMBER@gcp-sa-cloudscheduler.iam.gserviceaccount.com). It cannot be used for this purpose.

   • Do not revoke the Cloud Scheduler Service Agent role (roles/cloudscheduler.serviceAgent) from the Cloud Scheduler service agent on your project. Doing so results in 403 responses to endpoints requiring authentication, even if your job's service account has the appropriate role.

2. If your target is within Google Cloud, grant the necessary IAM roles to your service account. Each service within Google Cloud requires a specific role, and the receiving service automatically verifies the generated token. For example, for Cloud Run and second generation Cloud Run functions functions, you must add the Cloud Run Invoker role.

   Note that to deploy a resource with a user-managed service account, the deployer must have the iam.serviceAccounts.actAs permission for that service account. If you created the service account, you are automatically granted this permission. If not, someone who has the correct permissions must grant you this permission on the service account.

   Best practice: In the previous step, if you created a service account specifically for invoking the service that your Cloud Scheduler job targets, consider following the principle of least privilege (security best practice) by binding the account and its invoker permission to your target service. You can do this using the Google Cloud console or the gcloud CLI:

   Console

   1. Open the Google Cloud console.

   Go to Console

   2. Select your project.

   3. Navigate to the page for the resource type you are invoking. For example, if you are invoking a Cloud Run service, navigate to the page that lists Cloud Run services.

   4. Select the checkbox at the left of the service you want to invoke. (Don't click on the service itself.)

   5. Click the Permissions tab. If the information pane isn't visible, you may need to click Show Info Panel, then click Permissions.

   6. Click person_add Add principal.

   7. Under Add principals, enter the email address for the service account you created.

   8. Under Assign roles, select a role to grant from the drop-down list. Follow the principle of least privilege by choosing the role that includes only the permissions that your principal needs.

   9. Click Save.

   gcloud

   Run the add-iam-policy-binding command:

   gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
   --member=PRINCIPAL --role=ROLE

   Replace:

   • RESOURCE_TYPE: The resource type of your target. For example, run for a Cloud Run target.
   • RESOURCE_ID: The identifier for your target. For example, the service name for a Cloud Run target.
   • PRINCIPAL: The identifier for your service account. This has the following form: serviceAccount:SERVICE_ACCOUNT_EMAIL_ADDRESS. For example, serviceAccount:[email protected].
   • ROLE: The name of the role that your target service requires for invocation. For example, roles/run.invoker for a Cloud Run or second generation Cloud Run functions target.

   Examples:

   • Cloud Run target: The following command grants the Cloud Run Invoker role to the service account [email protected] for the Cloud Run service my-service:

     gcloud run add-iam-policy-binding my-service \
      --member=serviceAccount:[email protected] \
      --role=roles/run.invoker
     

   • Cloud Run functions target: The following command grants the Cloud Run Invoker role required by second generation Cloud Run functions functions to the service account [email protected] for the second generation Cloud Run functions function my-gen2-function:

     gcloud functions add-iam-policy-binding my-gen2-function \
      --member=serviceAccount:[email protected] \
      --role=roles/run.invoker --gen2
     

3. If your target is outside of Google Cloud, the receiving service must manually verify the token.

4. The default Cloud Scheduler service account is automatically set up when you enable the Cloud Scheduler API, unless you enabled it prior to March 19, 2019, in which case you must add the Cloud Scheduler Service Agent role manually. This is so that it can generate header tokens on behalf of your client service account to authenticate to your target.

   You can verify that the default Cloud Scheduler service account is set up in your project and that it has the Cloud Scheduler Service Agent role granted to it by viewing your project's current access. Note that if you use the Google Cloud console to view your project's access, make sure to select the Include Google-provided role grants checkbox.

Create a scheduler job with authentication

To create a job that uses authentication, you need to add the token type and the email address that identifies the client service account to your create-job request:

gcloud scheduler jobs create http JOB_ID \
  --schedule="FREQUENCY" --uri=URI \
  --oidc-service-account-email=CLIENT_SERVICE_ACCOUNT_EMAIL

Choose token types

To authenticate between Cloud Scheduler and an HTTP target, Cloud Scheduler creates a header token based on your client service account, identified by its email, and sends it, using HTTPS, to the target. You can use either an ID (OIDC) token or an OAuth (access) token. OIDC is generally used except for Google APIs hosted on *.googleapis.com as these APIs expect an OAuth token.

Manually add the Cloud Scheduler Service Agent role to your Cloud Scheduler service account

This is necessary only if one of the following is true:

• You enabled the Cloud Scheduler API prior to March 19, 2019
• You removed the Cloud Scheduler Service Agent role from your service account

The Cloud Scheduler service account requires the Cloud Scheduler Service Agent role. Without this role, Cloud Scheduler jobs fail. You can add the Cloud Scheduler Service Agent role to your Cloud Scheduler service account from the Google Cloud console or using the gcloud CLI: