Perform Google Workspace domain-wide delegation of authority

The Cloud Search Query API requires that API calls are authorized using OAuth credentials belonging to a licensed user in your domain. By default, service accounts, which are used to access the indexing and configuration APIs, cannot be used for query API calls because they are not domain users with Cloud Search or Google Workspace licenses. If you wish to use a service account when authenticating query API calls, a domain administrator can grant the account domain-wide access to user data — this is known as domain-wide delegation of authority. A service account with delegated authority can impersonate any user, including users with access to Cloud Search.

Create the service account and credentials

If you do not yet have service account credentials, refer to Create service account credentials.

Delegate domain-wide authority to your service account

To access user data on a Google Workspace domain, the service account that you created needs to be granted access by a super administrator for the domain. For more information about domain-wide delegation, see Control Google Workspace API access with domain-wide delegation.

To delegate domain-wide authority to a service account:

  1. From your domain’s Admin console, go to Main menu > Security > Access and data control > API controls.

  2. In the Domain wide delegation pane, select Manage Domain Wide Delegation.

  3. Click Add new.

  4. In the Client ID field, enter the client ID obtained from the service account creation steps above.

  5. In the OAuth Scopes field, enter a comma-delimited list of the scopes required for your application. Use the scope https://www.googleapis.com/auth/cloud_search.query for search applications using the Query API.

  6. Click Authorize.

Your service account now has domain-wide access to the Cloud Search Query API, and can impersonate any user of your domain in this scope. You are ready to instantiate an authorized Cloud Search API service object on behalf of your domain's users.

Instantiate a Cloud Search API service object

This section shows how to instantiate a Cloud Search API service object and then authorize it to make API requests using OAuth 2.0 and your service account's credentials to perform Google Workspace domain-wide delegation. The examples read the service account's information from the JSON-formatted private key file.

Java

import java.util.Collections;
import java.io.FileInputStream;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.services.cloudsearch.v1.CloudSearch;
import com.google.api.services.cloudsearch.v1.CloudSearchScopes;
...

/** Path to the Service Account's Private Key file */
private static final String SERVICE_ACCOUNT_FILE_PATH = "/path/to/key.json";

/**
 * Build and return a Cloud Search service object authorized with the service
 * account that acts on behalf of the given user.
 *
 * @param userEmail The email of the user to impersonate. Needs permissions to access Cloud Search.
 * @return CloudSearch service object that is ready to make requests.
 */
public static CloudSearch getCloudSearchAPIService(String userEmail)
    throws FileNotFoundException, IOException {

  FileInputStream credsFile = new FileInputStream(SERVICE_ACCOUNT_FILE_PATH);

  GoogleCredential init = GoogleCredential.fromStream(credsFile);

  HttpTransport httpTransport = init.getTransport();
  JsonFactory jsonFactory = init.getJsonFactory();

  GoogleCredential creds = new GoogleCredential.Builder()
      .setTransport(httpTransport)
      .setJsonFactory(jsonFactory)
      .setServiceAccountId(init.getServiceAccountId())
      .setServiceAccountPrivateKey(init.getServiceAccountPrivateKey())
      .setServiceAccountScopes(Collections.singleton(CloudSearchScopes.CLOUD_SEARCH_QUERY))
      .setServiceAccountUser(userEmail)
      .build();

  CloudSearch service = new CloudSearch.Builder(httpTransport, jsonFactory, creds).build();

  return service;
}

Python

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Path to the Service Account's Private Key file
SERVICE_ACCOUNT_FILE_PATH = "/path/to/key.json"

def create_query_api_service(user_email):
    """Build and return a CloudSearch service object authorized with the service
    account that acts on behalf of the given user.

    Args:
        user_email: The email of the user to impersonate. Needs permissions to access Cloud Search.
    Returns:
        Cloud Search Query API service object that is ready to make requests.
    """
    credentials = service_account.Credentials.from_service_account_file(
        SERVICE_ACCOUNT_FILE_PATH,
        scopes=['https://www.googleapis.com/auth/cloud_search.query'])

    delegated_credentials = credentials.with_subject(user_email)

    return build("cloudsearch", "v1", credentials=delegated_credentials)