Authentication between services

Google Cloud console

Create a service account:

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

   Go to Create service account

2. Select a project.

3. In the Service account name field, enter a name. The Google Cloud console fills in the Service account ID field based on this name.

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

5. Click Create.

6. Click the Select a role field.

   Under All roles, select Service Accounts > Service Account Token Creator.

7. Click Continue.

8. Click Done to finish creating the service account.

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

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 key file is downloaded 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

7. Create a service account key file in the current working directory. Replace FILE_NAME with the name that you want to use for key file. By default, the gcloud command creates a JSON file.

   gcloud iam service-accounts keys create FILE_NAME.json \
     --iam-account SA_EMAIL_ADDRESS

See the gcloud reference for more information about the previous commands.

OpenAPI 2.0

1. Add the service account as an issuer in your API config:

   securityDefinitions:
       DEFINITION_NAME:
         authorizationUrl: ""
         flow: "implicit"
         type: "oauth2"
         x-google-issuer: "SA_EMAIL_ADDRESS"
         x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS"
     

   • Replace DEFINITION_NAME with a string that identifies this security definition. You might want to replace it with the service account name or a name that identifies the calling service.
   • Replace SA_EMAIL_ADDRESS with the service account's email address.
   • You can define multiple security definitions in your API config, but each definition must have a different x-google-issuer. If you have created separate service accounts for each calling service, you can create a security definition for each service account, for example:

     securityDefinitions:
         service-1:
           authorizationUrl: ""
           flow: "implicit"
           type: "oauth2"
           x-google-issuer: "service-1@example-project-12345.iam.gserviceaccount.com"
           x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-1@example-project-12345.iam.gserviceaccount.com"
         service-2:
           authorizationUrl: ""
           flow: "implicit"
           type: "oauth2"
           x-google-issuer: "service-2@example-project-12345.iam.gserviceaccount.com"
           x-google-jwks_uri: "https://www.googleapis.com/robot/v1/metadata/x509/service-2@example-project-12345.iam.gserviceaccount.com"

2. Optionally, add x-google-audiences to the securityDefinitions section. If you don't add x-google-audiences, API Gateway requires that the "aud" (audience) claim in the JWT is in the format https://SERVICE_NAME, where SERVICE_NAME is the name of your API Gateway service, which you have configured in the host field of your OpenAPI document.
3. Add a security section at either the top level of the file (not indented or nested) to apply to the entire API, or at the method level to apply to a specific method. If you use security sections at both the API level and at the method level, the method-level settings override the API-level settings.

   security:
     - DEFINITION_NAME: []

   • Replace DEFINITION_NAME with the name that you used in the securityDefinitions section.
   • If you have more than one definition in the securityDefinitions section, add them in the security section, for example:

     security:
       - service-1: []
       - service-2: []

4. Deploy your updated API config. Before API Gateway forwards a request to your API, API Gateway verifies:
   • The signature of the JWT by using the public key, which is located at the URI specified in the x-google-jwks_urifield in your API config.
   • That the "iss"(issuer) claim in the JWT matches the value specified in the x-google-issuerfield.
   • That the "aud"(audience) claim in the JWT contains your API Gateway service name or matches one of the values that you specified in the x-google-audiencesfield.
   • That the token isn't expired by using the "exp"(expiration time) claim.

OpenAPI 3.x

1. Add the service account as an issuer in your API config:

   components:
     securitySchemes:
       SCHEME_NAME:
         type: oauth2
         flows:
          implicit:
            authorizationUrl: ""
            scopes: {}
         x-google-auth:
           issuer: SA_EMAIL_ADDRESS
           jwksUri: https://www.googleapis.com/robot/v1/metadata/x509/SA_EMAIL_ADDRESS
   security:
     - SCHEME_NAME: