Menggunakan OAuth 2.0 untuk Aplikasi Server Web

Dokumen ini menjelaskan cara aplikasi server web menggunakan Library Klien Google API atau endpoint Google OAuth 2.0 untuk menerapkan otorisasi OAuth 2.0 guna mengakses YouTube Data API.

OAuth 2.0 memungkinkan pengguna berbagi data tertentu dengan aplikasi, sekaligus tetap menjaga kerahasiaan nama pengguna, sandi, dan informasi mereka lainnya. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin untuk mengupload video ke channel YouTube pengguna.

Alur OAuth 2.0 ini khusus untuk otorisasi pengguna. API ini dirancang untuk aplikasi yang dapat menyimpan informasi rahasia dan mempertahankan status. Aplikasi server web yang diberi otorisasi dengan benar dapat mengakses API saat pengguna berinteraksi dengan aplikasi atau setelah pengguna keluar dari aplikasi.

Aplikasi server web juga sering menggunakan akun layanan untuk memberikan otorisasi pada permintaan API, terutama saat memanggil Cloud API untuk mengakses data berbasis project, bukan data khusus pengguna. Aplikasi server web dapat menggunakan akun layanan bersama dengan otorisasi pengguna. Perhatikan bahwa YouTube Data API hanya mendukung alur akun layanan untuk pemilik konten YouTube yang memiliki dan mengelola beberapa channel YouTube. Secara khusus, pemilik konten dapat menggunakan akun layanan untuk memanggil metode API yang mendukung parameter permintaan onBehalfOfContentOwner.

Catatan: Mengingat implikasi keamanan untuk mendapatkan penerapan yang benar, sebaiknya gunakan library OAuth 2.0 saat berinteraksi dengan endpoint OAuth 2.0 Google. Praktik terbaiknya adalah menggunakan kode yang telah di-debug dengan baik yang disediakan oleh orang lain, dan hal ini akan membantu Anda melindungi diri sendiri dan pengguna. Untuk informasi selengkapnya, lihat Library klien.

Library klien

Contoh khusus bahasa pada halaman ini menggunakan Library Klien Google API untuk menerapkan otorisasi OAuth 2.0. Untuk menjalankan contoh kode, Anda harus menginstal library klien untuk bahasa Anda terlebih dahulu.

Saat Anda menggunakan Library Klien Google API untuk menangani alur OAuth 2.0 aplikasi, library klien akan melakukan banyak tindakan yang harus ditangani sendiri oleh aplikasi. Misalnya, kebijakan ini menentukan kapan aplikasi dapat menggunakan atau memperbarui token akses yang disimpan serta kapan aplikasi harus memperoleh kembali izin. Library klien juga menghasilkan URL pengalihan yang benar dan membantu menerapkan pengendali pengalihan yang menukar kode otorisasi dengan token akses.

Library Klien Google API untuk aplikasi sisi server tersedia untuk bahasa berikut:

• Go
• Java
• .NET
• Node.js
• PHP
• Python
• Ruby

Penting: Library klien Google API untuk JavaScript dan Login dengan Google hanya ditujukan untuk menangani OAuth 2.0 di browser pengguna. Jika Anda ingin menggunakan JavaScript di sisi server untuk mengelola interaksi OAuth 2.0 dengan Google, pertimbangkan untuk menggunakan library Node.js di platform backend Anda.

Prasyarat

Mengaktifkan API untuk project Anda

Setiap aplikasi yang memanggil Google API harus mengaktifkan API tersebut di .

Untuk mengaktifkan API untuk project Anda:

1. di .
3. Gunakan halaman Library untuk menemukan dan mengaktifkan YouTube Data API. Temukan API lain yang akan digunakan aplikasi Anda dan aktifkan juga API tersebut.

Membuat kredensial otorisasi

Setiap aplikasi yang menggunakan OAuth 2.0 untuk mengakses Google API harus memiliki kredensial otorisasi yang mengidentifikasi aplikasi ke server OAuth 2.0 Google. Langkah-langkah berikut menjelaskan cara membuat kredensial untuk project Anda. Kemudian, aplikasi Anda dapat menggunakan kredensial untuk mengakses API yang telah Anda aktifkan untuk project tersebut.

2. Klik Create credentials > OAuth client ID.
3. Pilih jenis aplikasi Aplikasi web.
4. Isi formulir, lalu klik Buat. Aplikasi yang menggunakan bahasa dan framework seperti PHP, Java, Python, Ruby, dan .NET harus menentukan URI pengalihan yang diotorisasi. URI alihan adalah endpoint tempat server OAuth 2.0 dapat mengirim respons. Endpoint ini harus mematuhi aturan validasi Google.

   Untuk pengujian, Anda dapat menentukan URI yang merujuk ke mesin lokal, seperti http://localhost:8080. Dengan mempertimbangkan hal tersebut, perlu diperhatikan bahwa semua contoh dalam dokumen ini menggunakan http://localhost:8080 sebagai URI pengalihan.

   Sebaiknya desain endpoint autentikasi aplikasi Anda agar aplikasi Anda tidak mengekspos kode otorisasi ke resource lain di halaman.

Setelah membuat kredensial, download file client_secret.json dari . Simpan file dengan aman di lokasi yang hanya dapat diakses oleh aplikasi Anda.

Penting: Jangan simpan file client_secret.json di lokasi yang dapat diakses secara publik. Selain itu, jika Anda membagikan kode sumber ke aplikasi, misalnya, di GitHub, simpan file client_secret.json di luar hierarki sumber untuk menghindari berbagi kredensial klien secara tidak sengaja.

Mengidentifikasi cakupan akses

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan sekaligus memungkinkan pengguna mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Dengan demikian, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna.

Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya identifikasi cakupan yang memerlukan izin akses aplikasi Anda.

Sebaiknya aplikasi Anda juga meminta akses ke cakupan otorisasi melalui proses otorisasi inkremental, tempat aplikasi Anda meminta akses ke data pengguna dalam konteks. Praktik terbaik ini membantu pengguna lebih mudah memahami alasan aplikasi Anda memerlukan akses yang diminta.

YouTube Data API v3 menggunakan cakupan berikut:

Teropong senjata api
https://www.googleapis.com/auth/youtube	Mengelola akun YouTube Anda
https://www.googleapis.com/auth/youtube.channel-memberships.creator	Melihat daftar pelanggan yang saat ini aktif di channel Anda, level mereka saat ini, dan kapan mereka menjadi pelanggan
https://www.googleapis.com/auth/youtube.force-ssl	Melihat, mengedit, dan secara permanen menghapus video, rating, komentar, dan teks YouTube
https://www.googleapis.com/auth/youtube.readonly	Melihat akun YouTube Anda
https://www.googleapis.com/auth/youtube.upload	Mengelola video YouTube Anda
https://www.googleapis.com/auth/youtubepartner	Melihat dan mengelola aset Anda dan konten terkait di YouTube
https://www.googleapis.com/auth/youtubepartner-channel-audit	Melihat informasi pribadi channel YouTube Anda yang relevan selama proses audit bersama partner YouTube

Dokumen Cakupan API OAuth 2.0 berisi daftar lengkap cakupan yang dapat Anda gunakan untuk mengakses Google API.

Jika aplikasi publik Anda menggunakan cakupan yang mengizinkan akses ke data pengguna tertentu, aplikasi tersebut harus menyelesaikan proses verifikasi. Jika Anda melihat aplikasi yang belum diverifikasi di layar saat menguji aplikasi, Anda harus mengirimkan permintaan verifikasi untuk menghapusnya. Cari tahu lebih lanjut tentang aplikasi yang belum diverifikasi dan dapatkan jawaban atas pertanyaan umum tentang verifikasi aplikasi di Pusat Bantuan.

Persyaratan khusus bahasa

Untuk menjalankan contoh kode dalam dokumen ini, Anda memerlukan Akun Google, akses ke Internet, dan browser web. Jika Anda menggunakan salah satu library klien API, lihat juga persyaratan khusus bahasa di bawah.

PHP

Untuk menjalankan contoh kode PHP dalam dokumen ini, Anda memerlukan:

• PHP 8.0 atau yang lebih baru dengan antarmuka command line (CLI) dan ekstensi JSON yang diinstal.
• Alat pengelolaan dependensi Composer.

• Library Klien Google API untuk PHP:

  composer require google/apiclient:^2.15.0

Lihat Library Klien Google API untuk PHP guna mengetahui informasi selengkapnya.

Python

Untuk menjalankan contoh kode Python dalam dokumen ini, Anda memerlukan:

• Python 3.7 atau yang lebih tinggi
• Alat pengelolaan paket pip.
• Rilis Library Klien Google API untuk Python 2.0:

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

• google-auth, google-auth-oauthlib, dan google-auth-httplib2 untuk otorisasi pengguna.

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

• Framework aplikasi web Python Flask.

  pip install --upgrade flask

• Library HTTP requests.

  pip install --upgrade requests

Tinjau catatan rilis library klien Google API Python jika Anda tidak dapat mengupgrade python dan panduan migrasi terkait.

Ruby

Untuk menjalankan contoh kode Ruby dalam dokumen ini, Anda memerlukan:

• Ruby 2.6 atau yang lebih baru

• Library Google Auth untuk Ruby:

  gem install googleauth

• Framework aplikasi web Ruby Sinatra.

  gem install sinatra

Node.js

Untuk menjalankan contoh kode Node.js dalam dokumen ini, Anda memerlukan:

• LTS pemeliharaan, LTS aktif, atau rilis Node.js saat ini.

• Klien Node.js Google API:

  npm install googleapis crypto express express-session

