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 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:my-service-account@my-project.iam.gserviceaccount.com.
    • 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 my-service-account@my-project.iam.gserviceaccount.com for the Cloud Run service my-service:

      gcloud run add-iam-policy-binding my-service \
 --member=serviceAccount:my-service-account@my-project.iam.gserviceaccount.com \
 --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 my-service-account@my-project.iam.gserviceaccount.com for the second generation Cloud Run functions function my-gen2-function:

      gcloud functions add-iam-policy-binding my-gen2-function \
 --member=serviceAccount:my-service-account@my-project.iam.gserviceaccount.com \
 --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:

Console

  1. Specify the frequency as always.
  2. Specify HTTP as the target type.
  3. Add the URL and HTTP method as always.
  4. In the Auth header list, select the token type. Note that OIDC (ID token) is generally used except for Google APIs hosted on *.googleapis.com as these APIs expect an OAuth access token.
  5. For Service account, specify the client service account email.
  6. Audience is optional and limits the recipients for the OIDC token; typically, the job's target URL (without any URL parameters). If not specified, by default, the entire URL is used as the audience (including request parameters).

gcloud 

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

Replace the following:

  • JOB_ID: a name for the job. It must be unique in the project. Note that you cannot re-use a job name in a project even if you delete its associated job.
  • FREQUENCY: the job interval is how often the job is to run, for example, every 3 hours or every 10 mins. The string you supply here can be any Crontab compatible string. (Although we no longer recommend its use, the legacy App Engine cron syntax is still supported for existing jobs.)
  • URI: the fully qualified URL of the endpoint.
  • --oidc-service-account-email or --oauth-service-account-email: defines the token type. Note that OIDC is generally used except for Google APIs hosted on *.googleapis.com as these APIs expect an OAuth token.
  • CLIENT_SERVICE_ACCOUNT_EMAIL: the email of the client service account.
  • Other optional parameters are available and are described in the gcloud command line reference.

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:

Console

  1. In the Google Cloud console, go to the Cloud Scheduler API page.

    Go to Cloud Scheduler API

    If there is a Status field and the status is listed as Enabled, proceed. If not, click Enable.

  2. In the Google Cloud console, go to the Settings page.

    Go to Settings

  3. Find and copy your project number.

  4. In the Google Cloud console, go to the IAM page.

    Go to IAM

  5. Click Grant access. The Grant access pane opens.

  6. In the New principals field, add an email address with the format:

    service-PROJECT_NUMBER@gcp-sa-cloudscheduler.iam.gserviceaccount.com

    Replace PROJECT_NUMBER with your Google Cloud project number.

  7. In the Select a role list, search for and select Cloud Scheduler Service Agent.

  8. Click Save.

gcloud

  1. Confirm that the Cloud Scheduler API is enabled for your project:

    gcloud services list --enabled \
 --filter=cloudscheduler.googleapis.com

    • If you see the following output, the API is enabled:

      NAME: cloudscheduler.googleapis.com
TITLE: Cloud Scheduler API

    • If not (for example, if you see Listed 0 items.), enable the API:

      gcloud services enable cloudscheduler.googleapis.com

  2. Find your project number:

    gcloud projects describe PROJECT_ID --format='table(projectNumber)'

    Replace PROJECT_ID with your project ID.

  3. Copy the number.

  4. Grant the Cloud Scheduler service account the Cloud Scheduler Service Agent role:

    gcloud projects add-iam-policy-binding PROJECT_ID \
   --member serviceAccount:service-PROJECT_NUMBER@gcp-sa-cloudscheduler.iam.gserviceaccount.com \
   --role roles/cloudscheduler.serviceAgent

    Replace the following:

    • PROJECT_ID: your project ID
    • PROJECT_NUMBER: the project number you previously copied