OAuth 2.0 untuk Aplikasi Seluler & Desktop

Dokumen ini menjelaskan cara aplikasi yang diinstal di perangkat seperti ponsel, tablet, dan komputer menggunakan endpoint OAuth 2.0 Google untuk memberi otorisasi akses ke YouTube Data API.

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

Aplikasi yang diinstal didistribusikan ke perangkat individual, dan diasumsikan bahwa aplikasi ini tidak dapat menyimpan rahasia. Aplikasi dapat mengakses Google API saat pengguna berada di aplikasi atau saat aplikasi berjalan di latar belakang.

Alur otorisasi ini mirip dengan alur yang digunakan untuk aplikasi server web. Perbedaan utamanya adalah bahwa aplikasi yang diinstal harus membuka browser sistem dan menyediakan URI pengalihan lokal untuk menangani respons dari server otorisasi Google.

Library dan contoh

Untuk aplikasi seluler, sebaiknya gunakan library native Layanan Identitas Google versi terbaru untuk Android dan library native Login dengan Google untuk iOS. Library ini menangani otorisasi pengguna dan lebih mudah diterapkan daripada protokol tingkat bawah yang dijelaskan di sini.

Untuk aplikasi yang berjalan di perangkat yang tidak mendukung browser sistem atau yang memiliki kemampuan input terbatas, seperti TV, konsol game, kamera, atau printer, lihat OAuth 2.0 untuk TV & Perangkat atau Login di TV dan Perangkat Input Terbatas.

Prasyarat

Aktifkan API untuk project Anda

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

Untuk mengaktifkan API untuk project Anda:

  1. Open the API Library di Google API Console.
  2. If prompted, select a project, or create a new one.
  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. Aplikasi Anda kemudian dapat menggunakan kredensial untuk mengakses API yang telah Anda aktifkan untuk project tersebut.

  1. Go to the Credentials page.
  2. Klik Buat klien.
  3. Bagian berikut menjelaskan jenis klien yang didukung server otorisasi Google. Pilih jenis klien yang direkomendasikan untuk aplikasi Anda, beri nama klien OAuth Anda, dan tetapkan kolom lainnya dalam formulir sesuai kebutuhan.
Android
  1. Pilih jenis aplikasi Android.
  2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan di project Anda untuk mengidentifikasi klien.
  3. Masukkan nama paket aplikasi Android Anda. Nilai ini ditentukan dalam atribut package dari elemen <manifest> dalam file manifes aplikasi Anda.
  4. Masukkan sidik jari sertifikat penandatanganan SHA-1 distribusi aplikasi.
    • Jika aplikasi Anda menggunakan penandatanganan aplikasi oleh Google Play, salin sidik jari SHA-1 dari halaman penandatanganan aplikasi di Konsol Play.
    • Jika Anda mengelola keystore dan kunci penandatanganan sendiri, gunakan utilitas keytool yang disertakan dengan Java untuk mencetak informasi sertifikat dalam format yang mudah dibaca. Salin nilai SHA1 di bagian Certificate fingerprints dari output keytool. Lihat Mengautentikasi Klien Anda di dokumentasi Google API untuk Android guna mengetahui informasi selengkapnya.
  5. (Opsional) Verifikasi kepemilikan aplikasi Android Anda.
  6. Klik Buat.
iOS
  1. Pilih jenis aplikasi iOS.
  2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan di project Anda untuk mengidentifikasi klien.
  3. Masukkan ID paket untuk aplikasi Anda. ID paket adalah nilai kunci CFBundleIdentifier dalam file resource daftar properti informasi aplikasi Anda (info.plist). Nilai paling sering ditampilkan di panel General atau panel Signing & Capabilities di editor project Xcode. ID paket juga ditampilkan di bagian Informasi Umum di halaman Informasi Aplikasi untuk aplikasi di situs App Store Connect Apple.

    Pastikan Anda menggunakan ID paket yang benar untuk aplikasi Anda, karena Anda tidak akan dapat mengubahnya jika menggunakan fitur App Check.

  4. (Opsional)

    Masukkan ID App Store aplikasi Anda jika aplikasi dipublikasikan di App Store Apple. ID Toko adalah string numerik yang disertakan dalam setiap URL Apple App Store.

    1. Buka aplikasi Apple App Store di perangkat iOS atau iPadOS Anda.
    2. Telusuri aplikasi Anda.
    3. Pilih tombol Bagikan (simbol persegi dan panah ke atas).
    4. Pilih Salin Link.
    5. Tempelkan link ke editor teks. ID App Store adalah bagian terakhir dari URL.

      Contoh: https://apps.apple.com/app/google/id284815942

  5. (Opsional)

    Masukkan ID Tim Anda. Lihat Menemukan ID Tim Anda dalam dokumentasi Akun Developer Apple untuk mengetahui informasi selengkapnya.

    Catatan: Kolom ID Tim diperlukan jika Anda mengaktifkan App Check untuk klien.
  6. (Opsional)

    Aktifkan App Check untuk aplikasi iOS Anda. Saat Anda mengaktifkan App Check, layanan App Attest Apple digunakan untuk memverifikasi bahwa permintaan OAuth 2.0 yang berasal dari klien OAuth Anda adalah asli dan berasal dari aplikasi Anda. Hal ini membantu mengurangi risiko peniruan identitas aplikasi. Pelajari lebih lanjut cara mengaktifkan App Check untuk aplikasi iOS Anda.

  7. Klik Buat.