HTTP/REST

Anda tidak perlu menginstal library apa pun agar dapat langsung memanggil endpoint OAuth 2.0.

Mendapatkan token akses OAuth 2.0

Langkah-langkah berikut menunjukkan cara aplikasi Anda berinteraksi dengan server OAuth 2.0 Google untuk mendapatkan izin pengguna guna melakukan permintaan API atas nama pengguna. Aplikasi Anda harus memiliki izin tersebut sebelum dapat menjalankan permintaan Google API yang memerlukan otorisasi pengguna.

Daftar di bawah ini merangkum langkah-langkah ini dengan cepat:

1. Aplikasi Anda mengidentifikasi izin yang diperlukan.
2. Aplikasi Anda mengalihkan pengguna ke Google beserta daftar izin yang diminta.
3. Pengguna memutuskan apakah akan memberikan izin ke aplikasi Anda.
4. Aplikasi Anda akan mencari tahu keputusan pengguna.
5. Jika pengguna memberikan izin yang diminta, aplikasi Anda akan mengambil token yang diperlukan untuk membuat permintaan API atas nama pengguna.

Langkah 1: Tetapkan parameter otorisasi

Langkah pertama Anda adalah membuat permintaan otorisasi. Permintaan tersebut menetapkan parameter yang mengidentifikasi aplikasi Anda dan menentukan izin yang akan diminta pengguna untuk diberikan kepada aplikasi Anda.

• Jika menggunakan library klien Google untuk autentikasi dan otorisasi OAuth 2.0, Anda akan membuat dan mengonfigurasi objek yang menentukan parameter ini.
• Jika memanggil endpoint OAuth 2.0 Google secara langsung, Anda akan membuat URL dan menetapkan parameter di URL tersebut.

Tab di bawah menentukan parameter otorisasi yang didukung untuk aplikasi server web. Contoh khusus bahasa juga menunjukkan cara menggunakan library klien atau library otorisasi untuk mengonfigurasi objek yang menetapkan parameter tersebut.

PHP

Cuplikan kode berikut membuat objek Google\Client(), yang menentukan parameter dalam permintaan otorisasi.

Objek tersebut menggunakan informasi dari file client_secret.json untuk mengidentifikasi aplikasi Anda. (Lihat membuat kredensial otorisasi untuk mengetahui informasi selengkapnya tentang file tersebut.) Objek ini juga mengidentifikasi cakupan yang izin aksesnya diminta oleh aplikasi Anda dan URL ke endpoint autentikasi aplikasi Anda, yang akan menangani respons dari server OAuth 2.0 Google. Terakhir, kode menetapkan parameter access_type dan include_granted_scopes opsional.

Misalnya, kode ini meminta akses offline untuk mengelola akun YouTube pengguna:

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('[e-mail]');

// 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

Cuplikan kode berikut menggunakan modul google-auth-oauthlib.flow untuk membuat permintaan otorisasi.

Kode ini membuat objek Flow, yang mengidentifikasi aplikasi Anda menggunakan informasi dari file client_secret.json yang Anda download setelah membuat kredensial otorisasi. Objek tersebut juga mengidentifikasi cakupan yang izin aksesnya diminta oleh aplikasi Anda dan URL ke endpoint autentikasi aplikasi Anda, yang akan menangani respons dari server OAuth 2.0 Google. Terakhir, kode ini menetapkan parameter access_type dan include_granted_scopes opsional.

Misalnya, kode ini meminta akses offline untuk mengelola akun YouTube pengguna:

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='[e-mail]',
    # Optional, set prompt to 'consent' will prompt the user for consent
    prompt='consent')

Ruby

Gunakan file client_secrets.json yang Anda buat untuk mengonfigurasi objek klien di aplikasi Anda. Saat mengonfigurasi objek klien, Anda menentukan cakupan yang perlu diakses aplikasi, bersama dengan URL ke endpoint autentikasi aplikasi, yang akan menangani respons dari server OAuth 2.0.

Misalnya, kode ini meminta akses offline untuk mengelola akun YouTube pengguna:

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)

Aplikasi Anda menggunakan objek klien untuk melakukan operasi OAuth 2.0, seperti membuat URL permintaan otorisasi dan menerapkan token akses ke permintaan HTTP.

Node.js

Cuplikan kode berikut membuat objek google.auth.OAuth2, yang menentukan parameter dalam permintaan otorisasi.

Objek tersebut menggunakan informasi dari file client_secret.json untuk mengidentifikasi aplikasi Anda. Untuk meminta izin dari pengguna guna mengambil token akses, Anda mengalihkan mereka ke halaman izin. Untuk membuat URL halaman izin:

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
});

Catatan Penting - refresh_token hanya ditampilkan pada otorisasi pertama. Lihat detail selengkapnya di sini.

HTTP/REST

Endpoint OAuth 2.0 Google berada di https://accounts.google.com/o/oauth2/v2/auth. Endpoint ini hanya dapat diakses melalui HTTPS. Koneksi HTTP biasa ditolak.

Server otorisasi Google mendukung parameter string kueri berikut untuk aplikasi server web:

Parameter
client_id	Wajib Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di .
redirect_uri	Wajib Menentukan tempat server API mengalihkan pengguna setelah pengguna menyelesaikan alur otorisasi. Nilai ini harus sama persis dengan salah satu URI alihan yang diotorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di klien. Jika nilai ini tidak cocok dengan URI pengalihan resmi untuk client_id yang diberikan, Anda akan mendapatkan error redirect_uri_mismatch. Perhatikan bahwa skema, huruf besar/kecil, dan garis miring akhir http atau https ('/') harus cocok.
response_type	Wajib Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi. Tetapkan nilai parameter ke code untuk aplikasi server web.
scope	Wajib Daftar cakupan yang dipisahkan spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini menginformasikan layar izin yang ditampilkan Google kepada pengguna. Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang diperlukan sekaligus memungkinkan pengguna mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna. YouTube Data API v3 menggunakan cakupan berikut: Teropong senjata api https://www.googleapis.com/auth/youtube Mengelola akun YouTube Anda https://www.googleapis.com/auth/youtube.channel-memberships.creator Melihat daftar pelanggan yang saat ini aktif di channel Anda, level mereka saat ini, dan kapan mereka menjadi pelanggan https://www.googleapis.com/auth/youtube.force-ssl Melihat, mengedit, dan secara permanen menghapus video, rating, komentar, dan teks YouTube https://www.googleapis.com/auth/youtube.readonly Melihat akun YouTube Anda https://www.googleapis.com/auth/youtube.upload Mengelola video YouTube Anda https://www.googleapis.com/auth/youtubepartner Melihat dan mengelola aset Anda dan konten terkait di YouTube https://www.googleapis.com/auth/youtubepartner-channel-audit Melihat informasi pribadi channel YouTube Anda yang relevan selama proses audit bersama partner YouTube Dokumen Cakupan API OAuth 2.0 memberikan daftar lengkap cakupan yang dapat Anda gunakan untuk mengakses Google API. Sebaiknya aplikasi Anda meminta akses ke cakupan otorisasi dalam konteks jika memungkinkan. Dengan meminta akses ke data pengguna sesuai konteks, melalui otorisasi inkremental, Anda membantu pengguna lebih mudah memahami alasan aplikasi Anda memerlukan akses yang diminta.
access_type	Direkomendasikan Menunjukkan apakah aplikasi Anda dapat memuat ulang token akses saat pengguna tidak berada di browser. Nilai parameter yang valid adalah online, yang merupakan nilai default, dan offline. Tetapkan nilai ke offline jika aplikasi Anda perlu memuat ulang token akses saat pengguna tidak ada di browser. Ini adalah metode untuk memuat ulang token akses yang dijelaskan nanti dalam dokumen ini. Nilai ini menginstruksikan server otorisasi Google untuk menampilkan token refresh dan token akses saat pertama kali aplikasi Anda menukarkan kode otorisasi dengan token.
state	Direkomendasikan Menentukan nilai string apa pun yang digunakan aplikasi Anda untuk mempertahankan status antara permintaan otorisasi dan respons server otorisasi. Server menampilkan nilai persis yang Anda kirim sebagai pasangan name=value di komponen kueri URL (?) dari redirect_uri setelah pengguna menyetujui atau menolak permintaan akses aplikasi Anda. Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke resource yang benar di aplikasi Anda, mengirim nonce, dan mengurangi pemalsuan permintaan lintas situs. Karena redirect_uri dapat ditebak, menggunakan nilai state dapat meningkatkan keyakinan Anda bahwa koneksi yang masuk adalah hasil dari permintaan autentikasi. Jika Anda membuat string acak atau mengenkode hash cookie atau nilai lain yang menangkap status klien, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama, yang memberikan perlindungan terhadap serangan seperti peniruan permintaan lintas situs. Lihat dokumentasi OpenID Connect untuk mengetahui contoh cara membuat dan mengonfirmasi token state. Penting: Klien OAuth harus mencegah CSRF seperti yang disebutkan dalam Spesifikasi OAuth2 . Salah satu cara untuk melakukannya adalah dengan menggunakan parameter state untuk mempertahankan status antara permintaan otorisasi Anda dan respons server otorisasi.
include_granted_scopes	Opsional Memungkinkan aplikasi menggunakan otorisasi inkremental untuk meminta akses ke cakupan tambahan dalam konteks. Jika Anda menetapkan nilai parameter ini ke true dan permintaan otorisasi diberikan, token akses baru juga akan mencakup cakupan apa pun yang sebelumnya diberikan pengguna untuk akses aplikasi. Lihat bagian otorisasi inkremental untuk mengetahui contohnya.
enable_granular_consent	Opsional Default-nya adalah true. Jika ditetapkan ke false, izin Akun Google yang lebih terperinci akan dinonaktifkan untuk client ID OAuth yang dibuat sebelum tahun 2019. Tidak berpengaruh untuk client ID OAuth yang lebih baru, karena izin yang lebih terperinci selalu diaktifkan untuk client ID tersebut. Saat Google mengaktifkan izin terperinci untuk aplikasi, parameter ini tidak akan lagi berpengaruh.
login_hint	Opsional Jika mengetahui pengguna mana yang mencoba melakukan autentikasi, aplikasi Anda dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Autentikasi Google. Server menggunakan petunjuk untuk menyederhanakan alur login dengan mengisi otomatis kolom email di formulir login atau dengan memilih sesi multi-login yang sesuai. Tetapkan nilai parameter ke alamat email atau ID sub, yang setara dengan ID Google pengguna.
prompt	Opsional Daftar perintah yang peka huruf besar/kecil dan dipisahkan spasi untuk ditampilkan kepada pengguna. Jika Anda tidak menentukan parameter ini, pengguna hanya akan diminta saat pertama kali project Anda meminta akses. Lihat Meminta izin ulang untuk informasi selengkapnya. Nilai yang dimungkinkan adalah: none Jangan menampilkan layar autentikasi atau izin apa pun. Tidak boleh ditentukan dengan nilai lain. consent Minta izin pengguna. select_account Minta pengguna untuk memilih akun.

