OAuth 2.0 untuk Aplikasi Seluler & Desktop

Dokumen ini menjelaskan bagaimana aplikasi yang diinstal pada perangkat seperti ponsel, tablet, dan komputer menggunakan endpoint OAuth 2.0 Google untuk mengotorisasi akses ke Google API.

OAuth 2.0 memungkinkan pengguna untuk berbagi data tertentu dengan aplikasi sambil menjaga nama pengguna, kata sandi, dan informasi lainnya tetap pribadi. Misalnya, aplikasi dapat menggunakan OAuth 2.0 untuk mendapatkan izin dari pengguna untuk menyimpan file di Google Drive mereka.

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

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

Alternatif

Untuk aplikasi mobile, Anda dapat memilih untuk menggunakan Google Sign-in untuk Android atau iOS . Pustaka klien Masuk dengan Google menangani autentikasi dan otorisasi pengguna, dan mungkin lebih mudah diterapkan daripada protokol tingkat rendah yang dijelaskan di sini.

Untuk aplikasi yang berjalan pada perangkat yang tidak mendukung sistem peramban atau yang telah membatasi kemampuan input, seperti TV, konsol game, kamera, atau printer, lihat OAuth 2.0 untuk TV & Devices atau Google Sign-in untuk perangkat .

Perpustakaan dan sampel

Kami merekomendasikan pustaka dan sampel berikut untuk membantu Anda menerapkan alur OAuth 2.0 yang dijelaskan dalam dokumen ini:

Prasyarat

Aktifkan API untuk proyek Anda

Setiap aplikasi yang memanggil Google API perlu mengaktifkan mereka API di API Console.

Untuk mengaktifkan API untuk proyek Anda:

  1. Open the API Library di Google API Console.
  2. If prompted, select a project, or create a new one.
  3. The API Library daftar semua API yang tersedia, dikelompokkan berdasarkan produk keluarga dan popularitas. Jika API Anda ingin mengaktifkan tidak terlihat dalam daftar, penggunaan pencarian untuk menemukannya, atau klik Lihat Semua dalam keluarga produk itu milik.
  4. Pilih API Anda ingin mengaktifkan, kemudian klik tombol Enable.
  5. If prompted, enable billing.
  6. If prompted, read and accept the API's Terms of Service.

Buat kredensial otorisasi

Aplikasi apa pun 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 proyek Anda. Aplikasi Anda kemudian dapat menggunakan kredensial untuk mengakses API yang telah Anda aktifkan untuk proyek tersebut.

  1. Go to the Credentials page.
  2. Klik Buat kredensial> OAuth ID klien.
  3. Bagian di bawah menjelaskan jenis klien dan metode pengalihan yang didukung oleh server otorisasi Google. Pilih jenis klien yang direkomendasikan untuk aplikasi Anda, beri nama klien OAuth Anda, dan atur bidang lain dalam formulir yang sesuai.

Skema URI khusus (Android, iOS, UWP)

Skema URI khusus direkomendasikan untuk aplikasi Android, aplikasi iOS, dan aplikasi Universal Windows Platform (UWP).

Android
  1. Pilih jenis aplikasi Android.
  2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan pada proyek Anda Credentials page untuk mengidentifikasi klien.
  3. Masukkan nama paket aplikasi Android Anda. Nilai ini didefinisikan dalampackage atribut dari <manifest> elemen dalam file manifest aplikasi Anda.
  4. Masukkan sidik jari sertifikat penandatanganan SHA-1 dari distribusi aplikasi.
    • Jika menggunakan aplikasi App penandatanganan oleh Google Play , menyalin SHA-1 sidik jari dari halaman penandatanganan aplikasi dari Play Console.
    • Jika Anda mengelola keystore dan penandatanganan kunci Anda sendiri, menggunakan utilitas keytool disertakan dengan Java untuk mencetak informasi sertifikat dalam format yang dapat dibaca manusia. Salin SHA1 nilai dalam Certificate fingerprints bagian dari output keytool. Lihat Otentikasi Klien Anda di Google API untuk dokumentasi Android untuk informasi lebih lanjut.
  5. Klik Buat.
