Using OAuth 2.0 for Web Server Applications

PHP

To run the PHP code samples in this document, you'll need:

• PHP 8.0 or greater with the command-line interface (CLI) and JSON extension installed.
• The Composer dependency management tool.

• The Google APIs Client Library for PHP:

  composer require google/apiclient:^2.15.0

See Google APIs Client Library for PHP for more information.

Python

To run the Python code samples in this document, you'll need:

• Python 3.7 or greater
• The pip package management tool.
• The Google APIs Client Library for Python 2.0 release:

  pip install --upgrade google-api-python-client

• The google-auth, google-auth-oauthlib, and google-auth-httplib2 for user authorization.

  pip install --upgrade google-auth google-auth-oauthlib google-auth-httplib2

• The Flask Python web application framework.

  pip install --upgrade flask

• The requests HTTP library.

  pip install --upgrade requests

Review the Google API Python client library release note if you aren't able to upgrade python and associated migration guide.

Ruby

To run the Ruby code samples in this document, you'll need:

• Ruby 2.6 or greater

• The Google Auth Library for Ruby:

  gem install googleauth

• The Sinatra Ruby web application framework.

  gem install sinatra

Node.js

To run the Node.js code samples in this document, you'll need:

• The maintenance LTS, active LTS, or current release of Node.js.

• The Google APIs Node.js Client:

  npm install googleapis crypto express express-session

HTTP/REST

You don't need to install any libraries to be able to directly call the OAuth 2.0 endpoints.

PHP

The following code snippet creates a Google\Client() object, which defines the parameters in the authorization request.

That object uses information from your client_secret.json file to identify your application. (See creating authorization credentials for more about that file.) The object also identifies the scopes that your application is requesting permission to access and the URL to your application's auth endpoint, which will handle the response from Google's OAuth 2.0 server. Finally, the code sets the optional access_type and include_granted_scopes parameters.

For example, this code requests offline access to manage a user's YouTube account:

use Google\Client;

$client = new Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfig('client_secret.json');

// Required, to set the scope value, call the addScope function
$client->addScope(GOOGLE_SERVICE_YOUTUBE::YOUTUBE_FORCE_SSL);

// Required, call the setRedirectUri function to specify a valid redirect URI for the
// provided client_id
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php');

// Recommended, offline access will give you both an access and refresh token so that
// your app can refresh the access token without user interaction.
$client->setAccessType('offline');

// Recommended, call the setState function. Using a state value can increase your assurance that
// an incoming connection is the result of an authentication request.
$client->setState($sample_passthrough_value);

// Optional, if your application knows which user is trying to authenticate, it can use this
// parameter to provide a hint to the Google Authentication Server.
$client->setLoginHint('hint@example.com');

// Optional, call the setPrompt function to set "consent" will prompt the user for consent
$client->setPrompt('consent');

// Optional, call the setIncludeGrantedScopes function with true to enable incremental
// authorization
$client->setIncludeGrantedScopes(true);

Python

The following code snippet uses the google-auth-oauthlib.flow module to construct the authorization request.

The code constructs a Flow object, which identifies your application using information from the client_secret.json file that you downloaded after creating authorization credentials. That object also identifies the scopes that your application is requesting permission to access and the URL to your application's auth endpoint, which will handle the response from Google's OAuth 2.0 server. Finally, the code sets the optional access_type and include_granted_scopes parameters.

For example, this code requests offline access to manage a user's YouTube account:

import google.oauth2.credentials
import google_auth_oauthlib.flow

# Required, call the from_client_secrets_file method to retrieve the client ID from a
# client_secret.json file. The client ID (from that file) and access scopes are required. (You can
# also use the from_client_config method, which passes the client configuration as it originally
# appeared in a client secrets file but doesn't access the file itself.)
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file('client_secret.json',
    scopes=['https://www.googleapis.com/auth/youtube.force-ssl'])

# Required, indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
flow.redirect_uri = 'https://www.example.com/oauth2callback'