Langkah 2: Alihkan ke server OAuth 2.0 Google

Alihkan pengguna ke server OAuth 2.0 Google untuk memulai proses autentikasi dan otorisasi. Biasanya, hal ini terjadi saat aplikasi Anda pertama kali perlu mengakses data pengguna. Dalam kasus otorisasi inkremental, langkah ini juga terjadi saat aplikasi Anda pertama kali perlu mengakses resource tambahan yang belum memiliki izin untuk diakses.

PHP

1. Buat URL untuk meminta akses dari server OAuth 2.0 Google:

   $auth_url = $client->createAuthUrl();

2. Alihkan pengguna ke $auth_url:

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

Python

Contoh ini menunjukkan cara mengalihkan pengguna ke URL otorisasi menggunakan framework aplikasi web Flask:

return flask.redirect(authorization_url)

Ruby

1. Buat URL untuk meminta akses dari server OAuth 2.0 Google:

   auth_uri = authorizer.get_authorization_url(request: request)

2. Arahkan pengguna ke auth_uri.

Node.js

1. Gunakan URL authorizationUrl yang dihasilkan dari metode generateAuthUrl Langkah 1 untuk meminta akses dari server OAuth 2.0 Google.
2. Arahkan pengguna ke authorizationUrl.

   res.redirect(authorizationUrl);

HTTP/REST

Contoh pengalihan ke server otorisasi Google

Contoh URL di bawah meminta akses offline (access_type=offline) ke cakupan yang mengizinkan akses untuk melihat akun YouTube pengguna. API ini menggunakan otorisasi inkremental untuk memastikan bahwa token akses baru mencakup cakupan apa pun yang sebelumnya diberikan oleh pengguna untuk akses aplikasi. URL juga menetapkan nilai untuk parameter redirect_uri, response_type, dan client_id yang diperlukan serta untuk parameter state. URL berisi baris baru dan spasi agar lebih mudah dibaca.

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

Setelah Anda membuat URL permintaan, alihkan pengguna ke URL tersebut.

Server OAuth 2.0 Google mengautentikasi pengguna dan mendapatkan izin dari pengguna agar aplikasi Anda dapat mengakses cakupan yang diminta. Respons dikirim kembali ke aplikasi Anda menggunakan URL alihan yang Anda tentukan.

Langkah 3: Google meminta izin pengguna

Pada langkah ini, pengguna memutuskan apakah akan memberikan akses yang diminta ke aplikasi Anda. Pada tahap ini, Google menampilkan jendela izin yang menampilkan nama aplikasi Anda dan layanan Google API yang meminta izin untuk diakses dengan kredensial otorisasi pengguna dan ringkasan cakupan akses yang akan diberikan. Pengguna kemudian dapat mengizinkan pemberian akses ke satu atau beberapa cakupan yang diminta oleh aplikasi Anda atau menolak permintaan tersebut.

Aplikasi Anda tidak perlu melakukan apa pun pada tahap ini karena menunggu respons dari server OAuth 2.0 Google yang menunjukkan apakah akses diberikan atau tidak. Respons tersebut dijelaskan di langkah berikutnya.

Error

Permintaan ke endpoint otorisasi OAuth 2.0 Google dapat menampilkan pesan error yang ditampilkan kepada pengguna, bukan alur autentikasi dan otorisasi yang diharapkan. Kode error umum dan solusi yang disarankan tercantum di bawah.

admin_policy_enforced

Akun Google tidak dapat memberikan otorisasi untuk satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace-nya. Lihat artikel bantuan Admin Google Workspace Mengontrol aplikasi pihak ketiga & internal yang mengakses data Google Workspace untuk mengetahui informasi selengkapnya tentang cara administrator dapat membatasi akses ke semua cakupan atau cakupan sensitif dan dibatasi hingga akses diberikan secara eksplisit ke client ID OAuth Anda.

disallowed_useragent

Endpoint otorisasi ditampilkan di dalam agen pengguna tersemat yang tidak diizinkan oleh Kebijakan OAuth 2.0 Google.

Android

Developer Android mungkin melihat pesan error ini saat membuka permintaan otorisasi di android.webkit.WebView. Sebagai gantinya, developer harus menggunakan library Android seperti Login dengan Google untuk Android atau AppAuth untuk Android OpenID Foundation.

Developer web mungkin mengalami error ini saat aplikasi Android membuka link web umum di agen pengguna tersemat dan pengguna membuka endpoint otorisasi OAuth 2.0 Google dari situs Anda. Developer harus mengizinkan link umum dibuka di pengendali link default sistem operasi, yang mencakup pengendali Link Aplikasi Android atau aplikasi browser default. Library Tab Kustom Android juga merupakan opsi yang didukung.

iOS

Developer iOS dan macOS mungkin mengalami error ini saat membuka permintaan otorisasi di WKWebView. Sebagai gantinya, developer harus menggunakan library iOS seperti Google Sign-In untuk iOS atau AppAuth untuk iOS OpenID Foundation.

Developer web mungkin mengalami error ini saat aplikasi iOS atau macOS membuka link web umum di agen pengguna tersemat dan pengguna membuka endpoint otorisasi OAuth 2.0 Google dari situs Anda. Developer harus mengizinkan link umum dibuka di pengendali link default sistem operasi, yang mencakup pengendali Universal Links atau aplikasi browser default. Library SFSafariViewController juga merupakan opsi yang didukung.

org_internal

Client ID OAuth dalam permintaan adalah bagian dari project yang membatasi akses ke Akun Google di Organisasi Google Cloud tertentu. Untuk informasi selengkapnya tentang opsi konfigurasi ini, lihat bagian Jenis pengguna dalam artikel bantuan Menyiapkan layar izin OAuth.

invalid_client

Rahasia klien OAuth salah. Tinjau konfigurasi klien OAuth, termasuk client ID dan secret yang digunakan untuk permintaan ini.

invalid_grant

Saat memuat ulang token akses atau menggunakan otorisasi inkremental, token mungkin sudah tidak berlaku atau telah dibatalkan validasinya. Lakukan autentikasi ulang pengguna dan minta izin pengguna untuk mendapatkan token baru. Jika Anda terus melihat error ini, pastikan aplikasi Anda telah dikonfigurasi dengan benar dan Anda menggunakan token dan parameter yang benar dalam permintaan Anda. Jika tidak, akun pengguna mungkin telah dihapus atau dinonaktifkan.

redirect_uri_mismatch

redirect_uri yang diteruskan dalam permintaan otorisasi tidak cocok dengan URI pengalihan yang diberi otorisasi untuk client ID OAuth. Tinjau URI pengalihan yang sah di .

Parameter redirect_uri dapat merujuk ke alur out-of-band (OOB) OAuth yang tidak digunakan lagi dan tidak didukung lagi. Lihat panduan migrasi untuk mengupdate integrasi Anda.

invalid_request

Ada yang salah dengan permintaan yang Anda buat. Hal ini dapat disebabkan oleh sejumlah alasan:

• Permintaan tidak diformat dengan benar
• Permintaan tidak memiliki parameter yang diperlukan
• Permintaan menggunakan metode otorisasi yang tidak didukung Google. Memverifikasi integrasi OAuth Anda menggunakan metode integrasi yang direkomendasikan

Langkah 4: Tangani respons server OAuth 2.0

Penting: Sebelum menangani respons OAuth 2.0 di server, Anda harus mengonfirmasi bahwa state yang diterima dari Google cocok dengan state yang dikirim dalam permintaan otorisasi. Verifikasi ini membantu memastikan bahwa pengguna, bukan skrip malicious, yang membuat permintaan dan mengurangi risiko serangan CSRF.

Server OAuth 2.0 merespons permintaan akses aplikasi Anda menggunakan URL yang ditentukan dalam permintaan.

Jika pengguna menyetujui permintaan akses, respons akan berisi kode otorisasi. Jika pengguna tidak menyetujui permintaan, respons akan berisi pesan error. Kode otorisasi atau pesan error yang ditampilkan ke server web akan muncul di string kueri, seperti yang ditunjukkan di bawah ini:

Respons error:

