API Key Authentication with Google Cloud API Gateway and Cloud Run

Create an API Gateway Config

This is probably the hardest part of the entire process, at least when you’re doing it for the first time. In order to create the API Gateway Config, you need to create an OpenAPI2 spec file that defines the API endpoint this API Gateway will be communicating with. This spec file is a plain text YAML file that describes the various endpoints for your API, including their paths, any parameters they require, and the security settings.

Unfortunately, this is one of those areas where the documentation isn’t always as helpful as it could be. For starters, the file itself needs to be customized to match your specific API, so it’s up to you to write it properly. Also, the Google API Gateway implementation has a few quirks that can make your life difficult if you don’t know what to look out for.

All that said, here’s an example of what the OpenAPI spec file might look like for the example Cloud Run service we created earlier in this tutorial. You can save this file anywhere on your machine, just remember the name and location for when you need to create the actual API Gateway Config from it later.

OpenAPI Spec Example

# openapi2-run.yaml
swagger: '2.0'
info:
  title: Demo API
  description: Example API created for JustinDigsData.com tutorial
  version: 1.0.0
schemes:
- https
produces:
- application/json
x-google-backend:
  address: {{CLOUD_RUN_SERVICE_URL}}
securityDefinitions:
  # This section configures basic authentication with an API key.
  api_key:
    type: "apiKey"
    name: "x-api-key"
    in: "header"
security:
      - api_key: []
paths:
  /get/helloworld:
    get:
      summary: Cloud Run hello world
      operationId: helloworld
      responses:
        '200':
          description: A successful response
          schema:
            type: string
  /post/add:
    post:
      parameters:
        - in: query
          name: num1
          type: number
          required: true
          description: First number to add
        - in: query
          name: num2
          type: number
          required: true
          description: Second number to add
      summary: Adds two numbers provided in the query parameters.
      operationId: postAddQueryparamsNum1Num2
      responses:
        '200':
          description: A successful response
          schema:
            type: string

You’ll need to customize that quite a bit to match your own specific scenario, but if you’re just trying to follow along with this tutorial, the only thing you’ll need to change is the {{CLOUD_RUN_SERVICE_URL}} value. Just replace that placeholder with the actual value for your own Cloud Run service

Couple of important sections in that file that’s you’ll need to update for your own requirements:

• info:
  • title: This is the friendly name that you’ll see later when looking at your various APIs. Should be unique in the project
  • description (optional): Text description of your API
  • version (optional): The version of your API described in this document
• x-google-backend:
  • address: The URL of your Google Cloud Run service. You can find it using:
    • gcloud run services list --project={{PROJECT_ID}}
• securityDefinitions:
  • api_key:
    • type: “apiKey” (always use this value if you want to use API Keys for authentication)
    • name: If you want the key to be included as an HTTP header, value must be “x-api-key”. If using query parameters, value must be either “api_key” or “key”.
    • in: If you want the key to be included as an HTTP header, value must be “header”. If using query parameters, value must be either “query”.
• paths:
  • Really, all of this is going to depend on your specific situation. But you need to define the actual endpoint path, the parameters, etc. to match your endpoints.
    
    I’d HIGHLY recommend reading over the Swagger docs on Paths and Operations

Once your OpenAPI spec file is ready, you’ll need to create the Google API Gateway Config object based on it. Not surprisingly, we’ll use the gcloud Command Line Interface for that, too:

gcloud api-gateway api-configs create {{CONFIG_ID}} --api={{API_ID}} \
  --openapi-spec={{OPENAPI_SPEC_FILENAME}} --project={{PROJECT_ID}} \
  --backend-auth-service-account={{SERVICE_ACCOUNT_EMAIL}}

Where:

• {{CONFIG_ID}}: Name/ID of the new API Gateway API Config we want to create. I like to just use the same name as the API_ID with “-config” appended to the end (e.g. demo-api-config).
• {{API_ID}}: The ID of the API Gateway API created in the previous section. (e.g. demo-api).
• {{OPENAPI_SPEC_FILENAME}}: The name of the OpenAPI spec file. (e.g. openapi2-run.yaml)
• {{PROJECT_ID}}: Name of the Google Cloud project you’re using for the tutorial (e.g. api-gateway-key-auth-demo)
• {{SERVICE_ACCOUNT_EMAIL}}: Email address of the Google IAM Service Account you want the API Gateway to use to communicate with your backend Cloud Run service.

Technically, you can skip the Create an API Gateway API part we ran through before and just run this command. When you create a Gateway API Config, it will actually create the API you provided as the --api parameter if it doesn’t already exist.