AdSense Management API

OAuth 2.0 for web applications

Goal

This tutorial guides you through the different steps involved in a server-side or client-side OAuth 2.0 authorization flow for web applications.

Time to complete

Approximately 20 minutes.

Prerequisites
Before you start this tutorial:
Overview

Google APIs such as the AdSense Management API use the OAuth 2.0 protocol for authentication and authorization. Google supports several OAuth 2.0 flows, and in this tutorial we are going to examine the server-side and client-side authorization flow for web applications. We will also inspect the use of the approval_prompt parameter.

We will be performing all the steps in this tutorial on the Google Auth 2.0 playground and Google APIs console and examine the outcome of each and how to proceed to the following step.

The tutorial is composed of the following sections:
  1. Configure the Google OAuth 2.0 playground
  2. The server-side authorization flow
  3. The client-side authorization flow
  4. The approval_prompt parameter
  5. Summary and further readings

1. Configure the Google OAuth 2.0 playground

  1. Open the Google OAuth 2.0 playground and the Google APIs Console in a separate browser window.
  2. In the playground, open the configuration panel and select the checkbox Use your own OAuth credentials.

    Configure the OAuth 2.0 playground to use your own credentials
    Figure 1: Configure the OAuth 2.0 playground
  3. Copy the values for Client ID and Client secret for the Client ID for web applications that you have created from your project in the Google APIs console to the playground. In the API console you can find the information that you need under the tab API Access. In the API console, add https://code.google.com/oauthplayground/ as a valid redirect URI for the Client ID for web applications.

    Add redirect URI and JavaScript origins in the Google APIs console.
    Figure 2: Add redirect URI and JavaScript origins in the Google APIs console.
  4. In the playground, close the OAuth 2.0 configuration.

2. The server-side authorization flow

This flow is intended for web server applications (e.g. PHP, Java, Python, Ruby, .NET, etc.). These applications may access a Google API while the user is present at the application or after the user has left the application. This flow requires that the application can store a secret.

  1. Open the OAuth 2.0 Playground configuration and make sure that the value of OAuth flow is Server-side and the value of Access type is Offline.
  2. Select AdSense Management and then click Authorize APIs.

    Select and Authorize the API.
    Figure 3: Select and Authorize the AdSense Management API.
  3. The playground sends the following request:

    https://accounts.google.com/o/oauth2/auth?redirect_uri=https%3A%2F%2Fcode.google.com%2Foauthplayground%2F
    &response_type=code&client_id=<client_id_here>&approval_prompt=force
    &scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadsense&access_type=offline
              

    You will be redirected to the Google Authorization Server and notified of the permissions that the application is requesting. You’re also informed that the application is requesting an offline access, which means that the application is asking for permission to access your data even when you are not actively using it. This might be the case for applications that schedule update processes. We will see later how to change this option. Click Allow access to grant permission to the application and be redirected to the playground.

    Click Allow access to grant permission to the application and be redirected to the playground.
    Figure 4: Grant permission to the application.
  4. Back to the playground, on the right side of the screen we can analyze the request/response. The response contains the authorization code that we need to exchange for an access token.

    The OAuth 2.0 playground shows the content of request and response.
    Figure 5: The content of the request and the response.
  5. To get the access token, click Exchange authorization code for tokens. The playground will send the following post request:

    POST /o/oauth2/token HTTP/1.1
    Host: accounts.google.com
    content-type: application/x-www-form-urlencoded
    user-agent: google-oauth-playground
    
    code=<authorization_code_here>&redirect_uri=https%3A%2F%2Fcode.google.com%2Foauthplayground%2F
    &client_id=<client_id_here>&scope=&client_secret=<client_secret_here>
    &grant_type=authorization_code

    The authorization code is posted along with the request, and we receive in exchange a json array similar to:

    {
      "access_token" : "ya29.AHES6ZQLkr_uUxqfiyiljzVi9ImcSTmPT6LaXMr5OT6GquDVDPN5",
      "token_type" : "Bearer",
      "expires_in" : 3600,
      "refresh_token" : "1/XeVW2n0XCrdB_gT26_E83hySQBwqS-SKJolfbzfeawo"
    }
              

    We’ve just received an access_token that will expire in 3600 seconds. Because we had requested offline access, we also received a refresh_token that the application can use to renew the access_token after it has expired. Navigate to Refresh access token if you want to see how to renew the access token.

    Exchanging the authorization code for an access token in the OAuth 2.0 playground.
    Figure 6: Exchange the autorization code for an access token.
  6. To send a request to the API, we need to add our access token to the authentication headers. Copy https://www.googleapis.com/adsense/v1.4/adclients in the Request URI field, then click Send the request. The playground will send the following request:

    GET /adsense/v1.4/adclients HTTP/1.1
    Host: www.googleapis.com
    Authorization: OAuth <access_token_here>
              
    Sending an authorized request to the API from the OAuth 2.0 playground.
    Figure 7: Send an authorized request to the API.
  7. To check what happens when you request an online access, open the playground configuration and change the value of Access type accordingly, then restart the sequence from step 2).

    At 3) note that the content of the authorization panel has changed and now shows only View and manage your AdSense data.

    At 5), you can see that when we exchange the authorization code for tokens, we don’t receive the refresh token this time. In the playground, Refresh access token is disabled: you will need to get another authorization code and exchange it if you want to get another access token.

    Showing in the OAuth 2.0 playground that if we request Online access we don't receive a refresh token.
    Figure 8: Online access doens't receive a refresh token.