iOS
  1. Pilih iOS jenis aplikasi.
  2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan pada proyek Anda Credentials page untuk mengidentifikasi klien.
  3. Masukkan pengenal paket untuk aplikasi Anda. Bundel ID adalah nilai dari CFBundleIdentifier kunci dalam file daftar sumber daya properti informasi aplikasi (info.plist). Nilai paling sering ditampilkan di panel Umum atau panel Penandatanganan & Kemampuan dari editor proyek Xcode. Bundel ID juga ditampilkan di bagian Informasi Umum halaman App Informasi untuk aplikasi di Apple App Store situs Connect .
  4. (Opsional)

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

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

      Contoh: https://apps.apple.com/app/google/id 284815942

  5. (Opsional)

    Masukkan ID Tim Anda. Lihat Cari Tim ID Anda di Apple Developer dokumentasi Akun untuk informasi lebih lanjut.

  6. Klik Buat.
UWP
  1. Pilih Universal Platform Windows jenis aplikasi.
  2. Masukkan nama untuk klien OAuth. Nama ini ditampilkan pada proyek Anda Credentials page untuk mengidentifikasi klien.
  3. Masukkan 12 karakter Microsoft Store ID aplikasi Anda. Anda dapat menemukan nilai ini di Microsoft Pusat Mitra di identitas App halaman di bagian manajemen App.
  4. Klik Buat.

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

Alamat IP loopback (macOS, Linux, desktop Windows)

Untuk menerima kode otorisasi menggunakan URL ini, aplikasi Anda harus mendengarkan di server web lokal. Itu mungkin di banyak, tetapi tidak semua, platform. Namun, jika platform Anda mendukungnya, ini adalah mekanisme yang disarankan untuk mendapatkan kode otorisasi.

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

Penggunaan yang disarankan aplikasi desktop macOS, Linux, dan Windows (tetapi bukan Universal Windows Platform)
Nilai bentuk Mengatur jenis aplikasi untuk Desktop app.

Salin/tempel manual

Identifikasi cakupan akses

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke sumber daya yang dibutuhkannya sekaligus memungkinkan pengguna untuk mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Dengan demikian, mungkin ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan mendapatkan persetujuan pengguna.

Sebelum Anda mulai menerapkan otorisasi OAuth 2.0, sebaiknya Anda mengidentifikasi cakupan yang memerlukan izin untuk diakses oleh aplikasi Anda.

The OAuth 2.0 Cakupan API dokumen berisi daftar lengkap lingkup yang mungkin Anda gunakan untuk mengakses Google API.

Mendapatkan token akses OAuth 2.0

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

Langkah 1: Buat pemverifikasi kode dan tantangan

Google mendukung Key Bukti untuk Kode Efek (PKCE) protokol untuk membuat aliran aplikasi diinstal lebih aman. Pemverifikasi kode unik dibuat untuk setiap permintaan otorisasi, dan nilainya yang diubah, yang disebut "code_challenge", dikirim ke server otorisasi untuk mendapatkan kode otorisasi.

Buat pemverifikasi kode

Sebuah code_verifier adalah string acak kriptografi tinggi entropi menggunakan karakter unreserved [AZ] / [az] / [0-9] / "-" "" / / "_" / "~", dengan panjang minimal 43 karakter dan maksimal 128 karakter.

Pemverifikasi kode harus memiliki entropi yang cukup sehingga tidak praktis untuk menebak nilainya.

Buat tantangan kode

Dua metode untuk membuat tantangan kode didukung.

Metode Pembuatan Tantangan Kode
S256 (disarankan) Tantangan kode adalah hash SHA256 yang disandikan Base64URL (tanpa padding) dari pemverifikasi kode.
code_challenge = BASE64URL-ENCODE(SHA256(ASCII(code_verifier)))
polos Tantangan kode memiliki nilai yang sama dengan pemverifikasi kode yang dibuat di atas.
code_challenge = code_verifier

Langkah 2: Kirim permintaan ke server OAuth 2.0 Google

Untuk mendapatkan otorisasi pengguna, mengirim permintaan ke server otorisasi Google di https://accounts.google.com/o/oauth2/v2/auth . Titik akhir ini menangani pencarian sesi aktif, mengautentikasi pengguna, dan mendapatkan persetujuan pengguna. Titik akhir 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 Yg dibutuhkan

ID klien untuk aplikasi Anda. Anda dapat menemukan nilai ini di API ConsoleCredentials page.

redirect_uri Yg dibutuhkan

Menentukan bagaimana server otorisasi Google mengirimkan respons ke aplikasi Anda. Ada beberapa pilihan redirect tersedia untuk aplikasi yang diinstal, dan Anda akan telah menyiapkan Anda kredensial otorisasi dengan metode redirect tertentu dalam pikiran.

Nilai harus sama persis dengan salah satu URI redirect redirect berwenang untuk OAuth 2.0 klien, yang Anda dikonfigurasi dalam klien Anda API ConsoleCredentials page. Jika nilai ini tidak cocok dengan URI resmi, Anda akan mendapatkan redirect_uri_mismatch error.

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

