A service account is a type of Google account that can be used by an application to access Google APIs programmatically via OAuth 2.0. This does not require human authorization but instead uses a key file that only your application can access.
Before reading more about service accountsconsider the much simpler, and highly recommended, alternative of implementing the OAuth 2.0 installed application flow . This approach does require a user to manually authorize the application to generate a refresh token, but this only needs to be done onceas these tokens never expire.
Still reading? OK, you can implement a service account in either of the following ways:
- If your users reside on different domains, implement using a service account as a Campaign Manager 360 user . This enables you to connect to multiple accounts owned by different agencies by creating a new user profile on each account and associating them all with a single service account. This is the preferred way to use service accounts with Campaign Manager 360.
- If your users reside on a single domain that you own, implement domain-wide delegation . In this case you must have administrator access to a domain registered with G Suite . For help with G Suite and / or domain configuration see the G Suite support page .
Prerequisites
To implement a service account as a Campaign Manager 360 user, select the Campaign Manager 360 Usertab. To implement domain-wide delegation, select the Delegationtab below.
You must have access to a Campaign Manager 360 account with API access enabled.
- You must have access to a Campaign Manager 360 account with API access enabled.
- You must have administrator access to a domain registered with G Suite .
- You must have a Campaign Manager 360 user profile linked to one or more accounts under your G Suite-registered domain. User profiles linked to accounts under other domains, gmail.com for example, cannot be used.
Configuring and using a service account
To implement using a service account as a Campaign Manager 360 user, select the Campaign Manager 360 usertab. To implement domain-wide delegation, select the Delegationtab below.
- Generate a service account key
in the Google API Console.
Caution: It's important to protect the key file that grants a service account access to Google services for which it has been authorized. - Associate the Campaign Manager 360 user profile with the service account email obtained in the previous step as described in the Manage user access help center article.
- Implement the server-to-server OAuth 2.0 flow in your application, using your newly created service account. For more information, see the examples section.
- Generate a service account key
in the Google API Console.
Caution: It's important to protect the key file that grants a service account access to Google services for which it has been authorized. This is especially true for domain-wide delegation flow because of G Suite's domain-level control that gives the service account the ability to impersonate any user in the domain. It's also good practice to allow service accounts to only access one Google API each (using the "scope" field described in the next step). This is a preventative measure to mitigate the amount of data an attacker can access in the event that a service account’s key file is compromised. - Delegate domain-wide authority
to this service account to allow it to impersonate users within your domain. When prompted, provide the following API scopes:
Scope Meaning https://www.googleapis.com/auth/dfatraffickingRead/write access to Campaign Manager 360 trafficking. https://www.googleapis.com/auth/dfareportingRead/write access to Campaign Manager 360 reporting. https://www.googleapis.com/auth/ddmconversionsRead/write access to Campaign Manager 360 offline conversions. - Implement the server-to-server OAuth 2.0 flow in your application, using your newly created service account. For more information, see the examples section. Remember that you will need to provide an account to impersonate, and it must belong to the domain for which your service account was delegated domain-wide authority in the previous step.
For help with G Suite and / or domain configuration see the G Suite support page .
Examples
C#
/*
* Copyright 2015 Google Inc
*
* Licensed under the Apache License, Version 2.0(the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
using
Google.Apis.Auth.OAuth2
;
using
Google.Apis.Dfareporting.v4
;
using
Google.Apis.Dfareporting.v4.Data
;
using
Google.Apis.Json
;
using
Google.Apis.Services
;
using
System
;
using
System.Collections.Generic
;
using
System.IO
;
namespace
DfaReporting.Samples
{
/// <summary>
/// This example demonstrates how to authenticate and make a basic request using a service
/// account.
/// </summary>
class
AuthenticateUsingServiceAccount
:
SampleBase
{
/// <summary>
/// The OAuth 2.0 scopes to request.
/// </summary>
private
static
readonly
IEnumerable<string>
OAuthScopes
=
new
[]
{
DfareportingService
.
Scope
.
Dfareporting
};
/// <summary>
/// Returns a description about the code example.
/// </summary>
public
override
string
Description
{
get
{
return
"This example demonstrates how to authenticate and make a basic request"
+
" using a service account.\n"
;
}
}
/// <summary>
/// Main method, to run this code example as a standalone application.
/// </summary>
/// <param name="args">The command line arguments.</param>
public
static
void
Main
(
string
[]
args
)
{
SampleBase
codeExample
=
new
AuthenticateUsingServiceAccount
();
Console
.
WriteLine
(
codeExample
.
Description
);
codeExample
.
Run
(
null
);
}
/// <summary>
/// Run the code example.
/// </summary>
/// <param name="service">Unused</param>
public
override
void
Run
(
DfareportingService
service
)
{
string
pathToJsonFile
=
_T
(
"ENTER_PATH_TO_JSON_FILE_HERE"
);
// An optional Google account email to impersonate. Only applicable to service accounts which
// have enabled domain-wide delegation and wish to make API requests on behalf of an account
// within their domain. Setting this field will not allow you to impersonate a user from a
// domain you don't own (e.g., gmail.com).
string
emailToImpersonate
=
_T
(
""
);
// Build service account credential.
ServiceAccountCredential
credential
=
getServiceAccountCredential
(
pathToJsonFile
,
emailToImpersonate
);
// Create a Dfareporting service object.
//
// Note: application name should be replaced with a value that identifies your application.
service
=
new
DfareportingService
(
new
BaseClientService
.
Initializer
{
HttpClientInitializer
=
credential
,
ApplicationName
=
"C# service account sample"
}
);
// Retrieve and print all user profiles for the current authorized user.
UserProfileList
profiles
=
service
.
UserProfiles
.
List
().
Execute
();
foreach
(
UserProfile
profile
in
profiles
.
Items
)
{
Console
.
WriteLine
(
"Found user profile with ID {0} and name \"{1}\"."
,
profile
.
ProfileId
,
profile
.
UserName
);
}
}
private
ServiceAccountCredential
getServiceAccountCredential
(
String
pathToJsonFile
,
String
emailToImpersonate
)
{
// Load and deserialize credential parameters from the specified JSON file.
JsonCredentialParameters
parameters
;
using
(
Stream
json
=
new
FileStream
(
pathToJsonFile
,
FileMode
.
Open
,
FileAccess
.
Read
))
{
parameters
=
NewtonsoftJsonSerializer
.
Instance
.
Deserialize<JsonCredentialParameters>
(
json
);
}
// Create a credential initializer with the correct scopes.
ServiceAccountCredential
.
Initializer
initializer
=
new
ServiceAccountCredential
.
Initializer
(
parameters
.
ClientEmail
)
{
Scopes
=
OAuthScopes
};
// Configure impersonation (if applicable).
if
(
!
String
.
IsNullOrEmpty
(
emailToImpersonate
))
{
initializer
.
User
=
emailToImpersonate
;
}
// Create a service account credential object using the deserialized private key.
ServiceAccountCredential
credential
=
new
ServiceAccountCredential
(
initializer
.
FromPrivateKey
(
parameters
.
PrivateKey
));
return
credential
;
}
}
}
Java
// Copyright 2014 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
package
com.google.api.services.samples.dfareporting.auth
;
import
com.google.api.client.auth.oauth2.Credential
;
import
com.google.api.client.googleapis.auth.oauth2.GoogleCredential
;
import
com.google.api.services.dfareporting.Dfareporting
;
import
com.google.api.services.dfareporting.DfareportingScopes
;
import
com.google.api.services.dfareporting.model.UserProfileList
;
import
com.google.common.base.Strings
;
import
com.google.common.collect.ImmutableSet
;
import
java.io.FileInputStream
;
/**
* This example demonstrates how to authenticate and make a basic request using a service account.
*/
public
class
AuthenticateUsingServiceAccount
{
private
static
final
String
PATH_TO_JSON_FILE
=
"ENTER_PATH_TO_JSON_FILE_HERE"
;
/**
* An optional Google account email to impersonate. Only applicable to service accounts which have
* enabled domain-wide delegation and wish to make API requests on behalf of an account within
* their domain. Setting this field will not allow you to impersonate a user from a domain you
* don't own (e.g., gmail.com).
*/
private
static
final
String
EMAIL_TO_IMPERSONATE
=
""
;
// The OAuth 2.0 scopes to request.
private
static
final
ImmutableSet<String>
OAUTH_SCOPES
=
ImmutableSet
.
of
(
DfareportingScopes
.
DFAREPORTING
);
private
static
Credential
getServiceAccountCredential
(
String
pathToJsonFile
,
String
emailToImpersonate
)
throws
Exception
{
// Generate a credential object from the specified JSON file.
GoogleCredential
credential
=
GoogleCredential
.
fromStream
(
new
FileInputStream
(
pathToJsonFile
));
// Update the credential object with appropriate scopes and impersonation info (if applicable).
if
(
Strings
.
isNullOrEmpty
(
emailToImpersonate
))
{
credential
=
credential
.
createScoped
(
OAUTH_SCOPES
);
}
else
{
credential
=
new
GoogleCredential
.
Builder
()
.
setTransport
(
credential
.
getTransport
())
.
setJsonFactory
(
credential
.
getJsonFactory
())
.
setServiceAccountId
(
credential
.
getServiceAccountId
())
.
setServiceAccountPrivateKey
(
credential
.
getServiceAccountPrivateKey
())
.
setServiceAccountScopes
(
OAUTH_SCOPES
)
// Set the email of the user you are impersonating (this can be yourself).
.
setServiceAccountUser
(
emailToImpersonate
)
.
build
();
}
return
credential
;
}
public
static
void
runExample
(
Dfareporting
reporting
)
throws
Exception
{
// Retrieve and print all user profiles for the current authorized user.
UserProfileList
profiles
=
reporting
.
userProfiles
().
list
().
execute
();
for
(
int
i
=
0
;
i
<
profiles
.
getItems
().
size
();
i
++
)
{
System
.
out
.
printf
(
"%d) %s%n"
,
i
+
1
,
profiles
.
getItems
().
get
(
i
).
getUserName
());
}
}
public
static
void
main
(
String
[]
args
)
throws
Exception
{
// Build service account credential.
Credential
credential
=
getServiceAccountCredential
(
PATH_TO_JSON_FILE
,
EMAIL_TO_IMPERSONATE
);
// Create a Dfareporting client instance.
//
// Note: application name below should be replaced with a value that identifies your
// application. Suggested format is "MyCompany-ProductName/Version.MinorVersion".
Dfareporting
reporting
=
new
Dfareporting
.
Builder
(
credential
.
getTransport
(),
credential
.
getJsonFactory
(),
credential
)
.
setApplicationName
(
"dfareporting-java-service-acct-sample"
)
.
build
();
runExample
(
reporting
);
}
}
PHP
< ?php
/*
* Copyright 2017 Google Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
require_once dirname(__DIR__) . '/vendor/autoload.php';
/**
* This example demonstrates how to authenticate and make a basic request using
* a service account.
*
* This example is written to be run as a command line application, not as a
* webpage. An optional Google account email to impersonate may be specified as
* follows:
*
* AuthenticateUsingServiceAccount.php /path/to/client_secrets.json <email>
*
* This optional flag only applies to service accounts which have domain-wide
* delegation enabled and wish to make API requests on behalf of an account
* within that domain. Using this flag will not allow you to impersonate a user
* from a domain that you don't own (e.g., gmail.com).
*/
class AuthenticateUsingServiceAccount
{
// The OAuth 2.0 scopes to request.
private static $OAUTH_SCOPES = [
Google_Service_Dfareporting::DFAREPORTING
];
public function run($pathToJsonFile, $email = null)
{
// Create an authenticated client object.
$client = $this->createAuthenticatedClient($pathToJsonFile, $email);
// Create a Dfareporting service object.
$service = new Google_Service_Dfareporting($client);
$this->getUserProfiles($service);
}
private function createAuthenticatedClient($pathToJsonFile, $email)
{
// Create a Google_Client instance.
//
// Note: application name should be replaced with a value that identifies
// your application. Suggested format is "MyCompany-ProductName".
$client = new Google_Client();
$client->setApplicationName('PHP service account sample');
$client->setScopes(self::$OAUTH_SCOPES);
// Load the service account credentials.
$client->setAuthConfig($pathToJsonFile);
// Configure impersonation (if applicable).
if (!is_null($email)) {
$client->setSubject($email);
}
return $client;
}
private function getUserProfiles($service)
{
// Retrieve and print all user profiles for the current authorized user.
$result = $service->userProfiles->listUserProfiles();
foreach ($result['items'] as $userProfile) {
printf(
"User profile \"%s\" (ID: %d) found for account %d.\n",
$userProfile->getUserName(),
$userProfile->getProfileId(),
$userProfile->getAccountId()
);
}
}
}
if ($argc < 2 || $argc >= 4) {
printf(
"Usage: %s /path/to/client_secrets.json [email_to_impersonate]\n",
$argv[0]
);
} else {
$sample = new AuthenticateUsingServiceAccount();
if ($argc == 2) {
$sample->run($argv[1]);
} else {
$sample->run($argv[1], $argv[2]);
}
}
Python
#!/usr/bin/python
#
# Copyright 2015 Google Inc. All Rights Reserved.
#
# Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
# See the License for the specific language governing permissions and
# limitations under the License.
"""This example demonstrates how to authenticate using a service account.
An optional Google account email to impersonate may be specified as follows:
authenticate_using_service_account.py <path_to_json_file> -i <email>
This optional flag only applies to service accounts which have domain-wide
delegation enabled and wish to make API requests on behalf of an account
within that domain. Using this flag will not allow you to impersonate a
user from a domain you don't own (e.g., gmail.com).
"""
import
argparse
import
sys
from
googleapiclient
import
discovery
import
httplib2
from
oauth2client
import
client
from
oauth2client
import
tools
from
oauth2client.service_account
import
ServiceAccountCredentials
# Declare command-line flags.
argparser
=
argparse
.
ArgumentParser
(
add_help
=
False
)
argparser
.
add_argument
(
'path_to_service_account_json_file'
,
help
=
'Path to the service account JSON file to use for authenticating.'
)
argparser
.
add_argument
(
'-i'
,
'--impersonation_email'
,
help
=
'Google account email to impersonate.'
)
# The OAuth 2.0 scopes to request.
OAUTH_SCOPES
=
[
'https://www.googleapis.com/auth/dfareporting'
]
def
main
(
argv
):
# Retrieve command line arguments.
parser
=
argparse
.
ArgumentParser
(
description
=
__doc__
,
formatter_class
=
argparse
.
RawDescriptionHelpFormatter
,
parents
=
[
tools
.
argparser
,
argparser
])
flags
=
parser
.
parse_args
(
argv
[
1
:])
# Authenticate using the supplied service account credentials
http
=
authenticate_using_service_account
(
flags
.
path_to_service_account_json_file
,
flags
.
impersonation_email
)
# Construct a service object via the discovery service.
service
=
discovery
.
build
(
'dfareporting'
,
'v4'
,
http
=
http
)
try
:
# Construct the request.
request
=
service
.
userProfiles
()
.
list
()
# Execute request and print response.
response
=
request
.
execute
()
for
profile
in
response
[
'items'
]:
print
(
'Found user profile with ID
%s
and user name "
%s
".'
%
(
profile
[
'profileId'
],
profile
[
'userName'
]))
except
client
.
AccessTokenRefreshError
:
print
(
'The credentials have been revoked or expired, please re-run the '
'application to re-authorize'
)
def
authenticate_using_service_account
(
path_to_service_account_json_file
,
impersonation_email
):
"""Authorizes an httplib2.Http instance using service account credentials."""
# Load the service account credentials from the specified JSON keyfile.
credentials
=
ServiceAccountCredentials
.
from_json_keyfile_name
(
path_to_service_account_json_file
,
scopes
=
OAUTH_SCOPES
)
# Configure impersonation (if applicable).
if
impersonation_email
:
credentials
=
credentials
.
create_delegated
(
impersonation_email
)
# Use the credentials to authorize an httplib2.Http instance.
http
=
credentials
.
authorize
(
httplib2
.
Http
())
return
http
if
__name__
==
'__main__'
:
main
(
sys
.
argv
)
Ruby
#!/usr/bin/env ruby
#
# Copyright:: Copyright 2016, Google Inc. All Rights Reserved.
#
# License:: Licensed under the Apache License, Version 2.0 (the "License");
# you may not use this file except in compliance with the License.
# You may obtain a copy of the License at
#
# http://www.apache.org/licenses/LICENSE-2.0
#
# Unless required by applicable law or agreed to in writing, software
# distributed under the License is distributed on an "AS IS" BASIS,
# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
# implied.
# See the License for the specific language governing permissions and
# limitations under the License.
#
# This example demonstrates how to authenticate using a service account.
#
# An optional Google account email to impersonate may be specified as follows:
# authenticate_using_service_account.rb <path_to_json_file> --i <email>
#
# This optional flag only applies to service accounts which have domain-wide
# delegation enabled and wish to make API requests on behalf of an account
# within that domain. Using this flag will not allow you to impersonate a
# user from a domain you don't own (e.g., gmail.com).
require
'google/apis/dfareporting_v4'
require
'googleauth'
require
'optparse'
API_NAMESPACE
=
Google
::
Apis
::
DfareportingV4
def
authenticate_using_service_account
(
path_to_json_file
,
impersonation_email
)
# Create a Dfareporting service object.
#
# Note: application name should be replaced with a value that identifies
# your application. Suggested format is "MyCompany-ProductName".
service
=
API_NAMESPACE
::
DfareportingService
.
new
service
.
client_options
.
application_name
=
'Ruby service account sample'
service
.
client_options
.
application_version
=
'1.0.0'
# Generate an authorization object from the specified JSON file.
File
.
open
(
path_to_json_file
,
'r+'
)
do
|
json
|
service
.
authorization
=
Google
::
Auth
::
ServiceAccountCredentials
.
make_creds
(
json_key_io
:
json
,
scope
:
[
API_NAMESPACE
::
AUTH_DFAREPORTING
]
)
end
# Configure impersonation (if applicable).
service
.
authorization
.
sub
=
impersonation_email
unless
impersonation_email
.
nil?
service
end
def
get_userprofiles
(
service
)
# Get all user profiles.
result
=
service
.
list_user_profiles
# Display results.
result
.
items
.
each
do
|
profile
|
puts
format
(
'User profile with ID %d and name "%s" was found for account %d.'
,
profile
.
profile_id
,
profile
.
user_name
,
profile
.
account_id
)
end
end
if
$PROGRAM_NAME
==
__FILE__
# Retrieve command line arguments.
impersonation_email
=
nil
optparse
=
OptionParser
.
new
do
|
opts
|
opts
.
banner
=
format
(
'Usage: %s path_to_json_file [options]'
,
$PROGRAM_NAME
)
opts
.
on_tail
(
'-i'
,
'--impersonate EMAIL'
,
'Google account email to impersonate'
)
do
|
email
|
impersonation_email
=
email
end
end
optparse
.
parse!
if
ARGV
.
empty?
puts
optparse
exit
(
-
1
)
end
# Authenticate and initialize API service using service account.
service
=
authenticate_using_service_account
(
ARGV
.
shift
,
impersonation_email
)
get_userprofiles
(
service
)
end
