OAuth 2.0 is a new, simplified authorization protocol for Google APIs. OAuth 2.0 relies on SSL for security instead of requiring your application to do cryptographic signing directly. This protocol allows your application to request access to data associated with a user's Google Account.
The OAuth v1 protocol is a secure authentication and authorization service. This allows your web application to be given permission to access specific areas of your user's Google Apps data without revealing the users' names and passwords. The authentication examples in this document use the OAuth v1 delegated access 3-legged work flow which lets your web application access a Google Apps user's data hosted on the Google servers. When using OAuth v1, get an API key.
As your applications are extended using the full set of Google Apps APIs, you will implement a range of additional authentication and authorization protocols depending on the type of deployment. For more information about additional the Google Apps authentication and authorization protocols, see Choosing an Auth Mechanism.
Most of the examples in subsequent sections of this document assume you are providing the appropriate authentication.
OAuth scope parameter
Use the following scope for read only access to the Admin Audit API:
Use this scope for OAuth access to the customerId operation:
Getting and using a token credential
When setting up your OAuth credentials, determine your development environment, signature type and application registration. Then create your token credentials, and the OAuth signature.
Your development environment
The OAuth examples in this document use the generic XML. The operation examples use JSON.
Determine your OAuth signature and register your application
Before building up your OAuth 1.0 configuration, determine the type of OAuth signature used by your client application, and register your web application with Google.
- If your application requires enhanced security using the RSA-SHA1 signature, you must get your security certificate before registering your application with Google. The uploading of this certificate is part of the registration process. For more information, see Generating keys and certificates for use with registered mode.
- If you use a HMAC-SHA1 signature to sign your requests, no security certificate is required. For the HMAC-SHA1 signature, Google generates an OAuth consumer secret value, which is displayed on your domain's registration page after you have registered.
For more information on the registration process, see Registration for Web Applications. For more information about registering, see 'Deciding whether to register your web application'. This gives you your client credential (consumer key and secret).
Note: Do not use the OAuth non-registered option where the consumer key and consumer secret properties have 'anonymous' values. The Admin Audit API feeds are available to Google registered applications only. And all of your application's OAuth interactions must be digitally signed.
Get a token credentialFollow these general steps to obtain an a token credential. For more information, see OAuth Authentication for Web Applications:
- Get your temporary token (request token). This token is used once. (OAuthGetRequestToken)
- Ask the user to authorize the request token (OAuthAuthorizeToken)
- Exchange the authorized request token for a token credential (access token). (OAuthGetAccessToken)
Create your OAuth signature
Once you have a valid token credential, your client application can send requests with an OAuth_signature, Authorization header, and for OAuth 1.0 clients, an API key. These examples use the RSA-SHA1 signature method.
- Create the signature base string. Note, the actual string is continuous. This example
uses line returns for display purposes.
GET&https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991 &oauth_consumer_key=example.com&oauth_nonce=38863f48...28dd9fd2c &oauth_signature_method=RSA-SHA1&oauth_timestamp=1249972977 &oauth_token=1%2Fz1...LMzNBrKhElA&oauth_version=1.0&key=YOUR-DEV-CONSOLE-KEY &endTime=2010-10-28T05:14:18.345Z&maxResults=1&actorEmailfirstname.lastname@example.org
- Set the
oauth_signatureto the result of signing the base string with the algorithm you specify in
the oauth_signature_method. This requires URL-encoding the signature base string. Note, the string is continuous and this example uses line returns for display purposes.
GET&https%3A%2%2Fwww.googleapis.com%2Fapps%2Freporting%2Faudit%2Fv1 %2FC03az79cb%2FC207535951991%26%2F&oauth_consumer_key%3Dexample.com %26oauth_nonce%3D38863f48...28dd9fd2c%26oauth_signature_method%3DRSA-SHA1 %26oauth_timestamp%3D1249972977%26oauth_token%3D1%252Fz1...LMzNBrKhElA %26oauth_version%3D1.0%26key%3DYOUR-DEV-CONSOLE-KEY %26endTime%3D2010-10-28T05:14:18.345Z%26maxResults%3D1 %26actorEmail%3Djohn@example.com
- The Authorization header is similar to this example. Note, the string is continuous and
this example uses line returns for display purposes.
GET https://www.googleapis.com/apps/reporting/audit/v1/C03az79cb/207535951991 ?endTime=2010-10-28T05:14:18.345Z&maxResults=1 ...
Authorization: OAuth oauth_version="1.0", oauth_nonce="38863f48...28dd9fd2c", >oauth_timestamp="1249972977", oauth_consumer_key="example.com", oauth_token="1%2Fz1...LMzNBrKhElA", oauth_signature_method="RSA-SHA1", oauth_signature="kH%2BjQd%2Ba8...odMeUnsU%2FxANOw%3D", key=YOUR-DEV-CONSOLE-KEY
Additional OAuth reference and resources
- Beginner's Guide for OAuth, highly recommended if you are new to OAuth
- Using the OAuth Playground tool , a recommended tool for understanding the credential work flow.
- http://www.google.com/support/forum/p/apps-apis/, for questions or comments about the OAuth Playground or OAuth in general, visit the Google Apps APIs help forum
- Using OAuth with the Google Data APIs Client Libraries
- Java Client Library Overview
- OAuth for Web Applications
- Using OAuth with the Google Data APIs
- OAuth 1.0 API Reference.
- Registration for web-based applications, includes certification information.
- Authorize your application to use the 3-legged OAuth process