UWP
  1. Pilih jenis aplikasi Universal Windows Platform.
  2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan di project Anda untuk mengidentifikasi klien.
  3. Masukkan ID Microsoft Store 12 karakter aplikasi Anda. Anda dapat menemukan nilai ini di Microsoft Partner Center di halaman Identitas aplikasi di bagian Pengelolaan aplikasi.
  4. Klik Buat.

Untuk aplikasi UWP, skema URI kustom tidak boleh lebih dari 39 karakter.

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. Oleh karena itu, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan izin pengguna.

Sebelum mulai menerapkan otorisasi OAuth 2.0, sebaiknya Anda mengidentifikasi cakupan yang izin aksesnya akan diperlukan oleh aplikasi Anda.

YouTube Data API v3 menggunakan cakupan berikut:

Cakupan Deskripsi
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.

Mendapatkan token akses OAuth 2.0

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

Langkah 1: Buat verifier dan tantangan kode

Google mendukung protokol Proof Key for Code Exchange (PKCE) untuk membuat alur aplikasi yang diinstal lebih aman. Verifikasi kode unik dibuat untuk setiap permintaan otorisasi, dan nilai yang diubah, yang disebut "code_challenge", dikirim ke server otorisasi untuk mendapatkan kode otorisasi.

Buat verifier kode

code_verifier adalah string acak kriptografi entropi tinggi menggunakan karakter yang tidak dicadangkan [A-Z] / [a-z] / [0-9] / "-" / "." / "_" / "~", dengan panjang minimum 43 karakter dan panjang maksimum 128 karakter.

Verifier kode harus memiliki entropi yang cukup sehingga nilai tersebut tidak mungkin ditebak.

Membuat tantangan kode

Dua metode pembuatan tantangan kode didukung.

Metode Pembuatan Tantangan Kode
S256 (direkomendasikan) Tantangan kode adalah hash SHA256 berenkode Base64URL (tanpa padding) dari verifier kode.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
plain Tantangan kode memiliki nilai yang sama dengan verifier kode yang dihasilkan di atas.
code_challenge = code_verifier

Langkah 2: Kirim permintaan ke server OAuth 2.0 Google

Untuk mendapatkan otorisasi pengguna, kirim permintaan ke server otorisasi Google di https://accounts.google.com/o/oauth2/v2/auth. Endpoint ini menangani pencarian sesi aktif, mengautentikasi pengguna, dan mendapatkan izin pengguna. Endpoint hanya dapat diakses melalui SSL, dan menolak koneksi HTTP (non-SSL).

Server otorisasi mendukung parameter string kueri berikut untuk aplikasi yang diinstal:

Parameter
client_id Wajib

Client ID untuk aplikasi Anda. Anda dapat menemukan nilai ini di .
redirect_uri Wajib

Menentukan cara server otorisasi Google mengirimkan respons ke aplikasi Anda. Ada beberapa opsi pengalihan yang tersedia untuk aplikasi yang diinstal, dan Anda akan menyiapkan kredensial otorisasi dengan metode pengalihan tertentu.

Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0, yang Anda konfigurasi di klien. Jika nilai ini tidak cocok dengan URI yang diizinkan, Anda akan mendapatkan error redirect_uri_mismatch.

Tabel di bawah menunjukkan nilai parameter redirect_uri yang sesuai untuk setiap metode:

Nilai redirect_uri
Skema URI kustom com.example.app:redirect_uri_path

