Doubleclick for Publishers

Guide to Using Service Accounts with DFP

Service accounts are special Google accounts you can generate that can be used by applications to access Google APIs programmatically via OAuth 2.0. A service account uses an OAuth 2.0 flow that does not require human authorization but uses a key file that only your application can access. This guide discusses how to access the DFP API with service accounts, but note that you will require your own Google Apps domain.

Contents

  1. An alternative to service accounts
  2. Benefits of using service accounts with DFP
  3. Prerequisites
  4. Steps to using a service account to access the DFP API

An alternative to service accounts

Many developers look towards service accounts because they are interested in programmatic access to an API using OAuth with no user intervention. However, due to the complicated nature of setting up service accounts with DFP, a simpler alternative to achieve the same thing is to use the OAuth 2.0 installed application flow and persist the refresh token. This way, your application will always be able to request a new access token when necessary. The only caveat is that this process requires a user to manually authorize the application during the OAuth 2.0 installed applications flow, but this only needs to be done once since Google OAuth 2.0 refresh tokens do not expire.

Benefits of using service accounts with DFP

Using service accounts provides two major benefits:

  1. The authorization of an application to access a Google API is done as a configuration step and thus avoids the complications associated with other OAuth 2.0 flows that would otherwise require user intervention or your application to cache tokens to avoid future user intervention.
  2. OAuth 2.0 assertion flow allows for your application to impersonate other users if necessary.

The remainder of this guide walks you through the steps of how to use service accounts with the DFP API. The code samples provided use the Google Ads Java client library for DFP, but can be adapted to DFP API client libraries in other languages as well.

Prerequisites

Steps to using a service account to access the DFP API

  1. Generate a service account key in the Google Developers Console:
    1. Go to the Google Developers Console.
    2. Click on the "API Access" tab.
    3. Click on "Create another client ID..."
    4. Select "Service account" as the "Application type" and click on "Create client ID".
    5. Download your private key and store it in a safe place that only you can access.
    6. A new section called "Service account" should appear under your API Access information. Ensure this page is handy as you will need to copy the "Email address" later on.

  2. Using service accounts and assertion flow with Google OAuth 2.0 services require that you have your own domain registered with Google Apps. This is because user impersonation is controlled at the domain level with no finer granularity of access control. In other words, all users of a domain using a service account that has been whitelisted with the power to impersonate, can impersonate any user in the domain. For example, this is why Gmail accounts cannot be impersonated with service accounts.

    Security concerns

    Because of Google Apps domain-level control, it is important that you protect the *.p12 key file that allows a service account to access the Google services for which it has been authorized. This is especially the case since we are going to be granting that service account the ability to impersonate any user in the domain. It is also a good practice to allow service accounts to only access one Google API each (using the “scope” field shown in the next section). This is a preventative measure to mitigate the amount of data an attacker can access in the situation that the service account’s *.p12 key file is compromised.

    Steps to granting a service account impersonation abilities

    1. Add a new authorized API client to your Google Apps Domain by going to:
      https://www.google.com/a/cpanel/YOUR_DOMAIN/ManageOauthClients
      Note: Be sure to replace YOUR_DOMAIN with your actual domain (e.g., mydomain.com).
    2. Add a new Author API Client using the client ID we generated in the Developers Console in step 1 as the "Client Name".
    3. Enter the following for the API scope:
      https://www.google.com/apis/ads/publisher
    4. Repeat the process for all other service accounts you want to grant impersonation power to.

  3. Now you can access your DFP network using the service account via OAuth 2.0 assertion flow. In the following code example, we use our service account with OAuth 2.0 assertion flow to obtain an access token and make a basic DFP API call that gets all networks associated with that service account.
    private static Credential getOAuth2Credential() throws Exception {
      // Service account credential.
      GoogleCredential credential = new GoogleCredential.Builder().setTransport(
          new NetHttpTransport())
          .setJsonFactory(new GsonFactory())
          .setServiceAccountId(
              "****@developer.gserviceaccount.com")
          .setServiceAccountScopes("https://www.google.com/apis/ads/publisher")
          .setServiceAccountPrivateKeyFromP12File(new File("/path/to/key.p12"))
          // Set the user you are impersonating (this can be yourself).
          .setServiceAccountUser("user@yourdomain.com")
          .build();
    
      credential.refreshToken();
      return credential;
    }
    
    public static void runExample(DfpServices dfpServices, DfpSession session) throws Exception {
      // Get the NetworkService.
      NetworkServiceInterface networkService =
          dfpServices.get(session, NetworkServiceInterface.class);
    
      // Get all networks that you have access to with the current login credentials.
      Network[] networks = networkService.getAllNetworks();
    
      int i = 0;
      for (Network network : networks) {
        System.out.printf("%s) Network with network code \"%s\" and display name \"%s\" was found.\n",
            0, network.getNetworkCode(), network.getDisplayName());
        i++;
      }
    
      System.out.printf("Number of networks found: %s\n", networks.length);
    }
    
    public static void main(String[] args) throws Exception {
      // Get the OAuth2 credential.
      Credential credential = getOAuth2Credential();
    
      // Construct a DfpSession.
      DfpSession session =
          new DfpSession.Builder().fromFile().withOAuth2Credential(credential).build();
    
      DfpServices dfpServices = new DfpServices();
      runExample(dfpServices, session);
    }
            

Authentication required

You need to be signed in with Google+ to do that.

Signing you in...

Google Developers needs your permission to do that.