Using Google authentication

You're viewing Apigee X documentation.
View Apigee Edge documentation.

This topic explains how to set up and deploy an API proxy that is configured to use Google authentication.

Introduction

Apigee supports using Google OAuth tokens or OpenID Connect tokens to authenticate with Google services such as Cloud Logging and Secret Manager and custom services running on certain Google Cloud products such as Cloud Functions and Cloud Run.

To use this feature, you must configure the <Authentication> XML element in one of the following contexts:

  • ServiceCallout policies
  • ExternalCallout policies
  • TargetEndpoint configurations

After you complete some basic setup steps (as described in this topic), Apigee performs the token generation and makes secure calls to targeted Google services or custom hosted services for you, without the need to manually set authentication headers or otherwise modify a service request. From the perspective of an API developer, the process of calling Google services from within a properly configured API proxy is handled seamlessly.

API proxy configuration options

This section explains where you can use the <Authentication> XML element to enable Google OAuth Token or OpenID Connect authentication:

Configuration option Description
ServiceCallout policy The ServiceCallout policy lets you call to other internal or external services from an API proxy. For example, you can use ServiceCallout to call external Google services or custom hosted services. For usage details and examples, see ServiceCallout policy.
ExternalCallout policy The ExternalCallout policy enables you to send gRPC requests to your gRPC server to implement custom behavior that isn't supported by Apigee policies. For usage details and examples, see ExternalCallout policy.
TargetEndpoint Specify a Google service or custom hosted service as an API proxy target endpoint. For usage details and examples, see API Proxy configuration reference.

Google Auth Token supported contexts

The <Authentication> element has two sub-element configurations: <GoogleAccessToken> or <GoogleIDToken>. The following table shows the contexts in which these elements are supported:

Used in GoogleAccessToken GoogleIDToken
ServiceCallout policy Supported Supported
ExternalCallout policy Not supported Supported
TargetEndpoint Supported Supported

Deployment steps

This section explains how to deploy an API proxy that uses Google authentication to call targeted Google services or custom hosted services. We explain the deployment steps for Apigee X and Apigee hybrid separately.

Deploy on Apigee X

The following steps explain how to deploy an API proxy on Apigee X, where the proxy is configured to make authenticated calls to Google services or custom hosted services. The steps assume that you have already created the proxy, and that it includes an <Authentication> element in one of the listed supported contexts.

  1. Create a Google service account in the same Google Cloud project where your Apigee organization was created. You must provide this service account's name when you deploy an API proxy that is configured to use Google authentication, and the OAuth tokens that are generated will represent the service account. You can create the service account in the Google Cloud Console or with the gcloud command. See Creating and managing service accounts.
  2. Give the user who will do the deployment (the deployer) the iam.serviceAccounts.actAs permission on the service account. See also About service account permissions.
    gcloud iam service-accounts add-iam-policy-binding \
    SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --member="MEMBER" \
      --role="roles/iam.serviceAccountUser"
    
  3. Where:

    • PROJECT_ID: The project id. The ID is the same as your organization name.
    • SA_NAME: The name that you provided when you created the service account.
    • MEMBER: The member to add the binding for. Should be of the form user|group|serviceAccount:email or domain:domain.
  4. Give the service account permissions needed to talk to your targeted Google services. For example, if you want to call the Google Logging service, this service account must include the required permissions to talk to that service. See also Understanding roles.
  5. Before deploying an API proxy that is configured to use Google authentication, you need:
    • The name of the service account you created previously. For example: SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • As the user performing the deployment (the deployer), you must already have or be granted the iam.serviceAccounts.actAs permission on the service account. See Granting, changing, and revoking access to resources.
  6. Deploy the API proxy containing the Google authentication configuration you implemented. You can use the Apigee UI or API to deploy the proxy. To learn more, see Deploying an API proxy.
    • If using the UI, you are asked to provide a service account name. Use the name of the proxy service account you created in Step 1. For example: SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

    • If you prefer to deploy the proxy using the Apigee deployment API, here's an example cURL command that you can use. Notice that the command includes a service account name as a query parameter. This is the name of the service account you created in Step 1:
      curl -H "Authorization: Bearer $TOKEN" \
      "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      -H "Content-Type: application/json" -X POST

      Where:

      • TOKEN: An OAuth token that you must obtain in exchange for your Google credentials. For details, see Obtaining an OAuth 2.0 access token.
      • ORG_NAME: Your Apigee organization name.
      • ENV_NAME: The name of the environment to deploy the API proxy to.
      • SA_NAME: The name that you provided when you created the service account.
      • PROJECT_ID: Your Google Cloud project ID (same as the organization name).
  7. When the deployment completes, test your API proxy to make sure the Google service returns the expected response.

Deploy on Apigee hybrid