atau

com.googleusercontent.apps.123:redirect_uri_path
  • com.example.app adalah notasi DNS terbalik dari domain di bawah kontrol Anda. Skema kustom harus berisi titik agar valid.
  • com.googleusercontent.apps.123 adalah notasi DNS balik dari client ID.
  • redirect_uri_path adalah komponen jalur opsional, seperti /oauth2redirect. Perhatikan bahwa jalur harus dimulai dengan satu garis miring, yang berbeda dengan URL HTTP biasa.
Alamat IP loopback http://127.0.0.1:port atau http://[::1]:port

Kueri platform Anda untuk alamat IP loopback yang relevan dan mulai pemroses HTTP di port acak yang tersedia. Ganti port dengan nomor port sebenarnya yang diproses aplikasi Anda.

Perhatikan bahwa dukungan untuk opsi pengalihan alamat IP loopback di aplikasi seluler adalah TIDAK DIGUNAKAN LAGI.
response_type Wajib

Menentukan apakah endpoint Google OAuth 2.0 menampilkan kode otorisasi.

Setel nilai parameter ke code untuk aplikasi yang diinstal.
scope Wajib

Daftar cakupan yang dibatasi spasi yang mengidentifikasi resource yang dapat diakses aplikasi Anda atas nama pengguna. Nilai ini memberi tahu layar izin yang ditampilkan Google kepada pengguna.

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke resource yang dibutuhkan 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:

Cakupan Deskripsi
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.
code_challenge Direkomendasikan

Menentukan code_verifier yang dienkode yang akan digunakan sebagai tantangan sisi server selama pertukaran kode otorisasi. Lihat bagian membuat tantangan kode di atas untuk mengetahui informasi selengkapnya.
code_challenge_method Direkomendasikan

Menentukan metode yang digunakan untuk mengenkode code_verifier yang akan digunakan selama pertukaran kode otorisasi. Parameter ini harus digunakan dengan parameter code_challenge yang dijelaskan di atas. Nilai code_challenge_method secara default adalah plain jika tidak ada dalam permintaan yang menyertakan code_challenge. Satu-satunya nilai yang didukung untuk parameter ini adalah S256 atau plain.
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 ID fragmen 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 memitigasi pemalsuan permintaan lintas situs. Karena redirect_uri Anda dapat ditebak, menggunakan nilai state dapat meningkatkan kepastian Anda bahwa koneksi masuk adalah hasil dari permintaan autentikasi. Jika Anda membuat string acak atau mengenkode hash cookie atau nilai lain yang merekam status klien, Anda dapat memvalidasi respons untuk memastikan lebih lanjut bahwa permintaan dan respons berasal dari browser yang sama, sehingga memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs. Lihat dokumentasi OpenID Connect untuk mengetahui contoh cara membuat dan mengonfirmasi token state.
login_hint Opsional

Jika aplikasi Anda mengetahui pengguna mana yang mencoba melakukan autentikasi, aplikasi tersebut 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.

Contoh URL otorisasi

Tab di bawah ini menampilkan contoh URL otorisasi untuk berbagai opsi URI pengalihan.

Setiap URL meminta akses ke cakupan yang mengizinkan akses untuk melihat akun YouTube pengguna.

URL-nya identik kecuali untuk nilai parameter redirect_uri. URL juga berisi parameter response_type dan client_id yang diperlukan serta parameter state opsional. Setiap URL berisi jeda baris dan spasi agar mudah dibaca.

Skema URI kustom

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=com.example.app%3A/oauth2redirect&
 client_id=client_id

Alamat IP loopback

https://accounts.google.com/o/oauth2/v2/auth?
 scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fyoutube.readonly&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=http%3A//127.0.0.1%3A9004&
 client_id=client_id

Langkah 3: Perintah 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 menunjukkan nama aplikasi Anda dan layanan Google API yang meminta izin untuk mengakses dengan kredensial otorisasi pengguna dan ringkasan cakupan akses yang akan diberikan. Pengguna kemudian dapat menyetujui untuk memberikan akses ke satu atau beberapa cakupan yang diminta oleh aplikasi Anda atau menolak permintaan.

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

Error

Permintaan ke endpoint otorisasi OAuth 2.0 Google dapat menampilkan pesan error yang terlihat oleh pengguna, bukan alur autentikasi dan otorisasi yang diharapkan. Kode error umum dan saran penyelesaiannya tercantum di bawah.