# Generate URL for request to Google's OAuth 2.0 server.
# Use kwargs to set optional request parameters.
authorization_url, state = flow.authorization_url(
    # Recommended, enable offline access so that you can refresh an access token without
    # re-prompting the user for permission. Recommended for web server apps.
    access_type='offline',
    # Optional, enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true',
    # Optional, if your application knows which user is trying to authenticate, it can use this
    # parameter to provide a hint to the Google Authentication Server.
    login_hint='hint@example.com',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Ruby

Use the client_secrets.json file that you created to configure a client object in your application. When you configure a client object, you specify the scopes your application needs to access, along with the URL to your application's auth endpoint, which will handle the response from the OAuth 2.0 server.

For example, this code requests offline access to manage a user's YouTube account:

require 'googleauth'
require 'googleauth/web_user_authorizer'
require 'googleauth/stores/redis_token_store'

require 'google/apis/youtube_v3'

# Required, call the from_file method to retrieve the client ID from a
# client_secret.json file.
client_id = Google::Auth::ClientId.from_file('/path/to/client_secret.json')

# Required, scope value 
scope = 'https://www.googleapis.com/auth/youtube.force-ssl'

# Required, Authorizers require a storage instance to manage long term persistence of
# access and refresh tokens.
token_store = Google::Auth::Stores::RedisTokenStore.new(redis: Redis.new)

# Required, indicate where the API server will redirect the user after the user completes
# the authorization flow. The redirect URI is required. The value must exactly
# match one of the authorized redirect URIs for the OAuth 2.0 client, which you
# configured in the API Console. If this value doesn't match an authorized URI,
# you will get a 'redirect_uri_mismatch' error.
callback_uri = '/oauth2callback'

# To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
# from the client_secret.json file. To get these credentials for your application, visit
# https://console.cloud.google.com/apis/credentials.
authorizer = Google::Auth::WebUserAuthorizer.new(client_id, scope,
                                                token_store, callback_uri)

Your application uses the client object to perform OAuth 2.0 operations, such as generating authorization request URLs and applying access tokens to HTTP requests.

Node.js

The following code snippet creates a google.auth.OAuth2 object, which defines the parameters in the authorization request.

That object uses information from your client_secret.json file to identify your application. To ask for permissions from a user to retrieve an access token, you redirect them to a consent page. To create a consent page URL:

const {google} = require('googleapis');
const crypto = require('crypto');
const express = require('express');
const session = require('express-session');

/**
 * To use OAuth2 authentication, we need access to a CLIENT_ID, CLIENT_SECRET, AND REDIRECT_URI
 * from the client_secret.json file. To get these credentials for your application, visit
 * https://console.cloud.google.com/apis/credentials.
 */
const oauth2Client = new google.auth.OAuth2(
  YOUR_CLIENT_ID,
  YOUR_CLIENT_SECRET,
  YOUR_REDIRECT_URL
);

// Access scopes for YouTube API
const scopes = [
  'https://www.googleapis.com/auth/youtube.force-ssl'
];

// Generate a secure random state value.
const state = crypto.randomBytes(32).toString('hex');

// Store state in the session
req.session.state = state;

// Generate a url that asks permissions for the Drive activity and Google Calendar scope
const authorizationUrl = oauth2Client.generateAuthUrl({
  // 'online' (default) or 'offline' (gets refresh_token)
  access_type: 'offline',
  /** Pass in the scopes array defined above.
    * Alternatively, if only one scope is needed, you can pass a scope URL as a string */
  scope: scopes,
  // Enable incremental authorization. Recommended as a best practice.
  include_granted_scopes: true,
  // Include the state parameter to reduce the risk of CSRF attacks.
  state: state
});

Important Note - The refresh_token is only returned on the first authorization. More details here.

HTTP/REST

Google's OAuth 2.0 endpoint is at https://accounts.google.com/o/oauth2/v2/auth. This endpoint is accessible only over HTTPS. Plain HTTP connections are refused.

PHP

1. Generate a URL to request access from Google's OAuth 2.0 server:

   $auth_url = $client->createAuthUrl();

2. Redirect the user to $auth_url:

   header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));

Python

This example shows how to redirect the user to the authorization URL using the Flask web application framework:

return flask.redirect(authorization_url)

Ruby

1. Generate a URL to request access from Google's OAuth 2.0 server:

   auth_uri = authorizer.get_authorization_url(request: request)