The following steps explain how to deploy to Apigee hybrid an API proxy that is configured to make authenticated calls to Google services. The steps assume that you have already created the proxy, and that it includes an <Authentication> element in one of the listed supported contexts.

  1. Create a service account and key for the Apigee hybrid runtime component by using one of the following methods:
  2. Open your overrides.yaml file and specify the path to the service account key file for each environment that requires Google authentication capability:
    envs:
      - name: "ENVIRONMENT_NAME"
        serviceAccountPaths:
          runtime: "KEY_FILE_PATH"

    For example:

    envs:
      - name: "test"
        serviceAccountPaths:
          runtime: "./service_accounts/my_runtime_sa.json"
  3. Apply the overrides file to your cluster using apigeectl apply.
  4. Create a second service account, which we call the proxy service account. This service account must be in the same Google Cloud project that you used to create your Apigee organization. You must provide this service account's email address when you deploy an API proxy that is configured to use Google authentication, and the OAuth tokens that are generated will represent the service account.
  5. Give the user who will do the deployment (the deployer) the iam.serviceAccounts.actAs permission on the service account. See also About service account permissions.
    gcloud iam service-accounts add-iam-policy-binding PROJECT_ID \
    PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --member="MEMBER" \
      --role="roles/iam.serviceAccountUser
    
  6. Where:

    • PROJECT_ID: The project id. The ID is the same as your organization name.
    • PROXY_SA_NAME: The name you provided when you created the service account.
    • MEMBER: The member to add the binding for. Should be of the form user|group|serviceAccount:email or domain:domain.
  7. Give the proxy service account permissions needed to talk to your targeted Google services. For example, if you want to call the Google Logging service, this service account must include the required permissions to talk to that service. See also Understanding roles.
  8. Ensure that the runtime has the ability to impersonate the proxy service account. To provide this ability, grant the runtime service account the iam.serviceAccountTokenCreator role on the proxy service account. See also About service account permissions. For example:
    gcloud iam service-accounts add-iam-policy-binding \
    PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --member=serviceAccount:RUNTIME_SA_NAME@PROJECT_ID.iam.gserviceaccount.com \
    --role=roles/iam.serviceAccountTokenCreator
    

    Where:

    • PROJECT_ID: The project id. The ID is the same as your organization name. Note that you did not have to use the project associated with your organization to create the runtime service account. Just be sure you use the correct project IDs in this command.
    • PROXY_SA_NAME: The ID for the proxy service account.
    • RUNTIME_SA_NAME: The ID for the runtime service account.
  9. Before deploying an API proxy that is configured to use Google authentication, you need:
    • The name of the proxy service account you created previously. For example: PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com
    • As the user performing the deployment, you must already have or be granted the iam.serviceAccounts.actAs permission in the Google Cloud Project where the Apigee organization is provisioned. See Granting, changing, and revoking access to resources.
  10. Deploy the API proxy containing the Google authentication configuration you implemented. You can use the Apigee UI or API to deploy the proxy. To learn more, see Deploying an API proxy.
    • If using the UI, you are asked to provide a service account name. Use the name of the proxy service account you created previously. For example: PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com.

    • If you prefer to deploy the proxy using the Apigee deployment API, here's an example cURL command that you can use. Notice that the command includes a service account name as a query parameter. This is the name of the proxy service account:
      curl -H "Authorization: Bearer $TOKEN" \
      "https://apigee.googleapis.com/v1/organizations/ORG_NAME/environments/ENV_NAME/apis/apiproxy/revisions/2/deployments?serviceAccount=PROXY_SA_NAME@PROJECT_ID.iam.gserviceaccount.com" \
      -H "Content-Type: application/json" -X POST

      Where:

      • TOKEN: An OAuth token that you must obtain in exchange for your Google credentials. For details, see Obtaining an OAuth 2.0 access token.
      • ORG_NAME: Your Apigee organization name.
      • ENV_NAME: The name of the environment to deploy the API proxy to.
      • PROXY_SA_NAME: The name of the proxy service account.
      • PROJECT_ID: Your Google Cloud project ID (same as the organization name).
  11. When the deployment completes, test your API proxy to make sure the Google service returns the expected response.

About service account permissions

To configure an API proxy to use Google authentication, you must create two service accounts, described in the following table. See also Creating and managing service accounts.

Service account Required for Description
Proxy Apigee X and Apigee hybrid

Has permissions needed for an API proxy to make authenticated calls to targeted Google services.

  • Must be created in the same Google Cloud project as your Apigee organization.
  • The user performing the deployment (the deployer), must have or be granted the iam.serviceAccounts.actAs permission on the proxy service account.
  • Must include permissions needed to talk to specific target Google services. For example, if you want to call the Google Logging service, this service account must include the required permissions to talk to that service. See also Understanding roles.
  • The name of the service account must be provided when you deploy the proxy that uses Google authentication.
Runtime Apigee hybrid only

Allows the Apigee runtime to generate tokens to authenticate on Google services requested by an API proxy. This service account "impersonates" the proxy-specific service account to make authenticated calls on its behalf.

  • To be able to impersonate the proxy service account and create tokens, the runtime service account must be granted the role roles/iam.serviceAccountTokenCreator on the proxy service account. See Managing service account impersonation.