admin_policy_enforced

Akun Google tidak dapat mengizinkan 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 terbatas hingga akses diberikan secara eksplisit ke ID klien OAuth Anda.

disallowed_useragent

Endpoint otorisasi ditampilkan di dalam agen pengguna sematan 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 dari OpenID Foundation.

Developer web mungkin mengalami error ini saat aplikasi Android membuka link web umum di agen pengguna yang disematkan 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 Login dengan Google untuk iOS atau AppAuth untuk iOS dari OpenID Foundation.

Developer web mungkin mengalami error ini saat aplikasi iOS atau macOS membuka link web umum di agen pengguna yang disematkan 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 Link atau aplikasi browser default. Library SFSafariViewController juga merupakan opsi yang didukung.
org_internal

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

deleted_client

Klien OAuth yang digunakan untuk membuat permintaan telah dihapus. Penghapusan dapat terjadi secara manual atau otomatis dalam kasus klien yang tidak digunakan . Klien yang dihapus dapat dipulihkan dalam waktu 30 hari setelah penghapusan. Pelajari lebih lanjut .

invalid_grant

Jika Anda menggunakan verifikasi kode dan tantangan, parameter code_callenge tidak valid atau tidak ada. Pastikan parameter code_challenge disetel dengan benar.

Saat memperbarui token akses, token mungkin sudah tidak berlaku atau telah dibatalkan. 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 ID klien OAuth. Tinjau URI pengalihan yang sah di .

redirect_uri yang diteruskan mungkin tidak valid untuk jenis klien.

Parameter redirect_uri dapat merujuk ke alur OAuth di luar band (OOB) yang sudah tidak digunakan lagi dan tidak didukung lagi. Lihat panduan migrasi untuk memperbarui integrasi Anda.

invalid_request

Terjadi kesalahan pada permintaan yang Anda buat. Hal ini dapat disebabkan oleh beberapa alasan:

  • Permintaan tidak diformat dengan benar
  • Permintaan tidak memiliki parameter yang diperlukan
  • Permintaan menggunakan metode otorisasi yang tidak didukung Google. Memverifikasi bahwa integrasi OAuth Anda menggunakan metode integrasi yang direkomendasikan
  • Skema kustom digunakan untuk URI pengalihan : Jika Anda melihat pesan error Skema URI kustom tidak didukung di aplikasi Chrome atau Skema URI kustom tidak diaktifkan untuk klien Android Anda, artinya Anda menggunakan skema URI kustom yang tidak didukung di aplikasi Chrome dan dinonaktifkan secara default di Android. Pelajari lebih lanjut alternatif skema URI kustom

Langkah 4: Tangani respons server OAuth 2.0

Cara aplikasi Anda menerima respons otorisasi bergantung pada skema URI pengalihan yang digunakannya. Terlepas dari skemanya, respons akan berisi kode otorisasi (code) atau error (error). Misalnya, error=access_denied menunjukkan bahwa pengguna menolak permintaan.

Jika pengguna memberikan akses ke aplikasi Anda, Anda dapat menukarkan kode otorisasi dengan token akses dan token refresh seperti yang dijelaskan pada langkah berikutnya.

Langkah 5: Tukarkan kode otorisasi untuk mendapatkan token akses dan token refresh

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

Kolom
client_id ID klien yang diperoleh dari .
client_secret Rahasia klien yang diperoleh dari .
code Kode otorisasi yang ditampilkan dari permintaan awal.
code_verifier Verifikasi kode yang Anda buat di Langkah 1.
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=http://127.0.0.1:9004&
grant_type=authorization_code

Google merespons permintaan ini dengan menampilkan objek JSON yang berisi token akses dan token refresh yang masa berlakunya singkat.

Respons berisi kolom berikut:

Kolom
access_token Token yang dikirimkan aplikasi Anda untuk mengotorisasi permintaan Google API.
expires_in Masa aktif token akses yang tersisa dalam detik.
id_token Catatan: Properti ini hanya ditampilkan jika permintaan Anda menyertakan cakupan identitas, seperti openid, profile, atau email. Nilainya adalah Token Web JSON (JWT) yang berisi informasi identitas yang ditandatangani secara digital tentang pengguna.
refresh_token Token yang dapat Anda gunakan untuk mendapatkan token akses baru. Token refresh valid hingga pengguna mencabut akses atau token refresh berakhir masa berlakunya. Perhatikan bahwa token refresh selalu ditampilkan untuk aplikasi yang diinstal.
refresh_token_expires_in Masa aktif token refresh yang tersisa dalam hitungan detik. Nilai ini hanya ditetapkan saat pengguna memberikan akses berbasis waktu.
scope Cakupan akses yang diberikan oleh access_token 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.

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"
}

