Authentication between services

In addition to authenticating users, you might need to allow other services to interact with your API. While client applications can provide users with a web sign-in prompt to submit their credentials, you need another approach for secure service-to-service communication. This page shows the approach that we recommend to implement authentication between services and provides sample code.

Overview

To identify a service that sends requests to your API, you use a service account. The calling service uses the service account's private key to sign a secure JSON Web Token (JWT) and sends the signed JWT in the request to your API.

To implement service-to-service authentication in your API and calling service:

  1. Create a service account and key for the calling service to use.
  2. Add support for authentication in the OpenAPI document for your Cloud Endpoints service.

  3. Add code to the calling service that:

    • Creates a JWT and signs it with the service account's private key.
    • Sends the signed JWT in a request to the API.

ESP validates that the claims in the JWT match the configuration in your OpenAPI document before forwarding the request to your API. ESP doesn't check for Cloud Identity permissions that you have granted on the service account.

Prerequisites

This page assumes that you have already:

Creating a service account with a key

You need a service account with a private key file that the calling service uses to sign the JWT. If you have more than one service sending requests to your API, you can create one service account to represent all the calling services. If you need to differentiate between the services—for example, they might have different permissions—you can create a service account and key for each calling service.

This section shows how to use the Google Cloud console and the gcloud command-line tool to create the service account and private key file and to assign the service account the Service Account Token Creator role. For information on using an API to do this task, see Creating and managing service accounts.

To create a service account and key:

Google Cloud console

  1. Create a service account:

    1. In the Google Cloud console, go to the Create service account page.

      Go to the Create Service Account page

    2. Select the project that you want to use.

    3. In the Service account name field, enter a name.

    4. Optional: In the Service account description field, enter a description.

    5. Click Create.

    6. Click Done.

      Don't close your browser window. You will use it in the next step.

  2. Create a service account key:

    1. In the Google Cloud console, click the email address for the service account that you created.
    2. Click Keys.
    3. Click Add key, then Create new key.
    4. Click Create. A JSON file that contains the service account's private key downloads to your computer.
    5. Click Close.

gcloud

You can run the following commands by using the Google Cloud CLI on your local machine, or within Cloud Shell.

  1. Set the default account for gcloud. If you have more than one account, make sure to choose the account that is in the Google Cloud project that you want to use.

    gcloud auth login

  2. Display the project IDs for your Google Cloud projects.

    gcloud projects list

  3. Set the default project. Replace PROJECT_ID with the Google Cloud project ID that you want to use.

    gcloud config set project PROJECT_ID

  4. Create a service account. Replace SA_NAME and SA_DISPLAY_NAME with the name and display name that you want to use.

    gcloud iam service-accounts create SA_NAME \
  --display-name "SA_DISPLAY_NAME"

  5. Display the email address for the service account that you just created.

    gcloud iam service-accounts list

  6. Add the Service Account Token Creator role. Replace SA_EMAIL_ADDRESS with the service account's email address.

    gcloud projects add-iam-policy-binding PROJECT_ID \
  --member serviceAccount:SA_EMAIL_ADDRESS \
  --role roles/iam.serviceAccountTokenCreator