Secure traffic to a service with the Google Cloud console

This page shows you how to deploy an API on API Gateway to secure traffic to a backend service.

Follow the steps to deploy a new API to access a backend service on Cloud Run functions using the Google Cloud console. This quickstart also describes how to use an API key to protect your backend from unauthorized access.

Before you begin

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

   Go to API Gateway

   Note: If you don't plan to keep the resources you create in this quickstart, create a new project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

2. API Gateway requires that you enable the following Google services:

   Name	Title
   apigateway.googleapis.com	API Gateway API
   servicemanagement.googleapis.com	Service Management API
   servicecontrol.googleapis.com	Service Control API

   If you have not previously enabled these services for the project you select, you will be prompted to do so.

3. Confirm that billing is enabled for your project.

   Learn how to enable billing

Deploying an API backend

API Gateway sits in front of a deployed backend service and handles all incoming requests. In this quickstart, API Gateway routes incoming calls to a Cloud Run function backend named helloGET that contains the function shown as follows:

/**
 * HTTP Cloud Function.
 * This function is exported by index.js, and is executed when
 * you make an HTTP request to the deployed function's endpoint.
 *
 * @param {Object} req Cloud Function request context.
 *                     More info: https://expressjs.com/en/api.html#req
 * @param {Object} res Cloud Function response context.
 *                     More info: https://expressjs.com/en/api.html#res
 */

exports.helloGET = (req, res) => {
  res.send('Hello World!');
};

Follow the steps in Quickstart: Using the Google Cloud CLI to download the sample Cloud Run functions code and deploy the Cloud Run function backend service.

Note: The actual name of the function and backend in the example will vary according to the language you choose when completing the Cloud Run functions tutorial. This tutorial uses the Node.js example.

Creating an API definition

API Gateway uses an API definition to route calls to the backend service. You can use an OpenAPI spec that contains specialized annotations to define the chosen API Gateway behavior. The OpenAPI spec for this quickstart contains routing instructions to the Cloud Run function backend:

# openapi2-functions.yaml
swagger: '2.0'
info:
  title: API_ID optional-string
  description: Sample API on API Gateway with a Google Cloud Functions backend
  version: 1.0.0
schemes:
  - https
produces:
  - application/json
paths:
  /hello:
    get:
      summary: Greet a user
      operationId: hello
      x-google-backend:
        address: https://us-central1-PROJECT_ID.cloudfunctions.net/helloGET
      responses:
        '200':
          description: A successful response
          schema:
            type: string

To use the OpenAPI spec shown in the previous example to define your API:

1. From the command line, create a new file named openapi2-functions.yaml.

2. Copy and paste the contents of the OpenAPI spec shown in the previous example into the newly created file.

3. Edit the file as follows:

   1. In the title field, replace API_ID with the name of your API (which will be created in the next step) and replace optional-string with a brief description of your choosing. The value of this field is used when minting API keys that grant access to this API. See API ID requirements for API ID naming guidelines.
   2. In the address field, replace PROJECT_ID with the name of your Google Cloud project.

Creating a gateway

Now you are ready to create and deploy a gateway on API Gateway.

1. Open the API Gateway page in the Google Cloud console.

   Go to API Gateway

2. Click Create Gateway.

3. In the API section:

   1. You can choose to create a new API or select an existing API from the Select an API drop-down. For this tutorial, select Create a new API.
   2. Enter the Display Name for your API.
   3. Enter the API ID for your API.
   4. (Optional) Add labels to your API using a key/value format. To add more than one label, click Add Label and enter additional values.

4. In the API Config section:

   1. You can choose to create a new API config or select an existing API config from the Select a Config drop-down. For this tutorial, select Create a new API config.
   2. Use the file browser to upload the openapi2-functions.yaml used to define your API.
   3. Enter a display name for your API config.

   4. Select a service account from the drop-down list. The service account you select will be used as identity for API Gateway.

      Note: If you don't see a service account listed in the drop-down, see Configuring a service account to ensure that a service account is enabled for your project.

   5. (Optional) Add labels to your API config using a key/value format. To add more than one label, click Add Label and enter additional values.

5. In the Gateway details section:

   1. Enter the display name of the gateway. The URL to the gateway is automatically generated.
   2. Select the location of the gateway from the drop-down menu.
   3. (Optional) Add labels to your gateway using a key/value format. To add more than one label, click Add Label and enter additional values.

6. Click Create Gateway.

This deploys the API config on a newly created gateway. Deploying an API config on a gateway defines an external URL that API clients can use to access your API.

It may take several minutes for the operation to complete. To check the status of the creation and deployment process, you can click the Notification icon in the main navigation bar to display a status notification, as shown in the following image:

On successful completion, you can view details about the gateway on the Gateways landing page.

Go to API Gateway