https://oauth2.example.com/auth?error=access_denied

Respons kode otorisasi:

https://oauth2.example.com/auth?code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7

Penting: Jika endpoint respons Anda merender halaman HTML, semua resource di halaman tersebut akan dapat melihat kode otorisasi di URL. Skrip dapat membaca URL secara langsung, dan URL di header HTTP Referer dapat dikirim ke salah satu atau semua resource di halaman.

Pertimbangkan dengan cermat apakah Anda ingin mengirim kredensial otorisasi ke semua resource di halaman tersebut (terutama skrip pihak ketiga seperti plugin sosial dan analisis). Untuk menghindari masalah ini, sebaiknya server menangani permintaan terlebih dahulu, lalu mengalihkan ke URL lain yang tidak menyertakan parameter respons.

Contoh respons server OAuth 2.0

Anda dapat menguji alur ini dengan mengklik URL contoh berikut, yang meminta akses hanya baca untuk melihat metadata berbagai file di Google Drive dan akses hanya baca untuk melihat acara Google Kalender:

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

Setelah menyelesaikan alur OAuth 2.0, Anda akan dialihkan ke http://localhost/oauth2callback, yang kemungkinan akan menghasilkan error 404 NOT FOUND kecuali jika komputer lokal Anda menayangkan file di alamat tersebut. Langkah berikutnya memberikan detail selengkapnya tentang informasi yang ditampilkan dalam URI saat pengguna dialihkan kembali ke aplikasi Anda.

Langkah 5: Tukarkan kode otorisasi untuk token refresh dan akses

Setelah menerima kode otorisasi, server web dapat menukar kode otorisasi dengan token akses.

PHP

Untuk menukarkan kode otorisasi dengan token akses, gunakan metode fetchAccessTokenWithAuthCode:

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

Python

Di halaman callback, gunakan library google-auth untuk memverifikasi respons server otorisasi. Kemudian, gunakan metode flow.fetch_token untuk menukar kode otorisasi dalam respons tersebut dengan token akses:

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 the session.
# ACTION ITEM for developers:
#     Store user's access and refresh tokens in your data store if
#     incorporating this code into your real app.
credentials = flow.credentials
flask.session['credentials'] = {
    'token': credentials.token,
    'refresh_token': credentials.refresh_token,
    'token_uri': credentials.token_uri,
    'client_id': credentials.client_id,
    'client_secret': credentials.client_secret,
    'granted_scopes': credentials.granted_scopes}

Ruby

Di halaman callback, gunakan library googleauth untuk memverifikasi respons server otorisasi. Gunakan metode authorizer.handle_auth_callback_deferred untuk menyimpan kode otorisasi dan mengalihkan kembali ke URL yang awalnya meminta otorisasi. Tindakan ini menunda pertukaran kode dengan menyimpan hasil untuk sementara di sesi pengguna.

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

Node.js

Untuk menukarkan kode otorisasi dengan token akses, gunakan metode getToken:

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

Untuk menukarkan kode otorisasi dengan token akses, panggil endpoint https://oauth2.googleapis.com/token dan tetapkan parameter berikut:

Kolom
client_id	Client ID yang diperoleh dari .
client_secret	Rahasia klien yang diperoleh dari .
code	Kode otorisasi yang ditampilkan dari permintaan awal.
grant_type	Seperti yang ditentukan dalam spesifikasi OAuth 2.0, nilai kolom ini harus ditetapkan ke authorization_code.
redirect_uri	Salah satu URI pengalihan yang tercantum untuk project Anda di untuk client_id yang diberikan.

Cuplikan berikut menunjukkan contoh permintaan:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&
client_id=your_client_id&
client_secret=your_client_secret&
redirect_uri=https%3A//oauth2.example.com/code&
grant_type=authorization_code

Google merespons permintaan ini dengan menampilkan objek JSON yang berisi token akses dengan masa berlaku singkat dan token refresh. Perhatikan bahwa token refresh hanya ditampilkan jika aplikasi Anda menetapkan parameter access_type ke offline dalam permintaan awal ke server otorisasi Google.

Respons berisi kolom berikut:

Kolom
access_token	Token yang dikirimkan aplikasi Anda untuk memberikan otorisasi pada permintaan Google API.
expires_in	Masa berlaku token akses yang tersisa dalam hitungan detik.
refresh_token	Token yang dapat Anda gunakan untuk mendapatkan token akses baru. Token refresh berlaku hingga pengguna mencabut akses. Sekali lagi, kolom ini hanya ada dalam respons ini jika Anda menetapkan parameter access_type ke offline dalam permintaan awal ke server otorisasi Google.
scope	Cakupan akses yang diberikan oleh access_token yang dinyatakan sebagai daftar string yang peka huruf besar/kecil dan dipisahkan spasi.
token_type	Jenis token yang ditampilkan. Saat ini, nilai kolom ini selalu ditetapkan ke Bearer.

Penting: Aplikasi Anda harus menyimpan kedua token di lokasi yang aman dan berumur panjang yang dapat diakses di antara berbagai pemanggilan aplikasi Anda. Token refresh memungkinkan aplikasi Anda mendapatkan token akses baru jika masa berlaku token yang Anda miliki berakhir. Dengan demikian, jika aplikasi Anda kehilangan token refresh, pengguna harus mengulangi alur izin OAuth 2.0 agar aplikasi Anda dapat memperoleh token refresh baru.

Cuplikan berikut menunjukkan contoh respons:

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

Catatan: Aplikasi Anda harus mengabaikan kolom yang tidak dikenal yang disertakan dalam respons.

Error

Saat menukarkan kode otorisasi dengan token akses, Anda mungkin mengalami error berikut, bukan respons yang diharapkan. Kode error umum dan resolusi yang disarankan tercantum di bawah.

invalid_grant

Kode otorisasi yang diberikan tidak valid atau formatnya salah. Minta kode baru dengan memulai ulang proses OAuth untuk meminta izin lagi kepada pengguna.

Langkah 6: Periksa cakupan yang diberikan pengguna

Saat meminta beberapa cakupan sekaligus, pengguna mungkin tidak memberikan semua cakupan yang diminta aplikasi Anda. Aplikasi Anda harus selalu memeriksa cakupan yang diberikan oleh pengguna dan menangani penolakan cakupan dengan menonaktifkan fitur yang relevan. Tinjau Cara menangani izin terperinci untuk mengetahui informasi selengkapnya.

PHP

Untuk memeriksa cakupan yang telah diberikan pengguna, gunakan metode getGrantedScope():

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

Python

Objek credentials yang ditampilkan memiliki properti granted_scopes, yang merupakan daftar cakupan yang telah diberikan pengguna ke aplikasi Anda.

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

Ruby

Saat meminta beberapa cakupan sekaligus, periksa cakupan mana yang diberikan melalui properti scope objek credentials.

# 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

Saat meminta beberapa cakupan sekaligus, periksa cakupan mana yang diberikan melalui properti scope objek tokens.

// 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

Untuk memeriksa apakah pengguna telah memberikan akses ke cakupan tertentu kepada aplikasi Anda, periksa kolom scope dalam respons token akses. Cakupan akses yang diberikan oleh access_token yang dinyatakan sebagai daftar string yang peka huruf besar/kecil dan dipisahkan spasi.

Misalnya, contoh respons token akses berikut menunjukkan bahwa pengguna telah memberikan izin aplikasi Anda untuk melihat, mengedit, dan menghapus secara permanen video, rating, komentar, dan teks YouTube pengguna:

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

Memanggil Google API

PHP

Gunakan token akses untuk memanggil Google API dengan menyelesaikan langkah-langkah berikut:

1. Jika Anda perlu menerapkan token akses ke objek Google\Client baru — misalnya, jika Anda menyimpan token akses dalam sesi pengguna — gunakan metode setAccessToken:

   $client->setAccessToken($access_token);

2. Buat objek layanan untuk API yang ingin Anda panggil. Anda membuat objek layanan dengan menyediakan objek Google\Client yang diotorisasi ke konstruktor untuk API yang ingin Anda panggil. Misalnya, untuk memanggil YouTube Data API:

   $youtube = new Google_Service_YouTube($client);

3. Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan. Misalnya, untuk mengambil data tentang channel YouTube pengguna yang diberi otorisasi:

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

Python

Setelah mendapatkan token akses, aplikasi Anda dapat menggunakan token tersebut untuk memberikan otorisasi pada permintaan API atas nama akun pengguna atau akun layanan tertentu. Gunakan kredensial otorisasi khusus pengguna untuk membuat objek layanan untuk API yang ingin Anda panggil, lalu gunakan objek tersebut untuk membuat permintaan API yang diotorisasi.

1. Buat objek layanan untuk API yang ingin Anda panggil. Anda membuat objek layanan dengan memanggil metode build library googleapiclient.discovery dengan nama dan versi API serta kredensial pengguna: Misalnya, untuk memanggil YouTube Data API versi 3:

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

2. Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan. Misalnya, untuk mengambil data tentang channel YouTube pengguna yang diberi otorisasi:

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

Ruby

Setelah mendapatkan token akses, aplikasi Anda dapat menggunakan token tersebut untuk membuat permintaan API atas nama akun pengguna atau akun layanan tertentu. Gunakan kredensial otorisasi khusus pengguna untuk membuat objek layanan untuk API yang ingin Anda panggil, lalu gunakan objek tersebut untuk membuat permintaan API yang diotorisasi.

1. Buat objek layanan untuk API yang ingin Anda panggil. Misalnya, untuk memanggil YouTube Data API versi 3:

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

2. Tetapkan kredensial di layanan:

   youtube.authorization = credentials