Langkah 6: Periksa cakupan yang diberikan pengguna

Saat meminta beberapa izin (cakupan), pengguna mungkin tidak memberikan akses aplikasi Anda ke semua izin tersebut. Aplikasi Anda harus memverifikasi cakupan mana yang benar-benar diberikan dan menangani situasi dengan baik saat beberapa izin ditolak, biasanya dengan menonaktifkan fitur yang mengandalkan cakupan yang ditolak tersebut.

Namun, ada pengecualian. Aplikasi Google Workspace Enterprise dengan delegasi otoritas di seluruh domain, atau aplikasi yang ditandai sebagai Tepercaya, melewati layar izin izin terperinci. Untuk aplikasi ini, pengguna tidak akan melihat layar izin izin terperinci. Sebagai gantinya, aplikasi Anda akan menerima semua cakupan yang diminta atau tidak sama sekali.

Untuk informasi yang lebih mendetail, lihat Cara menangani izin terperinci.

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

Misalnya, respons token akses contoh berikut menunjukkan bahwa pengguna telah memberikan izin kepada 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

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 header HTTP Authorization Bearer. Jika memungkinkan, header HTTP lebih disarankan, karena string kueri cenderung terlihat dalam 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 youtube.channels endpoint (YouTube Data API) menggunakan header HTTP Authorization: Bearer mungkin terlihat seperti berikut. Perhatikan bahwa Anda harus 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 disarankan):

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

Memperbarui token akses

Token akses akan habis masa berlakunya secara berkala dan menjadi kredensial yang tidak valid untuk permintaan API terkait. Anda dapat memperbarui token akses tanpa meminta izin pengguna (termasuk saat pengguna tidak ada) jika Anda meminta akses offline ke cakupan yang terkait dengan token.

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

Kolom
client_id Client ID yang diperoleh dari API Console.
client_secret Rahasia klien yang diperoleh dari API Console. (client_secret tidak berlaku untuk permintaan dari klien yang terdaftar sebagai aplikasi Android, iOS, atau Chrome.)
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 dikeluarkan; satu batasan per kombinasi klien/pengguna, dan batasan lainnya per pengguna di semua klien. Anda harus menyimpan token refresh di penyimpanan jangka panjang dan terus menggunakannya selama token tersebut tetap valid. Jika aplikasi Anda meminta terlalu banyak token refresh, aplikasi tersebut mungkin mencapai batas ini, sehingga token refresh yang lebih 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 memiliki akses ke akun Anda untuk mengetahui informasi selengkapnya.

Aplikasi juga dapat mencabut akses yang diberikan kepadanya secara terprogram. Pencabutan akses secara 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.

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 respons adalah 200. Untuk kondisi error, kode status HTTP 400 ditampilkan bersama dengan kode error.

Metode pengalihan aplikasi

Skema URI kustom (Android, iOS, UWP)

Skema URI kustom adalah bentuk deep linking yang menggunakan skema yang ditentukan kustom untuk membuka aplikasi Anda.

Alternatif untuk menggunakan skema URI kustom di Android

Gunakan alternatif yang direkomendasikan yang mengirimkan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga tidak memerlukan URI pengalihan.

Cara bermigrasi ke Google Identity Services Android Library

Jika Anda menggunakan skema kustom untuk integrasi OAuth di Android, Anda harus menyelesaikan tindakan berikut untuk sepenuhnya bermigrasi ke penggunaan Library Android Layanan Identitas Google yang direkomendasikan:

  1. Perbarui kode Anda untuk menggunakan Google Identity Services Android Library.
  2. Nonaktifkan dukungan untuk skema kustom di Konsol Google Cloud.