Make a note of the gateway URL. This is used to test your deployment in the next step.

Note: The URL for your newly created gateway may take a few moments to display. If it does not appear momentarily, click Refresh on the Gateways landing page to update the display.

Testing your API deployment

Now you can send requests to your API using the URL generated upon deployment of your gateway.

In your browser, enter the following URL, where:

• GATEWAY_URL specifies your deployed gateway URL.
• hello is the path specified in your API config.

https://GATEWAY_URL/hello

For example:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

The message Hello World! should display in your browser.

You have successfully created and deployed an API Gateway!

Securing access by using an API key

To secure access to your API backend, you can generate an API key associated with your project and grant that key access to call your API. See Restricting API access with API keys for more information.

If you don't already have an API key associated with the Google Cloud project you are using in this quickstart, you can add one by following the steps at Creating an API Key.

To secure access to your gateway using an API key:

1. Enable API key support for your service:
   1. In the Google Cloud console, go to APIs & Services > Library.
   2. In the search bar, enter the Managed Service name of the API you just created. You can find this value in the Managed Service column for your API on the APIs landing page. For example:

      my-api-123abc456def1.apigateway.my-project.cloud.goog

   3. On the landing page for your service, click Enable.
      Note: There may be a delay of up to 30 minutes or more between the time you create your API and the time it appears in the Library. If your API is not visible in the Library, you can enable it using the gcloud command line tool. Enter the following command where MANAGED_SERVICE_NAME specifies the Managed Service name of your API:

      gcloud services enable MANAGED_SERVICE_NAME

2. Modify the OpenAPI spec used to create your API config to include instructions to enforce an API key validation security policy on all traffic. Add the security type and securityDefinitions as shown:

       # openapi2-functions.yaml
       swagger: '2.0'
       info:
         title: API_ID optional-string
         description: Sample API on API Gateway with a Google Cloud Functions backend
         version: 1.0.0
       schemes:
         - https
       produces:
         - application/json
       paths:
         /hello:
           get:
             summary: Greet a user
             operationId: hello
             x-google-backend:
               address:https://us-central1.PROJECT_ID.cloudfunctions.net/helloGET
             security:
             - api_key: []
             responses:
               '200':
                 description: A successful response
                 schema:
                   type: string
       securityDefinitions:
         # This section configures basic authentication with an API key.
         api_key:
           type: "apiKey"
           name: "key"
           in: "query"
       

   The securityDefinition configures your API to require an API key passed as a query parameter named key when requesting access to all paths defined in the spec.
3. Create and deploy a new API config to your existing gateway:
   1. Go to the Gateways landing page.

      Go to API Gateway

   2. Select your gateway from the list to view details.
   3. Click Edit to open the gateway configuration pane.
   4. In the API config section:
      1. Select Create a new API config from the available drop-down.
      2. Upload your modified OpenAPI spec using the file browser.
      3. Enter the display name for your new API config.
      4. Select a service account from the drop-down list. The service account you select will be used as the identity for API Gateway.
      5. (Optional) Add labels to your API config using a key/value format. To add more than one label, click Add Label and enter additional values.
   5. Click Update.

Testing your API key

Once you have created and deployed the modified API, try making a request to it.

In your browser, enter the following URL, where:

• GATEWAY_URL specifies your deployed gateway URL.
• hello is the path specified in your API config.

https://GATEWAY_URL/hello

For example:

https://my-gateway-a12bcd345e67f89g0h.uc.gateway.dev/hello

This should result in the following error:

UNAUTHENTICATED:Method doesn't allow unregistered callers (callers without established identity). Please use API Key or other form of API consumer identity to call this API.

Now, in your browser, enter the following URL, where:

• GATEWAY_URL specifies your deployed gateway URL.
• hello is the path specified in your API config.
• API_KEY specifies the API key you created in Securing access by using an API key.

https://GATEWAY_URL/hello?key=API_KEY

Now you should see Hello World! in your browser.

Congratulations! You have successfully protected your API backend with an API Gateway. Now you can start onboarding new API clients by generating additional API keys.

Tracking API activity

1. View the activity graphs for your API on the API Gateway page in the Google Cloud console. Click your API to view its activity graphs on the Overview page. It may take a few moments for the requests to be reflected in the graphs.

2. Look at the request logs for your API on the Logs Explorer page. A link to the Logs Explorer page can be found on the API Gateway page in the Google Cloud console.

   Go to API Gateway

   Once on the API Gateway page:

   1. Select the API to view.
   2. Click the Details tab.
   3. Click the link under Logs.

Clean up

To avoid incurring charges to your Google Cloud account for the resources used in this quickstart, you can:

• Delete your gateways
• Delete your API

Alternatively, you can also delete the Google Cloud project used for this tutorial.

What's next

• Learn more About API Gateway
• Walk through Configuring your development environment