2. Redirect the user to auth_uri.

Node.js

1. Use the generated URL authorizationUrl from Step 1 generateAuthUrl method to request access from Google's OAuth 2.0 server.
2. Redirect the user to authorizationUrl.

   res.redirect(authorizationUrl);

HTTP/REST

Sample redirect to Google's authorization server

The sample URL below requests offline access (access_type=offline) to a scope that permits access to view the user's YouTube account. It uses incremental authorization to ensure that the new access token covers any scopes to which the user previously granted the application access. The URL also sets values for the required redirect_uri, response_type, and client_id parameters as well as for the state parameter. The URL contains line breaks and spaces for readability.

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 access_type=offline&
 include_granted_scopes=true&
 state=state_parameter_passthrough_value&
 redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
 response_type=code&
 client_id=client_id

After you create the request URL, redirect the user to it.

PHP

To exchange an authorization code for an access token, use the fetchAccessTokenWithAuthCode method:

$access_token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

Python

On your callback page, use the google-auth library to verify the authorization server response. Then, use the flow.fetch_token method to exchange the authorization code in that response for an access token:

state = flask.session['state']
flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
    'client_secret.json',
    scopes=['https://www.googleapis.com/auth/youtube.force-ssl'],
    state=state)
flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

authorization_response = flask.request.url
flow.fetch_token(authorization_response=authorization_response)

# Store the credentials in browser session storage, but for security: client_id, client_secret,
# and token_uri are instead stored only on the backend server.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'granted_scopes': credentials.granted_scopes}

Ruby

On your callback page, use the googleauth library to verify the authorization server response. Use the authorizer.handle_auth_callback_deferred method to save the authorization code and redirect back to the URL that originally requested authorization. This defers the exchange of the code by temporarily stashing the results in the user's session.

  target_url = Google::Auth::WebUserAuthorizer.handle_auth_callback_deferred(request)
  redirect target_url

Node.js

To exchange an authorization code for an access token, use the getToken method:

const url = require('url');