3. Buat permintaan ke layanan API menggunakan antarmuka yang disediakan oleh objek layanan. Misalnya, untuk mengambil data tentang channel YouTube pengguna yang diberi otorisasi:

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

Atau, otorisasi dapat diberikan berdasarkan per metode dengan memberikan parameter options ke metode:

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

Node.js

Setelah mendapatkan token akses dan menetapkannya ke objek OAuth2, gunakan objek tersebut untuk memanggil Google API. Aplikasi Anda dapat menggunakan token tersebut untuk mengizinkan permintaan API atas nama akun pengguna atau akun layanan tertentu. Buat objek layanan untuk API yang ingin Anda panggil. Misalnya, kode berikut menggunakan Google Drive API untuk mencantumkan nama file di Drive pengguna.

const { google } = require('googleapis');

// Example of using YouTube API to list channels.
var service = google.youtube('v3');
service.channels.list({
  auth: oauth2Client,
  part: 'snippet,contentDetails,statistics',
  forUsername: 'GoogleDevelopers'
}, function (err, response) {
  if (err) {
    console.log('The API returned an error: ' + err);
    return;
  }
  var channels = response.data.items;
  if (channels.length == 0) {
    console.log('No channel found.');
  } else {
    console.log('This channel\'s ID is %s. Its title is \'%s\', and ' +
      'it has %s views.',
      channels[0].id,
      channels[0].snippet.title,
      channels[0].statistics.viewCount);
  }
});

HTTP/REST

Setelah aplikasi Anda mendapatkan token akses, Anda dapat menggunakan token tersebut untuk melakukan panggilan ke Google API atas nama akun pengguna tertentu jika cakupan akses yang diperlukan oleh API telah diberikan. Untuk melakukannya, sertakan token akses dalam permintaan ke API dengan menyertakan parameter kueri access_token atau nilai Bearer header HTTP Authorization. Jika memungkinkan, header HTTP lebih disarankan karena string kueri cenderung terlihat di log server. Dalam sebagian besar kasus, Anda dapat menggunakan library klien untuk menyiapkan panggilan ke Google API (misalnya, saat memanggil YouTube Data API).

Perhatikan bahwa YouTube Data API hanya mendukung akun layanan untuk pemilik konten YouTube yang memiliki dan mengelola beberapa channel YouTube, seperti label rekaman dan studio film.

Anda dapat mencoba semua Google API dan melihat cakupannya di OAuth 2.0 Playground.

Contoh HTTP GET

Panggilan ke endpoint youtube.channels (YouTube Data API) menggunakan header HTTP Authorization: Bearer mungkin terlihat seperti berikut. Perhatikan bahwa Anda perlu menentukan token akses Anda sendiri:

GET /youtube/v3/channels?part=snippet&mine=true HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

Berikut adalah panggilan ke API yang sama untuk pengguna yang diautentikasi menggunakan parameter string kueri access_token:

GET https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Contoh curl

Anda dapat menguji perintah ini dengan aplikasi command line curl. Berikut adalah contoh yang menggunakan opsi header HTTP (lebih disukai):

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/youtube/v3/channels?part=snippet&mine=true

Atau, opsi parameter string kueri:

curl https://www.googleapis.com/youtube/v3/channels?access_token=access_token&part=snippet&mine=true

Contoh lengkap

Contoh berikut mencetak objek berformat JSON yang menampilkan informasi tentang channel YouTube pengguna setelah pengguna mengautentikasi dan memberikan otorisasi ke aplikasi untuk mengelola akun YouTube pengguna.

PHP

Untuk menjalankan contoh ini:

1. Di , tambahkan URL mesin lokal ke daftar URL alihan. Misalnya, tambahkan http://localhost:8080.
2. Buat direktori baru dan ubah ke direktori tersebut. Contoh:

   mkdir ~/php-oauth2-example
   cd ~/php-oauth2-example

3. Instal Library Klien Google API untuk PHP menggunakan Composer:

   composer require google/apiclient:^2.15.0

4. Buat file index.php dan oauth2callback.php dengan konten berikut.
5. Jalankan contoh dengan server web pengujian bawaan PHP:

   php -S localhost:8080 ~/php-oauth2-example

index.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();
$client->setAuthConfig('client_secret.json');

// User granted permission as an access token is in the session.
if (isset($_SESSION['access_token']) && $_SESSION['access_token'])
{
  $client->setAccessToken($_SESSION['access_token']);
  
  $youtube = new Google_Service_YouTube($client);
  $channel = $youtube->channels->listChannels('snippet', array('mine' => $mine));
  echo json_encode($channel);
  
}
else
{
  // Redirect users to outh2call.php which redirects users to Google OAuth 2.0
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/oauth2callback.php';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}
?>

oauth2callback.php

<?php
require_once __DIR__.'/vendor/autoload.php';

session_start();

$client = new Google\Client();

// Required, call the setAuthConfig function to load authorization credentials from
// client_secret.json file.
$client->setAuthConfigFile('client_secret.json');
$client->setRedirectUri('http://' . $_SERVER['HTTP_HOST']. $_SERVER['PHP_SELF']);

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

// Enable incremental authorization. Recommended as a best practice.
$client->setIncludeGrantedScopes(true);

// 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");

// Generate a URL for authorization as it doesn't contain code and error
if (!isset($_GET['code']) && !isset($_GET['error']))
{
  // Generate and set state value
  $state = bin2hex(random_bytes(16));
  $client->setState($state);
  $_SESSION['state'] = $state;

  // Generate a url that asks permissions.
  $auth_url = $client->createAuthUrl();
  header('Location: ' . filter_var($auth_url, FILTER_SANITIZE_URL));
}

// User authorized the request and authorization code is returned to exchange access and
// refresh tokens.
if (isset($_GET['code']))
{
  // Check the state value
  if (!isset($_GET['state']) || $_GET['state'] !== $_SESSION['state']) {
    die('State mismatch. Possible CSRF attack.');
  }

  // Get access and refresh tokens (if access_type is offline)
  $token = $client->fetchAccessTokenWithAuthCode($_GET['code']);

  /** Save access and refresh token to the session variables.
    * ACTION ITEM: In a production app, you likely want to save the
    *              refresh token in a secure persistent storage instead. */
  $_SESSION['access_token'] = $token;
  $_SESSION['refresh_token'] = $client->getRefreshToken();
  
  $redirect_uri = 'http://' . $_SERVER['HTTP_HOST'] . '/';
  header('Location: ' . filter_var($redirect_uri, FILTER_SANITIZE_URL));
}

// An error response e.g. error=access_denied
if (isset($_GET['error']))
{
  echo "Error: ". $_GET['error'];
}
?>

Python

Contoh ini menggunakan framework Flask. Aplikasi ini menjalankan aplikasi web di http://localhost:8080 yang memungkinkan Anda menguji alur OAuth 2.0. Jika membuka URL tersebut, Anda akan melihat lima link:

• Menguji permintaan API: Link ini mengarah ke halaman yang mencoba menjalankan contoh permintaan API. Jika perlu, alur otorisasi akan dimulai. Jika berhasil, halaman akan menampilkan respons API.
• Uji alur autentikasi secara langsung: Link ini mengarah ke halaman yang mencoba mengirim pengguna melalui alur otorisasi. Aplikasi meminta izin untuk mengirimkan permintaan API yang diotorisasi atas nama pengguna.
• Cabut kredensial saat ini: Link ini mengarah ke halaman yang mencabut izin yang telah diberikan pengguna ke aplikasi.
• Hapus kredensial sesi Flask: Link ini menghapus kredensial otorisasi yang disimpan dalam sesi Flask. Hal ini memungkinkan Anda melihat apa yang akan terjadi jika pengguna yang telah memberikan izin ke aplikasi Anda mencoba menjalankan permintaan API dalam sesi baru. Hal ini juga memungkinkan Anda melihat respons API yang akan diperoleh aplikasi jika pengguna telah mencabut izin yang diberikan ke aplikasi, dan aplikasi Anda masih mencoba memberikan otorisasi pada permintaan dengan token akses yang dicabut.

Catatan: Untuk menjalankan kode ini secara lokal, Anda harus mengikuti petunjuk di bagian prasyarat, termasuk menetapkan http://localhost:8080 sebagai URI alihan yang valid untuk kredensial Anda dan mendownload file client_secret.json untuk kredensial tersebut ke direktori kerja Anda.

# -*- coding: utf-8 -*-

import os
import flask
import requests

import google.oauth2.credentials
import google_auth_oauthlib.flow
import googleapiclient.discovery

# This variable specifies the name of a file that contains the OAuth 2.0
# information for this application, including its client_id and client_secret.
CLIENT_SECRETS_FILE = "client_secret.json"

# The OAuth 2.0 access scope allows for access to the
# authenticated user's account and requires requests to use an SSL connection.
SCOPES = ['https://www.googleapis.com/auth/youtube.force-ssl']
API_SERVICE_NAME = 'youtube'
API_VERSION = 'v3'

app = flask.Flask(__name__)
# Note: A secret key is included in the sample so that it works.
# If you use this code in your application, replace this with a truly secret
# key. See https://flask.palletsprojects.com/quickstart/#sessions.
app.secret_key = 'REPLACE ME - this value is here as a placeholder.'

@app.route('/')
def index():
  return print_index_table()

@app.route('/test')
def test_api_request():
  if 'credentials' not in flask.session:
  return flask.redirect('authorize')

  # Load credentials from the session.
  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  youtube = googleapiclient.discovery.build(
    API_SERVICE_NAME, API_VERSION, credentials=credentials)

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

  # Save credentials back to session in case access token was refreshed.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.jsonify(**channel)
@app.route('/authorize')
def authorize():
  # Create flow instance to manage the OAuth 2.0 Authorization Grant Flow steps.
  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES)

  # The URI created here 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 = flask.url_for('oauth2callback', _external=True)

  authorization_url, state = flow.authorization_url(
      # 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',
      # Enable incremental authorization. Recommended as a best practice.
      include_granted_scopes='true')

  # Store the state so the callback can verify the auth server response.
  flask.session['state'] = state

  return flask.redirect(authorization_url)

@app.route('/oauth2callback')
def oauth2callback():
  # Specify the state when creating the flow in the callback so that it can
  # verified in the authorization server response.
  state = flask.session['state']

  flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file(
      CLIENT_SECRETS_FILE, scopes=SCOPES, state=state)
  flow.redirect_uri = flask.url_for('oauth2callback', _external=True)

  # Use the authorization server's response to fetch the OAuth 2.0 tokens.
  authorization_response = flask.request.url
  flow.fetch_token(authorization_response=authorization_response)

  # Store credentials in the session.
  # ACTION ITEM: In a production app, you likely want to save these
  #              credentials in a persistent database instead.
  credentials = flow.credentials
  
  flask.session['credentials'] = credentials_to_dict(credentials)

  return flask.redirect(flask.url_for('test_api_request'))
  

@app.route('/revoke')
def revoke():
  if 'credentials' not in flask.session:
    return ('You need to <a href="/authorize">authorize</a> before ' +
            'testing the code to revoke credentials.')

  credentials = google.oauth2.credentials.Credentials(
    **flask.session['credentials'])

  revoke = requests.post('https://oauth2.googleapis.com/revoke',
      params={'token': credentials.token},
      headers = {'content-type': 'application/x-www-form-urlencoded'})

  status_code = getattr(revoke, 'status_code')
  if status_code == 200:
    return('Credentials successfully revoked.' + print_index_table())
  else:
    return('An error occurred.' + print_index_table())

@app.route('/clear')
def clear_credentials():
  if 'credentials' in flask.session:
    del flask.session['credentials']
  return ('Credentials have been cleared.<br><br>' +
          print_index_table())

def credentials_to_dict(credentials):
  return {'token': credentials.token,
          'refresh_token': credentials.refresh_token,
          'token_uri': credentials.token_uri,
          'client_id': credentials.client_id,
          'client_secret': credentials.client_secret,
          'granted_scopes': credentials.granted_scopes}

def print_index_table():
  return ('<table>' +
          '<tr><td><a href="/test">Test an API request</a></td>' +
          '<td>Submit an API request and see a formatted JSON response. ' +
          '    Go through the authorization flow if there are no stored ' +
          '    credentials for the user.</td></tr>' +
          '<tr><td><a href="/authorize">Test the auth flow directly</a></td>' +
          '<td>Go directly to the authorization flow. If there are stored ' +
          '    credentials, you still might not be prompted to reauthorize ' +
          '    the application.</td></tr>' +
          '<tr><td><a href="/revoke">Revoke current credentials</a></td>' +
          '<td>Revoke the access token associated with the current user ' +
          '    session. After revoking credentials, if you go to the test ' +
          '    page, you should see an <code>invalid_grant</code> error.' +
          '</td></tr>' +
          '<tr><td><a href="/clear">Clear Flask session credentials</a></td>' +
          '<td>Clear the access token currently stored in the user session. ' +
          '    After clearing the token, if you <a href="/test">test the ' +
          '    API request</a> again, you should go back to the auth flow.' +
          '</td></tr></table>')

if __name__ == '__main__':
  # When running locally, disable OAuthlib's HTTPs verification.
  # ACTION ITEM for developers:
  #     When running in production *do not* leave this option enabled.
  os.environ['OAUTHLIB_INSECURE_TRANSPORT'] = '1'

  # This disables the requested scopes and granted scopes check.
  # If users only grant partial request, the warning would not be thrown.
  os.environ['OAUTHLIB_RELAX_TOKEN_SCOPE'] = '1'

  # Specify a hostname and port that are set as a valid redirect URI
  # for your API project in the .
  app.run('localhost', 8080, debug=True)

Ruby

Contoh ini menggunakan framework Sinatra.

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

require 'google/apis/youtube_v3'

require 'sinatra'

configure do
  enable :sessions

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

  # Required, scope value
  # Access scopes for retrieving data about the user's YouTube channel.
  scope = 'Google::Apis::YoutubeV3::AUTH_YOUTUBE_FORCE_SSL'

  # Required, Authorizers require a storage instance to manage long term persistence of
  # access and refresh tokens.
  set :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.
  set :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.
  set :authorizer, Google::Auth::WebUserAuthorizer.new(settings.client_id, settings.scope,
                          settings.token_store, callback_uri: settings.callback_uri)
end

get '/' do
  # NOTE: Assumes the user is already authenticated to the app
  user_id = request.session['user_id']

  # Fetch stored credentials for the user from the given request session.
  # nil if none present
  credentials = settings.authorizer.get_credentials(user_id, request)

  if credentials.nil?
    # Generate a url that asks the user to authorize requested scope(s).
    # Then, redirect user to the url.
    redirect settings.authorizer.get_authorization_url(request: request)
  end
  
  # User authorized read-only YouTube Data API permission.
  # Example of using YouTube Data API to list user's YouTube channel
  youtube = Google::Apis::YoutubeV3::YouTubeService.new
  channel = youtube.list_channels(part, :mine => mine, options: { authorization: auth_client })
  
  "<pre>#{JSON.pretty_generate(channel.to_h)}</pre>"
end

# Receive the callback from Google's OAuth 2.0 server.
get '/oauth2callback' do
  # Handle the result of the oauth callback. 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
end

Node.js

Untuk menjalankan contoh ini:

1. Di , tambahkan URL komputer lokal ke daftar URL alihan. Misalnya, tambahkan http://localhost.
2. Pastikan Anda telah menginstal LTS pemeliharaan, LTS aktif, atau rilis Node.js saat ini.
3. Buat direktori baru dan ubah ke direktori tersebut. Contoh:

   mkdir ~/nodejs-oauth2-example
   cd ~/nodejs-oauth2-example

4. Instal Library Klien Google API untuk Node.js menggunakan npm:

   npm install googleapis

5. Buat file main.js dengan konten berikut.
6. Jalankan contoh:

   node .\main.js

main.js

const http = require('http');
const https = require('https');
const url = require('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.
 * 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'
];

/* Global variable that stores user credential in this code example.
 * ACTION ITEM for developers:
 *   Store user's refresh token in your data store if
 *   incorporating this code into your real app.
 *   For more information on handling refresh tokens,
 *   see https://github.com/googleapis/google-api-nodejs-client#handling-refresh-tokens
 */
let userCredential = null;

async function main() {
  const app = express();

  app.use(session({
    secret: 'your_secure_secret_key', // Replace with a strong secret
    resave: false,
    saveUninitialized: false,
  }));

  // Example on redirecting user to Google's OAuth 2.0 server.
  app.get('/', async (req, res) => {
    // 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
    });

    res.redirect(authorizationUrl);
  });

  // Receive the callback from Google's OAuth 2.0 server.
  app.get('/oauth2callback', async (req, res) => {
    // Handle the OAuth 2.0 server response
    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);

      /** Save credential to the global variable in case access token was refreshed.
        * ACTION ITEM: In a production app, you likely want to save the refresh token
        *              in a secure persistent database instead. */
      userCredential = tokens;
      
      // Example of using YouTube API to list channels.
      var service = google.youtube('v3');
      service.channels.list({
        auth: oauth2Client,
        part: 'snippet,contentDetails,statistics',
        forUsername: 'GoogleDevelopers'
      }, function (err, response) {
        if (err) {
          console.log('The API returned an error: ' + err);
          return;
        }
        var channels = response.data.items;
        if (channels.length == 0) {
          console.log('No channel found.');
        } else {
          console.log('This channel\'s ID is %s. Its title is \'%s\', and ' +
            'it has %s views.',
            channels[0].id,
            channels[0].snippet.title,
            channels[0].statistics.viewCount);
        }
      });
    }
  });

  // Example on revoking a token
  app.get('/revoke', async (req, res) => {
    // Build the string for the POST request
    let postData = "token=" + userCredential.access_token;

    // Options for POST request to Google's OAuth 2.0 server to revoke a token
    let postOptions = {
      host: 'oauth2.googleapis.com',
      port: '443',
      path: '/revoke',
      method: 'POST',
      headers: {
        'Content-Type': 'application/x-www-form-urlencoded',
        'Content-Length': Buffer.byteLength(postData)
      }
    };

    // Set up the request
    const postReq = https.request(postOptions, function (res) {
      res.setEncoding('utf8');
      res.on('data', d => {
        console.log('Response: ' + d);
      });
    });

    postReq.on('error', error => {
      console.log(error)
    });

    // Post the request with data
    postReq.write(postData);
    postReq.end();
  });


  const server = http.createServer(app);
  server.listen(8080);
}
main().catch(console.error);

HTTP/REST

Contoh Python ini menggunakan framework Flask dan library Requests untuk mendemonstrasikan alur web OAuth 2.0. Sebaiknya gunakan Library Klien Google API untuk Python untuk alur ini. (Contoh di tab Python menggunakan library klien.)

import json
import flask
import requests

app = flask.Flask(__name__)