redirect_uri nilai-nilai
Skema URI khusus com.example.app : redirect_uri_path

atau

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

Minta platform Anda untuk alamat IP loopback yang relevan dan mulai pendengar HTTP pada port yang tersedia secara acak. Pengganti port dengan nomor port yang sebenarnya aplikasi Anda mendengarkan pada.

Salin/tempel manual urn:ietf:wg:oauth:2.0:oob
Ekstraksi terprogram urn:ietf:wg:oauth:2.0:oob:auto
response_type Yg dibutuhkan

Menentukan apakah titik akhir Google OAuth 2.0 mengembalikan kode otorisasi.

Mengatur nilai parameter untuk code untuk aplikasi yang terinstal.

scope Yg dibutuhkan

Daftar cakupan yang dibatasi spasi yang mengidentifikasi sumber daya yang dapat diakses aplikasi Anda atas nama pengguna. Nilai-nilai ini menginformasikan layar persetujuan yang ditampilkan Google kepada pengguna.

Cakupan memungkinkan aplikasi Anda hanya meminta akses ke sumber daya yang dibutuhkannya sekaligus memungkinkan pengguna untuk mengontrol jumlah akses yang mereka berikan ke aplikasi Anda. Dengan demikian, ada hubungan terbalik antara jumlah cakupan yang diminta dan kemungkinan memperoleh persetujuan pengguna.

code_challenge Direkomendasikan

Menentukan sebuah dikodekan code_verifier yang akan digunakan sebagai tantangan server-side saat pertukaran kode otorisasi. Parameter ini harus digunakan dengan code_challenge parameter yang dijelaskan di atas. Lihat membuat kode tantangan bagian atas untuk informasi lebih lanjut.

code_challenge_method Direkomendasikan