Langkah-langkah berikut menjelaskan cara bermigrasi ke Google Identity Services Android Library:

  1. Perbarui kode Anda untuk menggunakan Google Identity Services Android Library:
    1. Periksa kode Anda untuk mengidentifikasi tempat Anda mengirim permintaan ke server OAuth 2.0 Google; jika menggunakan skema kustom, permintaan Anda akan terlihat seperti di bawah: 
        https://accounts.google.com/o/oauth2/v2/auth?
  scope=<SCOPES>&
  response_type=code&
  &state=<STATE>&
  redirect_uri=com.example.app:/oauth2redirect&
  client_id=<CLIENT_ID>
      com.example.app:/oauth2redirect adalah URI pengalihan skema kustom dalam contoh di atas. Lihat definisi parameter redirect_uri untuk mengetahui detail selengkapnya tentang format nilai skema URI kustom.
    2. Catat parameter permintaan scope dan client_id yang perlu Anda konfigurasi untuk Google Sign-In SDK.
    3. Ikuti petunjuk Mengizinkan akses ke data pengguna Google untuk menyiapkan SDK. Anda dapat melewati langkah Siapkan project Konsol Google Cloud Anda karena Anda akan menggunakan kembali client_id yang Anda ambil dari langkah sebelumnya.
    4. Ikuti petunjuk Meminta izin yang diperlukan oleh tindakan pengguna. Hal ini mencakup langkah-langkah berikut:
      1. Meminta izin dari pengguna.
      2. Gunakan metode getServerAuthCode untuk mengambil kode otorisasi bagi cakupan yang Anda minta izinnya.
      3. Kirim kode autentikasi ke backend aplikasi Anda untuk ditukar dengan token akses & refresh.
      4. Gunakan token akses yang diambil untuk melakukan panggilan ke Google API atas nama pengguna.
  2. Nonaktifkan dukungan untuk skema kustom di Konsol Google API:
    1. Buka daftar kredensial OAuth 2.0 Anda, lalu pilih klien Android Anda.
    2. Buka bagian Setelan Lanjutan, hapus centang pada kotak Aktifkan Skema URI Kustom, lalu klik Simpan untuk menonaktifkan dukungan skema URI kustom.

Mengaktifkan skema URI kustom

Jika alternatif yang direkomendasikan tidak berfungsi untuk Anda, Anda dapat mengaktifkan skema URI kustom untuk klien Android dengan mengikuti petunjuk di bawah:
  1. Buka daftar kredensial OAuth 2.0 dan pilih klien Android Anda.
  2. Buka bagian Setelan Lanjutan, centang kotak Aktifkan Skema URI Kustom, lalu klik Simpan untuk mengaktifkan dukungan skema URI kustom.

Alternatif untuk menggunakan skema URI kustom di aplikasi Chrome

Gunakan Chrome Identity API yang mengirimkan respons OAuth 2.0 langsung ke aplikasi Anda, sehingga tidak memerlukan URI pengalihan.

Alamat IP loopback (desktop macOS, Linux, Windows)

Untuk menerima kode otorisasi menggunakan URL ini, aplikasi Anda harus memproses server web lokal. Hal ini dapat dilakukan di banyak platform, tetapi tidak semua. Namun, jika platform Anda mendukungnya, mekanisme ini adalah mekanisme yang direkomendasikan untuk mendapatkan kode otorisasi.

Saat aplikasi Anda menerima respons otorisasi, untuk kegunaan terbaik, aplikasi harus merespons dengan menampilkan halaman HTML yang menginstruksikan pengguna untuk menutup browser dan kembali ke aplikasi Anda.

Penggunaan yang direkomendasikan Aplikasi desktop macOS, Linux, dan Windows (tetapi bukan Universal Windows Platform)
Nilai formulir Tetapkan jenis aplikasi ke Aplikasi desktop.

Salin/tempel manual (Tidak digunakan lagi)

Melindungi aplikasi Anda

Memverifikasi kepemilikan aplikasi (Android, Chrome)

Anda dapat memverifikasi kepemilikan aplikasi untuk mengurangi risiko peniruan identitas aplikasi.

Android

Untuk menyelesaikan proses verifikasi, Anda dapat menggunakan Akun Developer Google Play jika Anda memilikinya dan aplikasi Anda terdaftar di Konsol Google Play. Persyaratan berikut harus dipenuhi agar verifikasi berhasil:

  • Anda harus memiliki aplikasi terdaftar di Konsol Google Play dengan nama paket dan sidik jari sertifikat penandatanganan SHA-1 yang sama dengan klien OAuth Android yang Anda selesaikan verifikasinya.
  • Anda harus memiliki izin Admin untuk aplikasi di Konsol Google Play. Pelajari lebih lanjut pengelolaan akses di Konsol Google Play.

Di bagian Verify App Ownership pada klien Android, klik tombol Verify Ownership untuk menyelesaikan proses verifikasi.