# To get these credentials (CLIENT_ID CLIENT_SECRET) and for your application, visit
# https://console.cloud.google.com/apis/credentials.
CLIENT_ID = '123456789.apps.googleusercontent.com'
CLIENT_SECRET = 'abc123'  # Read from a file or environmental variable in a real app

# Access scopes for YouTube API
SCOPE = 'https://www.googleapis.com/auth/youtube.force-ssl'

# 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.
REDIRECT_URI = 'http://example.com/oauth2callback'

@app.route('/')
def index():
  if 'credentials' not in flask.session:
    return flask.redirect(flask.url_for('oauth2callback'))

  credentials = json.loads(flask.session['credentials'])

  if credentials['expires_in'] <= 0:
    return flask.redirect(flask.url_for('oauth2callback'))
  else: 
    headers = {'Authorization': 'Bearer {}'.format(credentials['access_token'])}
    req_uri = 'https://www.googleapis.com/youtube/v3/channels/list'
    r = requests.get(req_uri, headers=headers)
    return r.text 

@app.route('/oauth2callback')
def oauth2callback():
  if 'code' not in flask.request.args:
    state = str(uuid.uuid4())
    flask.session['state'] = state
    # Generate a url that asks permissions for the Drive activity
    # and Google Calendar scope. Then, redirect user to the url.
    auth_uri = ('https://accounts.google.com/o/oauth2/v2/auth?response_type=code'
                '&client_id={}&redirect_uri={}&scope={}&state={}').format(CLIENT_ID, REDIRECT_URI,
                                                                          SCOPE, state)
    return flask.redirect(auth_uri)
  else:
    if 'state' not in flask.request.args or flask.request.args['state'] != flask.session['state']:
      return 'State mismatch. Possible CSRF attack.', 400

    auth_code = flask.request.args.get('code')
    data = {'code': auth_code,
            'client_id': CLIENT_ID,
            'client_secret': CLIENT_SECRET,
            'redirect_uri': REDIRECT_URI,
            'grant_type': 'authorization_code'}

    # Exchange authorization code for access and refresh tokens (if access_type is offline)
    r = requests.post('https://oauth2.googleapis.com/token', data=data)
    flask.session['credentials'] = r.text
    return flask.redirect(flask.url_for('index'))

if __name__ == '__main__':
  import uuid
  app.secret_key = str(uuid.uuid4())
  app.debug = False
  app.run()

Aturan validasi URI pengalihan

Google menerapkan aturan validasi berikut untuk mengalihkan URI guna membantu developer menjaga keamanan aplikasi mereka. URI pengalihan Anda harus mematuhi aturan ini. Lihat RFC 3986 bagian 3 untuk mengetahui definisi domain, host, jalur, kueri, skema, dan userinfo, yang disebutkan di bawah.

Aturan validasi
Skema	URI pengalihan harus menggunakan skema HTTPS, bukan HTTP biasa. URI localhost (termasuk URI alamat IP localhost) dikecualikan dari aturan ini.
Host	Host tidak boleh berupa alamat IP mentah. Alamat IP localhost dikecualikan dari aturan ini.
Domain	TLD host (Domain Level Teratas) harus termasuk dalam daftar akhiran publik. Domain host tidak boleh “googleusercontent.com”. URI pengalihan tidak boleh berisi domain penyingkat URL (misalnya, goo.gl) kecuali jika aplikasi memiliki domain tersebut. Selain itu, jika aplikasi yang memiliki domain penyingkat memilih untuk mengalihkan ke domain tersebut, URI pengalihan tersebut harus berisi “/google-callback/” di jalurnya atau diakhiri dengan “/google-callback”.
Userinfo	URI alihan tidak boleh berisi subkomponen userinfo.
Jalur	URI pengalihan tidak boleh berisi path traversal (juga disebut backtracking direktori), yang direpresentasikan oleh “/..” atau “\..” atau encoding URL-nya.
Kueri	URI pengalihan tidak boleh berisi pengalihan terbuka.
Fragment	URI pengalihan tidak boleh berisi komponen fragmen.
Karakter	URI pengalihan tidak boleh berisi karakter tertentu, termasuk: Karakter pengganti ('*') Karakter ASCII yang tidak dapat dicetak Encoding persen tidak valid (encoding persen apa pun yang tidak mengikuti format encoding URL berupa tanda persen diikuti dengan dua digit heksadesimal) Karakter null (karakter NULL yang dienkode, misalnya, %00, %C0%80)

Otorisasi inkremental

Dalam protokol OAuth 2.0, aplikasi Anda meminta otorisasi untuk mengakses resource, yang diidentifikasi oleh cakupan. Meminta otorisasi untuk resource pada saat Anda membutuhkannya dianggap sebagai praktik pengalaman pengguna terbaik. Untuk mengaktifkan praktik tersebut, server otorisasi Google mendukung otorisasi inkremental. Fitur ini memungkinkan Anda meminta cakupan sesuai kebutuhan dan, jika pengguna memberikan izin untuk cakupan baru, menampilkan kode otorisasi yang dapat ditukar dengan token yang berisi semua cakupan yang telah diberikan pengguna ke project.

Misalnya, aplikasi membantu pengguna mengidentifikasi acara lokal yang menarik. Aplikasi ini memungkinkan pengguna melihat video tentang acara, memberi rating pada video, dan menambahkan video ke playlist. Pengguna juga dapat menggunakan aplikasi untuk menambahkan acara ke Google Kalender mereka.

Dalam hal ini, pada waktu login, aplikasi mungkin tidak memerlukan atau meminta akses ke cakupan apa pun. Namun, jika pengguna mencoba memberi rating pada video, menambahkan video ke playlist, atau melakukan tindakan YouTube lainnya, aplikasi dapat meminta akses ke cakupan https://www.googleapis.com/auth/youtube.force-ssl. Demikian pula, aplikasi dapat meminta akses ke cakupan https://www.googleapis.com/auth/calendar jika pengguna mencoba menambahkan acara kalender.

Untuk menerapkan otorisasi inkremental, Anda harus menyelesaikan alur normal untuk meminta token akses, tetapi pastikan permintaan otorisasi menyertakan cakupan yang diberikan sebelumnya. Pendekatan ini memungkinkan aplikasi Anda menghindari pengelolaan beberapa token akses.

Aturan berikut berlaku untuk token akses yang diperoleh dari otorisasi inkremental:

• Token dapat digunakan untuk mengakses resource yang sesuai dengan cakupan apa pun yang digabungkan ke dalam otorisasi gabungan baru.
• Saat Anda menggunakan token refresh untuk otorisasi gabungan guna mendapatkan token akses, token akses mewakili otorisasi gabungan dan dapat digunakan untuk salah satu nilai scope yang disertakan dalam respons.
• Otorisasi gabungan mencakup semua cakupan yang diberikan pengguna ke project API meskipun pemberian tersebut diminta dari klien yang berbeda. Misalnya, jika pengguna memberikan akses ke satu cakupan menggunakan klien desktop aplikasi, lalu memberikan cakupan lain ke aplikasi yang sama melalui klien seluler, otorisasi gabungan akan menyertakan kedua cakupan tersebut.
• Jika Anda mencabut token yang mewakili otorisasi gabungan, akses ke semua cakupan otorisasi tersebut atas nama pengguna terkait akan dicabut secara bersamaan.

Perhatian: memilih untuk menyertakan cakupan yang diberikan akan otomatis menambahkan cakupan yang sebelumnya diberikan oleh pengguna ke permintaan otorisasi Anda. Halaman peringatan atau error dapat ditampilkan jika aplikasi Anda saat ini tidak disetujui untuk meminta semua cakupan yang dapat ditampilkan dalam respons. Lihat Aplikasi yang belum diverifikasi untuk mengetahui informasi selengkapnya.

Contoh kode khusus bahasa di Langkah 1: Menetapkan parameter otorisasi dan contoh URL pengalihan HTTP/REST di Langkah 2: Mengalihkan ke server OAuth 2.0 Google semuanya menggunakan otorisasi inkremental. Contoh kode di bawah juga menunjukkan kode yang perlu Anda tambahkan untuk menggunakan otorisasi inkremental.

PHP

$client->setIncludeGrantedScopes(true);

Python

Di Python, tetapkan argumen kata kunci include_granted_scopes ke true untuk memastikan bahwa permintaan otorisasi menyertakan cakupan yang telah diberikan sebelumnya. Sangat mungkin bahwa include_granted_scopes tidak akan menjadi satu-satunya argumen kata kunci yang Anda tetapkan, seperti yang ditunjukkan dalam contoh di bawah.

authorization_url, state = flow.authorization_url(
    # 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',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Ruby

auth_client.update!(
  :additional_parameters => {"include_granted_scopes" => "true"}
)

Node.js

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
});

HTTP/REST

Dalam contoh ini, aplikasi panggilan meminta akses untuk mengambil data YouTube Analytics pengguna selain akses lain yang telah diberikan pengguna ke aplikasi.

GET https://accounts.google.com/o/oauth2/v2/auth?
  scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyt-analytics.readonly&
  access_type=offline&
  state=security_token%3D138rk%3Btarget_url%3Dhttp...index&
  redirect_uri=http%3A%2F%2Flocalhost%2Foauth2callback&
  response_type=code&
  client_id=client_id&
  include_granted_scopes=true

      

Refreshing an access token (offline access)

Access tokens periodically expire and become invalid credentials for a related API request. You can refresh an access token without prompting the user for permission (including when the user is not present) if you requested offline access to the scopes associated with the token.