Menentukan metode apa yang digunakan untuk mengkodekan code_verifier yang akan digunakan selama pertukaran kode otorisasi. Parameter ini harus digunakan dengan code_challenge parameter. Nilai code_challenge_method default untuk plain jika tidak hadir dalam permintaan yang mencakup code_challenge . Nilai-nilai hanya 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 Anda dan respons server otorisasi. Server mengembalikan nilai yang tepat yang Anda kirim sebagai name=value pasangan di identifier URL fragmen ( # ) dari redirect_uri setelah persetujuan pengguna atau menolak permintaan akses aplikasi Anda.

Anda dapat menggunakan parameter ini untuk beberapa tujuan, seperti mengarahkan pengguna ke sumber daya yang benar di aplikasi Anda, mengirim nonces, dan mengurangi pemalsuan permintaan lintas situs. Karena Anda redirect_uri bisa ditebak, menggunakan state nilai dapat meningkatkan jaminan Anda bahwa koneksi masuk adalah hasil dari permintaan otentikasi. Jika Anda membuat string acak atau menyandikan hash cookie atau nilai lain yang menangkap status klien, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama, memberikan perlindungan terhadap serangan seperti lintas situs meminta pemalsuan. Lihat OpenID Connect dokumentasi untuk contoh bagaimana untuk membuat dan mengkonfirmasi state tanda.

login_hint Opsional

Jika aplikasi Anda mengetahui pengguna mana yang mencoba mengautentikasi, aplikasi dapat menggunakan parameter ini untuk memberikan petunjuk ke Server Google Authentication. Server menggunakan petunjuk untuk menyederhanakan alur login dengan mengisi kolom email di formulir login atau dengan memilih sesi multi-login yang sesuai.

Mengatur nilai parameter ke alamat email atau sub identifier, yang setara dengan Google ID pengguna.

Contoh URL otorisasi

Tab di bawah ini menunjukkan contoh URL otorisasi untuk opsi URI pengalihan yang berbeda.

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

Skema URI khusus

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 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=email%20profile&
 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

Salin/Tempel

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob&
 client_id=client_id

Ekstraksi terprogram

https://accounts.google.com/o/oauth2/v2/auth?
 scope=email%20profile&
 response_type=code&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2.example.com%2Ftoken&
 redirect_uri=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
 client_id=client_id

Langkah 3: Google meminta persetujuan pengguna

Pada langkah ini, pengguna memutuskan apakah akan memberikan aplikasi Anda akses yang diminta. Pada tahap ini, Google menampilkan jendela persetujuan yang menunjukkan 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 menyetujui untuk memberikan 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 ada akses yang diberikan. Respon tersebut dijelaskan pada langkah berikut.

kesalahan

Permintaan ke titik akhir otorisasi OAuth 2.0 Google dapat menampilkan pesan kesalahan yang dihadapi pengguna, bukan alur autentikasi dan otorisasi yang diharapkan. Kode kesalahan umum dan resolusi yang disarankan tercantum di bawah ini.

admin_policy_enforced

Akun Google tidak dapat mengotorisasi satu atau beberapa cakupan yang diminta karena kebijakan administrator Google Workspace mereka. Lihat Google Workspace Admin artikel bantuan Control yang pihak ketiga & aplikasi internal mengakses data Google Workspace untuk informasi lebih lanjut tentang bagaimana administrator dapat membatasi akses ke semua lingkup atau cakupan sensitif dan dibatasi sampai akses secara eksplisit diberikan kepada ID OAuth klien Anda.

disallowed_useragent

Otorisasi endpoint ditampilkan dalam sebuah tertanam user-agent dianulir oleh Google OAuth 2.0 Kebijakan .

Android

Pengembang Android mungkin menemukan pesan kesalahan ini saat membuka permintaan otorisasi diandroid.webkit.WebView . Pengembang malah harus menggunakan perpustakaan Android seperti Google Sign-In untuk Android atau OpenID Foundation AppAuth untuk Android .

Pengembang web mungkin mengalami kesalahan ini saat aplikasi Android membuka tautan web umum di agen pengguna yang disematkan dan pengguna menavigasi ke titik akhir otorisasi OAuth 2.0 Google dari situs Anda. Pengembang harus memungkinkan link umum untuk membuka di link standar handler dari sistem operasi, yang meliputi Android App Links penangan atau aplikasi browser default. The Android Kustom Tab perpustakaan juga merupakan pilihan yang didukung.

iOS

iOS dan MacOS pengembang mungkin mengalami kesalahan ini saat membuka permintaan otorisasi diWKWebView . Pengembang malah harus menggunakan iOS perpustakaan seperti Google Sign-In untuk iOS atau OpenID Foundation AppAuth untuk iOS .

Pengembang web mungkin mengalami kesalahan ini saat aplikasi iOS atau macOS membuka tautan web umum di agen pengguna yang disematkan dan pengguna menavigasi ke titik akhir otorisasi OAuth 2.0 Google dari situs Anda. Pengembang harus memungkinkan link umum untuk membuka di link standar handler dari sistem operasi, yang meliputi Universal Link penangan atau aplikasi browser default. TheSFSafariViewController perpustakaan juga merupakan pilihan yang didukung.

org_internal

ID klien OAuth dalam permintaan adalah bagian dari proyek membatasi akses ke Google Account di tertentu Cloud Organisasi Google . Untuk informasi lebih lanjut tentang opsi konfigurasi ini melihat jenis Pengguna bagian dalam Menyiapkan persetujuan OAuth layar bantuan artikel Anda.

redirect_uri_mismatch

The redirect_uri lulus dalam permintaan otorisasi tidak cocok dengan redirect berwenang URI untuk ID klien OAuth. Ulasan berwenang URI redirect di Google API Console Credentials page.

Berlalu redirect_uri mungkin tidak valid untuk jenis klien.

Langkah 4: Tangani respons server OAuth 2.0

Cara di mana aplikasi Anda menerima respon otorisasi tergantung pada redirect skema URI yang menggunakan. Terlepas dari skema, respon baik akan berisi kode otorisasi ( code ) atau kesalahan ( error ). Misalnya, error=access_denied menunjukkan bahwa pengguna menolak permintaan tersebut.

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

Langkah 5: Tukarkan kode otorisasi untuk penyegaran dan akses token

Untuk bertukar kode otorisasi untuk akses token, hubungi https://oauth2.googleapis.com/token endpoint dan mengatur parameter berikut:

bidang
client_id ID klien yang diperoleh dari API ConsoleCredentials page.
client_secret Klien rahasia yang diperoleh dari API ConsoleCredentials page.
code Kode otorisasi dikembalikan dari permintaan awal.
code_verifier Kode verifier Anda buat di Langkah 1 .
grant_type Sebagaimana didefinisikan dalam OAuth 2.0 spesifikasi , nilai bidang ini harus diatur ke authorization_code .
redirect_uri Salah satu URI redirect terdaftar untuk proyek Anda dalam API ConsoleCredentials page untuk diberikan client_id .

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=urn%3Aietf%3Awg%3Aoauth%3A2.0%3Aoob%3Aauto&
grant_type=authorization_code

Google menanggapi permintaan ini dengan mengembalikan objek JSON yang berisi token akses berumur pendek dan token penyegaran.

Respons berisi bidang berikut:

bidang
access_token Token yang dikirim aplikasi Anda untuk mengotorisasi permintaan Google API.
expires_in Masa pakai token akses yang tersisa dalam hitungan detik.
id_token Catatan: Properti ini hanya dikembalikan jika permintaan Anda termasuk ruang lingkup identitas, seperti openid , profile , atau email . Nilainya adalah JSON Web Token (JWT) yang berisi informasi identitas yang ditandatangani secara digital tentang pengguna.
refresh_token Token yang dapat Anda gunakan untuk mendapatkan token akses baru. Token penyegaran berlaku hingga pengguna mencabut akses. Perhatikan bahwa token penyegaran selalu dikembalikan untuk aplikasi yang diinstal.
scope Lingkup akses yang diberikan oleh access_token dinyatakan sebagai daftar ruang-delimited, case-sensitive string.
token_type Jenis token yang dikembalikan. Pada saat ini, nilai bidang ini selalu diatur ke Bearer .

Cuplikan berikut menunjukkan contoh respons:

{
  "access_token": "1/fFAGRNJru1FTz70BzhT3Zg",
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/drive.metadata.readonly",
  "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 melakukan hal ini, termasuk akses token permintaan untuk API dengan termasuk salah seorang access_token parameter permintaan atau Authorization header HTTP Bearer nilai. Jika memungkinkan, header HTTP lebih disukai, karena string kueri cenderung terlihat di log server. Dalam kebanyakan kasus, Anda dapat menggunakan perpustakaan klien untuk mengatur panggilan Anda ke Google API (misalnya, ketika memanggil API drive Files ).

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

Contoh HTTP GET

Panggilan untuk drive.files endpoint (API drive Files) dengan menggunakan Authorization: Bearer HTTP header yang mungkin terlihat seperti berikut ini. Perhatikan bahwa Anda perlu menentukan token akses Anda sendiri:

GET /drive/v2/files HTTP/1.1
Host: www.googleapis.com
Authorization: Bearer access_token

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

GET https://www.googleapis.com/drive/v2/files?access_token=access_token

curl contoh

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

curl -H "Authorization: Bearer access_token" https://www.googleapis.com/drive/v2/files

Atau, sebagai alternatif, opsi parameter string kueri:

curl https://www.googleapis.com/drive/v2/files?access_token=access_token

Menyegarkan token akses

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

Untuk me-refresh token akses, aplikasi Anda mengirimkan HTTPS POST permintaan ke server otorisasi Google ( https://oauth2.googleapis.com/token ) yang meliputi parameter berikut:

bidang
client_id ID klien yang diperoleh dari API Console.
client_secret Klien rahasia yang diperoleh dari API Console. (The client_secret tidak berlaku untuk permintaan dari klien terdaftar sebagai Android, iOS, atau aplikasi Chrome.)
grant_type Seperti didefinisikan dalam OAuth 2.0 spesifikasi , nilai bidang ini harus diatur ke refresh_token .
refresh_token Token penyegaran kembali 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 mengembalikan 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 penyegaran yang akan dikeluarkan; satu batas per kombinasi klien/pengguna, dan satu lagi per pengguna di semua klien. Anda harus menyimpan token penyegaran dalam penyimpanan jangka panjang dan terus menggunakannya selama masih valid. Jika aplikasi Anda meminta terlalu banyak token penyegaran, itu mungkin mengalami batas ini, dalam hal ini token penyegaran yang lebih lama akan berhenti bekerja.

Mencabut token

Dalam beberapa kasus, pengguna mungkin ingin mencabut akses yang diberikan ke aplikasi. Seorang pengguna dapat mencabut akses dengan mengunjungi Account Settings . Lihat situs Hapus atau aplikasi bagian akses dari situs pihak ketiga & aplikasi dengan akses ke akun Anda dokumen dukungan untuk informasi lebih lanjut.

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

Pemrograman mencabut token, aplikasi Anda membuat permintaan untuk https://oauth2.googleapis.com/revoke dan termasuk 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 penyegaran. Jika token adalah token akses dan memiliki token penyegaran yang sesuai, token penyegaran juga akan dicabut.

Jika pencabutan tersebut berhasil diproses, maka HTTP kode status respon adalah 200 . Untuk kondisi kesalahan, HTTP kode status 400 dikembalikan bersama dengan kode kesalahan.

Bacaan lebih lanjut

IETF Terbaik Saat Ini Practice OAuth 2.0 untuk Native Apps menetapkan banyak praktek-praktek terbaik didokumentasikan di sini.