3. The client-side authorization flow

This flow is intended for JavaScript-centric applications. These applications may access a Google API while the user is present at the application, and we can’t trust this type of application to store refresh tokens or the Client Secret.

  1. Open the OAuth 2.0 configuration and change the value of OAuth flow to Client-side. Notice two differences with the configuration panel for the server-side flow:

    • Access type is not available anymore
    • We need to add only the OAuth Client ID
    Showing in the OAuth 2.0 playground that the Access type parameter is not available for the client-side flow.
    Figure 9: The access type parameter is not available for the client-side flow.
  2. Select AdSense Management and then click Authorize APIs.
  3. The playground sends the following request:

    https://accounts.google.com/o/oauth2/auth?redirect_uri=https%3A%2F%2Fcode.google.com%2Foauthplayground%2F
    &response_type=token&client_id=<client_id_here>&approval_prompt=force
    &scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fadsense&access_type=online
              

    The authorization panel will be shown. Click Allow access to grant permission to the application and go back to the playground.

  4. We receive only an access token, returned in the fragment as part of the access_token parameter. Other parameters included in the response are expires_in and token_type.

    Showing in the OAuth 2.0 playground that the Access token for the client-side flow does not contain a refresh token.
    Figure 10: No refresh token for the client-side flow.
  5. Once again to send a request, we need to add the access token to the authorization headers. Copy https://www.googleapis.com/adsense/v1.4/adclients in the Request URI field, then click Send the request. The playground will send the following request:

    GET /adsense/v1.4/adclients HTTP/1.1
    Host: www.googleapis.com
    Authorization: OAuth <access_token_here>
              
    Sending an authorized request to the API from the OAuth 2.0 playground.
    Figure 11: Send an authorized request to the API.

4. The approval_prompt parameter

The approval_prompt parameter is available for both flows, and indicates if the user should be re-prompted for consent. The default is auto, so a given user should only see the consent page for a given set of scopes the first time through the sequence. If the value is force, then the user sees a consent page even if they have previously given consent to your application for a given set of scopes.

  1. Open the configuration editor, and regardless of the selected flow, verify that Force approval prompt is checked.
  2. Select AdSense Management and then click Authorize APIs.
  3. In the authorization panel, click Allow access to grant permission to the application and go back to the playground.
  4. Open the tab for Step 1, then click Authorize APIs. The authorization panel will be shown again. Click Allow access to go back to the playground.
  5. Open the configuration editor and uncheck Force approval prompt. Open the tab for Step 1, then click Authorize APIs. The authorization panel is now shown this time, because of the value of the approval_prompt parameter.

5. Summary and further reading

In this tutorial we have examined OAuth 2.0 authorization flows for web applications, server-side or client-side.

Two more OAuth 2.0 authentication and authorization flows are available:

  • a flow for installed applications, meant for desktop and mobile applications
  • a flow for applications that run on devices with limited input capabilities such as game consoles, video cameras and printers.

Check the Google APIs Client Libraries to find how to integrate the Google OAuth 2.0 flows into your application.

Authentication required

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

Signing you in...

Google Developers needs your permission to do that.