Jika verifikasi berhasil, notifikasi akan ditampilkan untuk mengonfirmasi keberhasilan proses verifikasi. Jika tidak, pesan error akan ditampilkan.

Untuk memperbaiki kegagalan verifikasi, coba langkah-langkah berikut:

  • Pastikan aplikasi yang Anda verifikasi adalah aplikasi terdaftar di Konsol Google Play.
  • Pastikan Anda memiliki izin Admin untuk aplikasi di Konsol Google Play.
Chrome

Untuk menyelesaikan proses verifikasi, Anda akan menggunakan akun Developer Chrome Web Store Anda. Persyaratan berikut harus dipenuhi agar verifikasi berhasil:

  • Anda harus memiliki item terdaftar di Dasbor Developer Chrome Web Store dengan ID item yang sama dengan klien OAuth Ekstensi Chrome yang Anda selesaikan verifikasinya.
  • Anda harus menjadi penerbit untuk item Chrome Web Store. Pelajari lebih lanjut pengelolaan akses di Dasbor Developer Chrome Web Store.

Di bagian Verifikasi Kepemilikan Aplikasi pada klien Ekstensi Chrome, klik tombol Verifikasi Kepemilikan untuk menyelesaikan proses verifikasi.

Catatan: Tunggu beberapa menit sebelum menyelesaikan proses verifikasi setelah memberikan akses ke akun Anda.

Jika verifikasi berhasil, notifikasi akan ditampilkan untuk mengonfirmasi keberhasilan proses verifikasi. Jika tidak, pesan error akan ditampilkan.

Untuk memperbaiki kegagalan verifikasi, coba langkah-langkah berikut:

  • Pastikan ada item terdaftar di Dasbor Developer Chrome Web Store dengan ID item yang sama dengan klien OAuth Ekstensi Chrome yang Anda selesaikan verifikasinya.
  • Pastikan Anda adalah penayang aplikasi, yaitu Anda harus menjadi penayang perorangan aplikasi atau anggota penayang grup aplikasi. Pelajari lebih lanjut pengelolaan akses di Dasbor Developer Chrome Web Store.
  • Jika Anda baru saja memperbarui daftar penayang grup, pastikan daftar keanggotaan penayang grup disinkronkan di Dasbor Developer Chrome Web Store. Pelajari lebih lanjut cara menyinkronkan daftar keanggotaan penayang Anda.

App Check (khusus iOS)

Fitur App Check membantu mengamankan aplikasi iOS Anda dari penggunaan yang tidak sah dengan menggunakan layanan App Attest Apple untuk memverifikasi bahwa permintaan yang dibuat ke endpoint Google OAuth 2.0 berasal dari aplikasi asli Anda. Hal ini membantu mengurangi risiko peniruan identitas aplikasi.

Mengaktifkan App Check untuk Klien iOS Anda

Persyaratan berikut harus dipenuhi agar App Check berhasil diaktifkan untuk klien iOS Anda:
  • Anda harus menentukan ID tim untuk klien iOS.
  • Anda tidak boleh menggunakan karakter pengganti dalam ID paket karena dapat diselesaikan ke lebih dari satu aplikasi. Artinya, ID paket tidak boleh menyertakan simbol asteris (*).
Untuk mengaktifkan App Check, aktifkan tombol pilihan Lindungi klien OAuth Anda dari penyalahgunaan dengan Firebase App Check di tampilan edit klien iOS Anda.

Setelah mengaktifkan App Check, Anda akan mulai melihat metrik terkait permintaan OAuth dari klien di tampilan edit klien OAuth. Permintaan dari sumber yang tidak terverifikasi tidak akan diblokir hingga Anda menerapkan App Check. Informasi di halaman pemantauan metrik dapat membantu Anda menentukan kapan harus memulai penegakan.

Anda mungkin melihat error terkait fitur App Check saat mengaktifkan App Check untuk aplikasi iOS Anda. Untuk memperbaiki error ini, coba langkah-langkah berikut:

  • Pastikan ID paket dan ID tim yang Anda tentukan valid.
  • Pastikan Anda tidak menggunakan karakter pengganti untuk ID paket.

Menerapkan App Check untuk Klien iOS Anda