// Receive the callback from Google's OAuth 2.0 server.
app.get('/oauth2callback', async (req, res) => {
  let q = url.parse(req.url, true).query;

  if (q.error) { // An error response e.g. error=access_denied
    console.log('Error:' + q.error);
  } else if (q.state !== req.session.state) { //check state value
    console.log('State mismatch. Possible CSRF attack');
    res.end('State mismatch. Possible CSRF attack');
  } else { // Get access and refresh tokens (if access_type is offline)

    let { tokens } = await oauth2Client.getToken(q.code);
    oauth2Client.setCredentials(tokens);
});

HTTP/REST

To exchange an authorization code for an access token, call the https://oauth2.googleapis.com/token endpoint and set the following parameters:

While the use of DPoP is optional, it is recommended for increased security. The security of DPoP relies on the private key being restricted to a single device; we recommend storing it in a way that it cannot be copied off-device, for example by using TPMs, Secure Enclaves, or other hardware-backed keystores. To use DPoP, your application must generate a new, unique DPoP proof JWT for each request to the token endpoint and add it as a HTTP request header.

The following snippet shows a sample request:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded
DPoP: eyJ0eXAiOiJkcG9wK2p3dCIsImFsZyI6IkVTMjU2IiwiandrIjp7Imt0eSI6Ik\
 VDIiwieCI6Imw4dEZyaHgtMzR0VjNoUklDUkRZOXpDa0RscEJoRjQyVVFVZldWQVdCR\
 nMiLCJ5IjoiOVZFNGpmX09rX282NHpiVFRsY3VOSmFqSG10NnY5VERWclUwQ2R2R1JE\
 QSIsImNydiI6IlAtMjU2In19.eyJqdGkiOiItQndDM0VTYzZhY2MybFRjIiwiaHRtIj\
 oiUE9TVCIsImh0dSI6Imh0dHBzOi8vc2VydmVyLmV4YW1wbGUuY29tL3Rva2VuIiwia\
 WF0IjoxNTYyMjYyNjE2fQ.2-GxA6T8lP4vfrg8v-FdWP0A0zdrj8igiMLvqRMUvwnQg\
 4PtFLbdLXiOSsX0x7NVY-FNyJK70nfbV37xRZT3Lg

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
redirect_uri=https%3A//developers.google.com/oauthplayground&
grant_type=authorization_code

Construct a DPoP proof

The following steps show how to construct a DPoP proof using OpenSSL from the command line:

1. Generate an EC P-256 key pair:

   openssl ecparam -name prime256v1 -genkey -noout -out dpop_private.pem
   openssl ec -in dpop_private.pem -pubout -out dpop_public.pem

2. Create the DPoP header:

   The header must include the typ, alg, and jwk (public key) claims. The x and y values are the Base64Url-encoded coordinates of your EC public key. Base64Url encode this JSON:

   {
     "typ":"dpop+jwt",
     "alg":"ES256",
     "jwk": {
       "kty":"EC",
       "x":"YOUR_PUBLIC_KEY_X",
       "y":"YOUR_PUBLIC_KEY_Y",
       "crv":"P-256"
     }
   }

3. Create the DPoP payload:

   The payload must include jti (a unique identifier for the request), htm (HTTP method, e.g., POST), htu (HTTP URI, e.g., https://oauth2.googleapis.com/token), and iat (issued at time). If you received a nonce from the server in a DPoP-Nonce header on the response to a previous request, you must include that nonce value in a nonce claim. The nonce claim is optional for authorization code exchanges and used only when the DPoP-Nonce header was previously received. Base64Url encode this JSON:

   {
     "jti":"JTI_VALUE",
     "htm":"POST",
     "htu":"https://oauth2.googleapis.com/token",
     "iat":YOUR_JWT_ISSUED_TIME,
     "nonce":"SERVER_PROVIDED_NONCE"
   }

   The jti value depends on the type of exchange:

   • For authorization code exchanges, the jti must be the Base64Url-encoded SHA256 hash of the authorization code: "jti":"BASE64URL(SHA256(AUTHORIZATION_CODE))".
   • For refresh token exchanges, the jti must be a unique per-request identifier: "jti":"YOUR_UNIQUE_PER_REQUEST_IDENTIFIER".
4. Sign the proof:

   Concatenate the encoded header and payload with a period (.), then sign the result with your private key using ES256. Note that JWS requires the signature to be in a raw R | S concatenated format (64 bytes for P-256). If using OpenSSL directly, you must convert the default ASN.1 DER-encoded signature to this raw format.

A successful exchange is indicated by a 200 OK response containing the tokens. If a valid DPoP proof is used during the exchange, the refresh token Google returns will be DPoP-bound to your key, but access tokens won't be DPoP bound. Access tokens will retain the token_type of Bearer rather than DPoP. Additionally, Google returns a DPoP-Nonce HTTP header in the response. Your client must cache this nonce and include it in the nonce claim of the DPoP proof in subsequent requests (such as when exchanging a refresh token for a new access token, or when calling DPoP-protected APIs). By using this early-issued nonce, you can avoid an extra round-trip failure (use_dpop_nonce) on your next request.

DPoP proofs must be included for token exchange requests made with DPoP-bound refresh tokens.

A failed exchange occurs if the DPoP header is missing when expected, invalid, or if the proof uses a different key than the one bound to the token. In these cases, the server returns a 400 Bad Request error. If the DPoP proof has mismatching htm or htu claims, an expired iat, a re-used jti, or an invalid signature, Google returns an invalid_dpop_proof error code. If a DPoP nonce is required, such as during a refresh token exchange, and the DPoP proof is missing a nonce claim, or the nonce value is unacceptable to the server (e.g., it is expired, has already been used, or is incorrect), Google returns a use_dpop_nonce error code along with a DPoP-Nonce HTTP header containing a new nonce that you can use in a subsequent request. Other failures might return invalid_grant.

Google responds to this request by returning a JSON object that contains a short-lived access token and a refresh token. Note that the refresh token is only returned if your application set the access_type parameter to offline in the initial request to Google's authorization server.

The response contains the following fields:

The following snippet shows a sample successful response headers and body when DPoP is used:

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
DPoP-Nonce: AN3XwJjZsjnb0ZuWkRlek8QU7wY-Zhf-5IP6tO0tORz0KgtDT1Bo8FX-w4nz3r5lnepI

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
  "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
}

PHP

To check which scopes the user has granted, use the getGrantedScope() method:

// Space-separated string of granted scopes if it exists, otherwise null.
$granted_scopes = $client->getOAuth2Service()->getGrantedScope();

Python

The returned credentials object has a granted_scopes property, which is a list of scopes the user has granted to your app.

credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'granted_scopes': credentials.granted_scopes}