• If you use a Google API Client Library, the client object refreshes the access token as needed as long as you configure that object for offline access.
• If you are not using a client library, you need to set the access_type HTTP query parameter to offline when redirecting the user to Google's OAuth 2.0 server. In that case, Google's authorization server returns a refresh token when you exchange an authorization code for an access token. Then, if the access token expires (or at any other time), you can use a refresh token to obtain a new access token.

Requesting offline access is a requirement for any application that needs to access a Google API when the user is not present. For example, an app that performs backup services or executes actions at predetermined times needs to be able to refresh its access token when the user is not present. The default style of access is called online.

Server-side web applications, installed applications, and devices all obtain refresh tokens during the authorization process. Refresh tokens are not typically used in client-side (JavaScript) web applications.

PHP

If your application needs offline access to a Google API, set the API client's access type to offline:

$client->setAccessType("offline");

Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

Python

Di Python, tetapkan argumen kata kunci access_type ke offline untuk memastikan bahwa Anda dapat memuat ulang token akses tanpa harus meminta izin kepada pengguna lagi. Sangat mungkin access_type bukan argumen kata kunci satu-satunya yang Anda tetapkan, seperti yang ditunjukkan dalam contoh di bawah.

authorization_url, state = flow.authorization_url(
    # 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',
    # Enable incremental authorization. Recommended as a best practice.
    include_granted_scopes='true')

Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

Ruby

Jika aplikasi Anda memerlukan akses offline ke Google API, tetapkan jenis akses klien API ke offline:

auth_client.update!(
  :additional_parameters => {"access_type" => "offline"}
)

Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

Node.js

Jika aplikasi Anda memerlukan akses offline ke Google API, tetapkan jenis akses klien API ke offline:

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
});

Setelah pengguna memberikan akses offline ke cakupan yang diminta, Anda dapat terus menggunakan klien API untuk mengakses Google API atas nama pengguna saat pengguna offline. Objek klien akan memperbarui token akses sesuai kebutuhan.

Masa berlaku token akses akan berakhir. Library ini akan otomatis menggunakan token refresh untuk mendapatkan token akses baru jika masa berlakunya akan segera berakhir. Cara mudah untuk memastikan Anda selalu menyimpan token terbaru adalah dengan menggunakan peristiwa token:

oauth2Client.on('tokens', (tokens) => {
  if (tokens.refresh_token) {
    // store the refresh_token in your secure persistent database
    console.log(tokens.refresh_token);
  }
  console.log(tokens.access_token);
});

Peristiwa token ini hanya terjadi dalam otorisasi pertama, dan Anda harus menetapkan access_type ke offline saat memanggil metode generateAuthUrl untuk menerima token refresh. Jika telah memberikan izin yang diperlukan kepada aplikasi tanpa menetapkan batasan yang sesuai untuk menerima token refresh, Anda harus memberikan otorisasi ulang ke aplikasi untuk menerima token refresh baru.

Untuk menetapkan refresh_token di lain waktu, Anda dapat menggunakan metode setCredentials:

oauth2Client.setCredentials({
  refresh_token: `STORED_REFRESH_TOKEN`
});

Setelah klien memiliki token refresh, token akses akan diperoleh dan dimuat ulang secara otomatis dalam panggilan berikutnya ke API.

HTTP/REST

Untuk memperbarui token akses, aplikasi Anda akan mengirimkan permintaan POST HTTPS ke server otorisasi Google (https://oauth2.googleapis.com/token) yang menyertakan parameter berikut:

Kolom
client_id	Client-ID yang diperoleh dari .
client_secret	Rahasia klien yang diperoleh dari .
grant_type	Seperti yang ditentukan dalam spesifikasi OAuth 2.0, nilai kolom ini harus ditetapkan ke refresh_token.
refresh_token	Token refresh yang ditampilkan dari pertukaran kode otorisasi.

Cuplikan berikut menunjukkan contoh permintaan:

POST /token HTTP/1.1
Host: oauth2.googleapis.com
Content-Type: application/x-www-form-urlencoded

client_id=your_client_id&
client_secret=your_client_secret&
refresh_token=refresh_token&
grant_type=refresh_token

Selama pengguna belum mencabut akses yang diberikan ke aplikasi, server token akan menampilkan objek JSON yang berisi token akses baru. Cuplikan berikut menunjukkan contoh respons:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "token_type": "Bearer"
}

Perhatikan bahwa ada batasan jumlah token refresh yang akan diterbitkan; satu batasan per kombinasi klien/pengguna, dan satu lagi per pengguna di semua klien. Anda harus menyimpan token refresh dalam penyimpanan jangka panjang dan terus menggunakannya selama token tersebut tetap valid. Jika aplikasi Anda meminta terlalu banyak token refresh, aplikasi tersebut mungkin akan mengalami batas ini, dalam hal ini token refresh lama akan berhenti berfungsi.

Mencabut token

Dalam beberapa kasus, pengguna mungkin ingin mencabut akses yang diberikan ke aplikasi. Pengguna dapat mencabut akses dengan membuka Setelan Akun. Lihat Bagian Hapus akses situs atau aplikasi di dokumen dukungan Situs & aplikasi pihak ketiga yang dapat mengakses akun Anda untuk mengetahui informasi selengkapnya.

Aplikasi juga dapat mencabut akses yang diberikan secara terprogram. Pencabutan terprogram penting dalam kasus saat pengguna berhenti berlangganan, menghapus aplikasi, atau resource API yang diperlukan oleh aplikasi telah berubah secara signifikan. Dengan kata lain, bagian dari proses penghapusan dapat mencakup permintaan API untuk memastikan izin yang sebelumnya diberikan ke aplikasi dihapus.

PHP

Untuk mencabut token secara terprogram, panggil revokeToken():

$client->revokeToken();

Python

Untuk mencabut token secara terprogram, buat permintaan ke https://oauth2.googleapis.com/revoke yang menyertakan token sebagai parameter dan menetapkan header Content-Type:

requests.post('https://oauth2.googleapis.com/revoke',
    params={'token': credentials.token},
    headers = {'content-type': 'application/x-www-form-urlencoded'})

Ruby

Untuk mencabut token secara terprogram, buat permintaan HTTP ke endpoint oauth2.revoke:

uri = URI('https://oauth2.googleapis.com/revoke')
response = Net::HTTP.post_form(uri, 'token' => auth_client.access_token)

Token dapat berupa token akses atau token refresh. Jika token adalah token akses dan memiliki token refresh yang sesuai, token refresh juga akan dicabut.

Jika pencabutan berhasil diproses, kode status responsnya adalah 200. Untuk kondisi error, kode status 400 ditampilkan bersama dengan kode error.

Node.js

Untuk mencabut token secara terprogram, buat permintaan POST HTTPS ke endpoint /revoke:

const https = require('https');

// Build the string for the POST request
let postData = "token=" + userCredential.access_token;

// Options for POST request to Google's OAuth 2.0 server to revoke a token
let postOptions = {
  host: 'oauth2.googleapis.com',
  port: '443',
  path: '/revoke',
  method: 'POST',
  headers: {
    'Content-Type': 'application/x-www-form-urlencoded',
    'Content-Length': Buffer.byteLength(postData)
  }
};

// Set up the request
const postReq = https.request(postOptions, function (res) {
  res.setEncoding('utf8');
  res.on('data', d => {
    console.log('Response: ' + d);
  });
});

postReq.on('error', error => {
  console.log(error)
});

// Post the request with data
postReq.write(postData);
postReq.end();

Parameter token dapat berupa token akses atau token refresh. Jika token adalah token akses dan memiliki token refresh yang sesuai, token refresh juga akan dicabut.

Jika pencabutan berhasil diproses, kode status responsnya adalah 200. Untuk kondisi error, kode status 400 ditampilkan bersama dengan kode error.

HTTP/REST

Untuk mencabut token secara terprogram, aplikasi Anda membuat permintaan ke https://oauth2.googleapis.com/revoke dan menyertakan token sebagai parameter:

curl -d -X -POST --header "Content-type:application/x-www-form-urlencoded" \
        https://oauth2.googleapis.com/revoke?token={token}

Token dapat berupa token akses atau token refresh. Jika token adalah token akses dan memiliki token refresh yang sesuai, token refresh juga akan dicabut.

Jika pencabutan berhasil diproses, kode status HTTP responsnya adalah 200. Untuk kondisi error, kode status HTTP 400 ditampilkan bersama dengan kode error.

Catatan: Setelah respons pencabutan berhasil, mungkin perlu waktu beberapa saat sebelum pencabutan tersebut berlaku sepenuhnya.

Menerapkan Perlindungan Lintas Akun

Langkah tambahan yang harus Anda lakukan untuk melindungi akun pengguna adalah menerapkan Perlindungan lintas akun dengan memanfaatkan Layanan Perlindungan Lintas Akun Google. Layanan ini memungkinkan Anda berlangganan notifikasi peristiwa keamanan yang memberikan informasi kepada aplikasi tentang perubahan besar pada akun pengguna. Anda kemudian dapat menggunakan informasi tersebut untuk mengambil tindakan, bergantung pada cara Anda memutuskan untuk merespons peristiwa.

Beberapa contoh jenis peristiwa yang dikirim ke aplikasi Anda oleh Layanan Perlindungan Lintas Akun Google adalah:

• https://schemas.openid.net/secevent/risc/event-type/sessions-revoked
• https://schemas.openid.net/secevent/oauth/event-type/token-revoked
• https://schemas.openid.net/secevent/risc/event-type/account-disabled

Lihat halaman Melindungi akun pengguna dengan Perlindungan Lintas Akun untuk mengetahui informasi selengkapnya tentang cara menerapkan Perlindungan Lintas Akun dan untuk mengetahui daftar lengkap peristiwa yang tersedia.