Perform Google Apps domain-wide delegation of authority

In enterprise applications, you might want to programmatically access user data without any manual authorization on the user's part. In Google Apps domains, the domain administrator can grant specific third party applications domain-wide access to its user data—this is referred to as domain-wide delegation of authority. To delegate authority in this way, domain administrators must use service accounts with OAuth 2.0.

You must first create a service account.

Create a console project with service account credentials

The following steps create a Google API Console project with credentials for a service account. The procedure generates credentials that your application will need: the client ID, the private key, and the email address of the service account.

  1. Go to the Google API Console .
  2. From the project drop-down, select a project , or create a new one.
  3. Enable the Google+ Domains API service:
    1. In the list of Google APIs, search for the Google+ Domains API service.
    2. Select Google+ Domains API from the results list.
    3. Select Enable API.
    When the process completes, Google+ Domains API appears in the list of enabled APIs. To access, select APIs & Services on the left sidebar menu, then select the Enabled APIs tab.
  4. In the sidebar under "APIs & Services", select Credentials, then select the OAuth consent screen tab.
    1. Choose an Email Address, specify a Product Name, and select Save.
  5. From the Credentials tab, select the New credentials drop-down list, and choose Service account key.
    1. In the Service account drop-down, choose New service account.
    2. Enter a Name. The Service account ID is generated for you from the name you enter. You can accept this ID or override it. The Service account ID must be between 6 and 30 characters.
    3. Choose a Key type, then select the Create button.
    Once generated, the public/private key pair file downloads to your machine. The file serves as the only copy of this key; you are responsible for storing it securely.
  6. A "Service account created" dialog pops-up after successful creation/download. Select Close to return to the Credentials page.
  7. The Credentials page now displays a Service account keys section containing the service account ID, Creation date, and Service account name. To view the service account's Email address, select Manage service accounts to access the Permissions page. Note or copy these values to use in later steps to configure access to the API. For examples where these values are used, see the Java or Python quickstart.

Delegate domain-wide authority to your service account

The service account must now be granted domain-wide access to the user data for your Google Apps domain. There are two flows to do this:

  • If the service account is listed as an app on the Google Apps Marketplace, then domain-wide access to user data is granted during the installation of that app.
  • If the service account isn't listed as an app, but is a custom integration, then the domain administrator of Google Apps needs to perform the following procedure.
  1. Open your G Suite domain control panel, at https://www.google.com/a/cpanel/example.com.
  2. Click on the Security icon. This can sometimes be found in the More controls option.
  3. Go to Advanced settings > Authentication > Manage OAuth client access.
  4. In the Client Name field enter the service account's Client ID.
  5. In the One or More API Scopes field enter the list of scopes that your app should be granted access to.
  6. Click the Authorize button.

Instantiate a Plus service object

This section shows how to instantiate a Plus service object and then authorize it to make API requests using OAuth 2.0 and your service account's credentials to perform Google Apps Domain-wide delegation. You should now have the service account's private key file in a PKCS #12 format and the email address of the service account.

Java

import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.javanet.NetHttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.client.json.jackson.JacksonFactory;
import com.google.api.services.plusDomains.PlusDomains;

import java.io.IOException;
import java.security.GeneralSecurityException;
import java.util.Arrays;
import java.util.List;

// Fill in the following values based upon the previous steps
private static final String SERVICE_ACCOUNT_EMAIL = "<some-id>@developer.gserviceaccount.com";
private static final String SERVICE_ACCOUNT_PKCS12_FILE_PATH =
    "/path/to/<public_key_fingerprint>-privatekey.p12";
private static final String USER_EMAIL = "user@ink-42.com";

// List the scopes your app requires. These must match the scopes
// registered in the Admin console for your Google Apps domain.
private static final List<String> SCOPE = Arrays.asList(
    "https://www.googleapis.com/auth/plus.me",
    "https://www.googleapis.com/auth/plus.stream.write");

private static PlusDomains authenticate() throws GeneralSecurityException, IOException {
  System.out.println(String.format("Authenticate the domain for %s", USER_EMAIL));

  HttpTransport httpTransport = new NetHttpTransport();
  JsonFactory jsonFactory = new JacksonFactory();

  // Setting the sub field with USER_EMAIL allows you to make API calls using the special keyword
  // "me" in place of a user id for that user.
  GoogleCredential credential = new GoogleCredential.Builder()
      .setTransport(httpTransport)
      .setJsonFactory(jsonFactory)
      .setServiceAccountId(SERVICE_ACCOUNT_EMAIL)
      .setServiceAccountScopes(SCOPE)
      .setServiceAccountUser(USER_EMAIL)
      .setServiceAccountPrivateKeyFromP12File(
          new java.io.File(SERVICE_ACCOUNT_PKCS12_FILE_PATH))
      .build();

  // Create and return the authorized API client
  PlusDomains service = new PlusDomains.Builder(httpTransport, jsonFactory, credential).build();
  return service;
}

Python

from googleapiclient.discovery import build
from oauth2client.service_account import ServiceAccountCredentials

#  Fill in the following values based upon the previous steps
SERVICE_ACCOUNT_EMAIL = '<some-id>@developer.gserviceaccount.com'
SERVICE_ACCOUNT_PKCS12_FILE_PATH = '/path/to/<public_key_fingerprint>-privatekey.p12'
USER_EMAIL = 'user@ink-42.com'

# List the scopes your app requires. These must match the scopes
# registered in the Admin console for your Google Apps domain.
SCOPES = ['https://www.googleapis.com/auth/plus.me',
          'https://www.googleapis.com/auth/plus.stream.write']

def authenticate():
    print 'Authenticate the domain for %s' % USER_EMAIL

    # Creating delegated credentials with USER_EMAIL allows you to make API
    # calls using the special keyword 'me' in place of a user id for that user.
    credentials = ServiceAccountCredentials.from_p12_keyfile(
        SERVICE_ACCOUNT_EMAIL,
        SERVICE_ACCOUNT_PKCS12_FILE_PATH,
        'notasecret',
        scopes=SCOPES)

    credentials = credentials.create_delegated(USER_EMAIL)

    # Create and return the authorized API client
    return build('plusDomains', 'v1', credentials=credentials)

Send feedback about...

Google+ Domains API
Google+ Domains API