Ruby

When requesting multiple scopes at once, check which scopes were granted through the scope property of the credentials object.

# User authorized the request. Now, check which scopes were granted.
if credentials.scope.include?(Google::Apis::YoutubeV3::AUTH_YOUTUBE_FORCE_SSL)
  # User authorized permission to see, edit, and permanently delete the
  # YouTube videos, ratings, comments and captions.
  # Calling the APIs, etc
else
  # User didn't authorize the permission.
  # Update UX and application accordingly
end

Node.js

When requesting multiple scopes at once, check which scopes were granted through the scope property of the tokens object.

// User authorized the request. Now, check which scopes were granted.
if (tokens.scope.includes('https://www.googleapis.com/auth/youtube.force-ssl'))
{
  // User authorized permission to see, edit, and permanently delete the
  // YouTube videos, ratings, comments and captions.
  // Calling the APIs, etc.
}
else
{
  // User didn't authorize read-only Drive activity permission.
  // Update UX and application accordingly
}

HTTP/REST

To check whether the user has granted your application access to a particular scope, exam the scope field in the access token response. The scopes of access granted by the access_token expressed as a list of space-delimited, case-sensitive strings.

For example, the following sample access token response indicates that the user has granted your application permission to see, edit, and permanently delete user's YouTube videos, ratings, comments and captions:

  {
    "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
    "expires_in": 3920,
    "token_type": "Bearer",
    "scope": "https://www.googleapis.com/auth/youtube.force-ssl",
    "refresh_token": "1//xEoDL4iW3cxlI7yDbSRFYNG01kVKM2C-259HOF2aQbI"
  }

PHP

Use the access token to call Google APIs by completing the following steps:

1. If you need to apply an access token to a new Google\Client object — for example, if you stored the access token in a user session — use the setAccessToken method:

   $client->setAccessToken($access_token);

2. Build a service object for the API that you want to call. You build a service object by providing an authorized Google\Client object to the constructor for the API you want to call. For example, to call the YouTube Data API:

   $youtube = new Google_Service_YouTube($client);

3. Make requests to the API service using the interface provided by the service object. For example, to retrieve data about the authorized user's YouTube channel:

   $channel = $youtube->channels->listChannels('snippet', array('mine' => $mine));

Python

After obtaining an access token, your application can use that token to authorize API requests on behalf of a given user account or service account. Use the user-specific authorization credentials to build a service object for the API that you want to call, and then use that object to make authorized API requests.

1. Build a service object for the API that you want to call. You build a service object by calling the googleapiclient.discovery library's build method with the name and version of the API and the user credentials: For example, to call version 3 of the YouTube Data API:

   from googleapiclient.discovery import build
   
   youtube = build('youtube', 'v3', credentials=credentials)

2. Make requests to the API service using the interface provided by the service object. For example, to retrieve data about the authorized user's YouTube channel:

   channel = youtube.channels().list(mine=True, part='snippet').execute()

Ruby

After obtaining an access token, your application can use that token to make API requests on behalf of a given user account or service account. Use the user-specific authorization credentials to build a service object for the API that you want to call, and then use that object to make authorized API requests.

1. Build a service object for the API that you want to call. For example, to call version 3 of the YouTube Data API:

   youtube = Google::Apis::YoutubeV3::YouTubeService.new

2. Set the credentials on the service:

   youtube.authorization = credentials

3. Make requests to the API service using the interface provided by the service object. For example, to retrieve data about the authorized user's YouTube channel:

   channel = youtube.list_channels(part, :mine => mine)

Alternately, authorization can be provided on a per-method basis by supplying the options parameter to a method:

channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client })

Node.js