Mengaktifkan App Check untuk aplikasi Anda tidak secara otomatis memblokir permintaan yang tidak dikenal. Untuk menerapkan perlindungan ini, buka tampilan edit klien iOS Anda. Di sana, Anda akan melihat metrik App Check di sebelah kanan halaman di bagian Google Identity for iOS. Metrik ini mencakup informasi berikut:
  • Jumlah permintaan terverifikasi - permintaan yang memiliki token App Check yang valid. Setelah Anda mengaktifkan penerapan App Check, hanya permintaan dalam kategori ini yang akan berhasil.
  • Jumlah permintaan yang tidak diverifikasi: kemungkinan permintaan klien sudah lama - permintaan yang tidak memiliki token App Check; permintaan ini mungkin berasal dari versi lama aplikasi Anda yang tidak menyertakan implementasi App Check.
  • Jumlah permintaan yang tidak diverifikasi: permintaan dengan asal yang tidak diketahui - permintaan yang tidak memiliki token App Check dan sepertinya tidak berasal dari aplikasi Anda.
  • Jumlah permintaan yang tidak diverifikasi: permintaan tidak valid - permintaan dengan token App Check yang tidak valid, yang mungkin berasal dari klien palsu yang mencoba meniru aplikasi Anda, atau dari lingkungan yang diemulasikan.
Tinjau metrik ini untuk memahami pengaruh penerapan App Check terhadap pengguna Anda.

Untuk menerapkan App Check, klik tombol TERAPKAN dan konfirmasi pilihan Anda. Setelah penerapan aktif, semua permintaan yang belum diverifikasi dari klien Anda akan ditolak.

Catatan: setelah Anda mengaktifkan penegakan, perlu waktu hingga 15 menit agar perubahan diterapkan.

Membatalkan penerapan App Check untuk Klien iOS Anda

Pembatalan penerapan App Check untuk aplikasi Anda akan menghentikan penerapan dan akan mengizinkan semua permintaan dari klien Anda ke endpoint Google OAuth 2.0, termasuk permintaan yang belum diverifikasi.

Untuk membatalkan penerapan App Check untuk klien iOS Anda, buka tampilan edit klien iOS, lalu klik tombol BATALKAN PENERAPAN dan konfirmasi pilihan Anda.

Catatan: setelah tidak menerapkan App Check, perlu waktu hingga 15 menit agar perubahan diterapkan.

Menonaktifkan App Check untuk Klien iOS Anda

Menonaktifkan App Check untuk aplikasi Anda akan menghentikan semua pemantauan dan penerapan App Check. Pertimbangkan untuk tidak menerapkan App Check agar Anda dapat terus memantau metrik untuk klien Anda.

Untuk menonaktifkan App Check bagi klien iOS Anda, buka tampilan edit klien iOS dan nonaktifkan tombol Lindungi klien OAuth Anda dari penyalahgunaan dengan Firebase App Check.

Catatan: setelah menonaktifkan App Check, perlu waktu hingga 15 menit agar perubahan diterapkan.

Akses berbasis waktu

Akses berbasis waktu memungkinkan pengguna memberikan akses aplikasi Anda ke datanya selama durasi terbatas untuk menyelesaikan tindakan. Akses berbasis waktu tersedia di produk Google tertentu selama alur izin, sehingga pengguna dapat memberikan akses untuk jangka waktu terbatas. Contohnya adalah Data Portability API yang memungkinkan transfer data satu kali.

Saat pengguna memberikan akses berbasis waktu ke aplikasi Anda, masa berlaku token refresh akan berakhir setelah durasi yang ditentukan. Perhatikan bahwa token refresh dapat dibatalkan lebih awal dalam keadaan tertentu; lihat kasus ini untuk mengetahui detailnya. Kolom refresh_token_expires_in yang ditampilkan dalam respons penukaran kode otorisasi menunjukkan waktu yang tersisa hingga token refresh habis masa berlakunya dalam kasus tersebut.

Bacaan Lebih Lanjut

Praktik Terbaik IETF saat ini OAuth 2.0 untuk Aplikasi Native menetapkan banyak praktik terbaik yang didokumentasikan di sini.

Menerapkan Perlindungan Lintas Akun

Langkah tambahan yang harus Anda lakukan untuk melindungi akun pengguna Anda adalah menerapkan Perlindungan Lintas Akun dengan menggunakan Layanan Perlindungan Lintas Akun Google. Layanan ini memungkinkan Anda berlangganan notifikasi peristiwa keamanan yang memberikan informasi kepada aplikasi Anda tentang perubahan besar pada akun pengguna. Kemudian, Anda 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 daftar lengkap peristiwa yang tersedia.