Ringkasan
Dengan izin terperinci, konsumen mendapatkan kontrol yang lebih mendetail atas data akun mereka memilih untuk berbagi dengan setiap aplikasi. Mereka menguntungkan pengguna dan pengembang dengan memberikan kontrol, transparansi, dan keamanan. Panduan ini akan membantu Anda memahami hal-hal yang diperlukan perubahan dan langkah-langkah agar berhasil memperbarui aplikasi Anda untuk menangani izin yang terperinci.
Apa yang dimaksud dengan izin terperinci?
Bayangkan Anda mengembangkan aplikasi produktivitas yang meminta cakupan email dan kalender. Pengguna Anda mungkin ingin menggunakan aplikasi Anda hanya untuk Google Kalender, bukan Gmail. Dengan OAuth terperinci izin akses, pengguna dapat memilih untuk hanya memberikan izin Google Kalender, bukan Gmail. Dengan mengizinkan pengguna memberikan akses ke data tertentu, hal ini meminimalkan eksposur data, mendukung kepercayaan, dan memberdayakan pengguna dengan kontrol yang mengutamakan privasi atas kehidupan digital mereka. Penting untuk merancang aplikasi Anda untuk menangani skenario tersebut.
Jika lebih dari satu cakupan non-Login diminta
Cakupan Login dan non-Login
Untuk aplikasi yang meminta cakupan Login dan non-Login, pengguna akan melihat izin terlebih dahulu
untuk Cakupan Login
(email
, profile
, dan openid
). Setelah pengguna mengizinkan
membagikan informasi identitas dasar mereka (nama, alamat email, dan foto profil), pengguna akan melihat
layar persetujuan izin terperinci untuk cakupan non-Login. Dalam hal ini, aplikasi
harus memeriksa cakupan yang diberikan oleh pengguna dan tidak boleh berasumsi bahwa pengguna memenuhi semua permintaan
cakupan. Pada contoh berikut, aplikasi web meminta ketiga cakupan Sign-In dan
Cakupan Google Drive tanpa Login. Setelah pengguna menyetujui cakupan Login, pengguna akan melihat
layar persetujuan izin terperinci untuk izin Google Drive:
Lebih dari satu cakupan non-Login
Layar persetujuan izin yang terperinci akan ditampilkan kepada pengguna saat aplikasi meminta izin lainnya dari satu cakupan non-Login. Pengguna dapat memilih izin berbagi yang ingin mereka setujui dengan aplikasi. Berikut adalah contoh layar izin terperinci yang meminta akses ke pesan Gmail dan data Google Kalender pengguna:
Untuk aplikasi yang hanya meminta Login
cakupan (email
, profile
, dan openid
), model
layar persetujuan izin tidak berlaku. Pengguna menyetujui atau menolak seluruh proses login
permintaan. Dengan kata lain, jika aplikasi hanya meminta cakupan Login (satu, dua, atau semua
tiga), layar persetujuan izin terperinci tidak berlaku.
Untuk aplikasi yang hanya meminta satu cakupan non-Login, layar persetujuan izin tidak berlaku. Dengan kata lain, pengguna menyetujui atau menolak seluruh permintaan, dan tidak ada kotak centang di layar izin. Tabel berikut merangkum saat layar izin terperinci ditampilkan.
Jumlah cakupan Login | Jumlah cakupan Non-Login | Layar izin izin terperinci |
---|---|---|
1-3 | 0 | Tidak berlaku |
1-3 | 1+ | Berlaku |
0 | 1 | Tidak berlaku |
0 | 2+ | Berlaku |
Tentukan apakah aplikasi Anda terpengaruh
Lakukan peninjauan menyeluruh pada semua bagian dalam permohonan Anda jika Endpoint otorisasi Google OAuth 2.0 digunakan untuk permintaan izin. Perhatikan aplikasi yang meminta beberapa cakupan saat mengaktifkan layar izin izin terperinci yang ditampilkan kepada pengguna. Dalam kasus tersebut, pastikan kode Anda dapat menangani kasus di mana pengguna hanya mengizinkan beberapa cakupan.
Cara menentukan apakah aplikasi Anda menggunakan beberapa cakupan
Periksa kode aplikasi Anda atau panggilan jaringan keluar untuk menentukan apakah Google OAuth 2.0 permintaan otorisasi yang dibuat aplikasi Anda akan menyebabkan layar izin yang terperinci untuk ditampilkan.
Memeriksa kode aplikasi
Tinjau bagian kode aplikasi tempat Anda melakukan panggilan ke Google OAuth endpoint otorisasi untuk meminta izin dari pengguna. Jika menggunakan salah satu Library Klien Google API, Anda sering kali dapat menemukan cakupan yang diminta aplikasi Anda dalam langkah-langkah inisialisasi klien. Beberapa contoh ditampilkan di bagian berikut. Anda harus merujuk ke dokumentasi SDK yang digunakan aplikasi Anda untuk menangani Google OAuth 2.0 guna menentukan apakah aplikasi terpengaruh, dengan menggunakan panduan yang ditampilkan dalam contoh berikut sebagai alamat IP internal.
Google Identity Services
Google Identity Services berikut
Cuplikan kode library JavaScript menginisialisasi TokenClient
dengan beberapa
non-Login. Layar persetujuan izin terperinci akan ditampilkan saat web
aplikasi meminta otorisasi dari pengguna.
const client = google.accounts.oauth2.initTokenClient({ client_id: 'YOUR_CLIENT_ID', scope: 'https://www.googleapis.com/auth/calendar.readonly \ https://www.googleapis.com/auth/contacts.readonly', callback: (response) => { ... }, });
Python
Cuplikan kode berikut menggunakan modul google-auth-oauthlib.flow
untuk
membuat permintaan otorisasi; Parameter scope
menyertakan dua
non-Login. Layar persetujuan izin terperinci akan ditampilkan saat web
aplikasi meminta otorisasi
dari pengguna.
import google.oauth2.credentials import google_auth_oauthlib.flow # Use the client_secret.json file to identify the application requesting # authorization. The client ID (from that file) and access scopes are required. flow = google_auth_oauthlib.flow.Flow.from_client_secrets_file( 'client_secret.json', scopes=['https://www.googleapis.com/auth/calendar.readonly', 'https://www.googleapis.com/auth/contacts.readonly'])
Node.js
Cuplikan kode berikut membuat objek google.auth.OAuth2
, yang menentukan
parameter dalam permintaan otorisasi yang parameter scope
-nya menyertakan dua
cakupan non-Login. Layar izin izin terperinci akan ditampilkan saat aplikasi web
meminta otorisasi dari pengguna.
const {google} = require('googleapis'); /** * 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 read-only Calendar and Contacts. const scopes = [ 'https://www.googleapis.com/auth/calendar.readonly', 'https://www.googleapis.com/auth/contacts.readonly'] ]; // Generate a url that asks permissions 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 best practices. include_granted_scopes: true });
Memeriksa panggilan jaringan keluar
- Aplikasi web - memeriksa aktivitas jaringan di Chrome
- Android - memeriksa traffic jaringan dengan Network Inspector
-
Aplikasi Chrome
- Buka Ekstensi Chrome halaman
- Centang kotak Mode developer di kanan atas sudut halaman ekstensi
- Pilih ekstensi yang ingin Anda pantau
- Klik link halaman latar belakang di bagian Periksa tampilan di halaman ekstensi
- Pop-up Developer Tools akan terbuka tempat Anda dapat memantau lalu lintas jaringan di Tab Jaringan
- iOS - Menganalisis traffic HTTP dengan Instrument
- Platform Windows Universal (UWP) - Memeriksa traffic jaringan di Visual Studio
- Aplikasi desktop - menggunakan alat penangkap jaringan tersedia untuk sistem operasi tempat aplikasi itu dikembangkan
Saat memeriksa panggilan jaringan, cari permintaan yang dikirim ke Google OAuth
endpoint otorisasi dan periksa parameter scope
.
Nilai ini menyebabkan layar izin terperinci ditampilkan.
Parameter
scope
berisi cakupan Login dan cakupan non-Login.Contoh permintaan berikut berisi ketiga cakupan Login dan satu cakupan non-Login untuk melihat metadata file Google Drive pengguna:
https://accounts.google.com/o/oauth2/v2/auth? access_type=offline& scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.email%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fuserinfo.profile%20openid%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly& include_granted_scopes=true& response_type=code& redirect_uri=YOUR_REDIRECT_URL& client_id=YOUR_CLIENT_ID
Parameter
scope
berisi lebih dari satu cakupan non-Login.Contoh permintaan berikut berisi dua cakupan non-Login untuk melihat Google Drive pengguna metadata dan mengelola file Google Drive tertentu:
https://accounts.google.com/o/oauth2/v2/auth? access_type=offline& scope=https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.metadata.readonly%20https%3A%2F%2Fwww.googleapis.com%2Fauth%2Fdrive.file& include_granted_scopes=true& response_type=code& redirect_uri=YOUR_REDIRECT_URL& client_id=YOUR_CLIENT_ID
Praktik terbaik untuk menangani izin terperinci
Jika Anda menentukan bahwa aplikasi Anda perlu diupdate agar dapat menangani Anda harus melakukan pembaruan yang diperlukan pada kode untuk menangani izin dengan benar untuk beberapa cakupan. Semua aplikasi harus mematuhi praktik terbaik berikut:
- Tinjau Layanan Google API: Kebijakan Data Pengguna dan pastikan Anda mematuhinya.
- Minta cakupan spesifik yang diperlukan untuk tugas. Anda harus mematuhi kebijakan Google OAuth 2.0 yang hanya meminta cakupan yang butuhkan. Sebaiknya hindari meminta beberapa cakupan saat login, kecuali jika penting untuk fungsi inti aplikasi. Pemaketan beberapa cakupan bersama-sama, terutama bagi pengguna pemula yang tidak terbiasa dengan fitur aplikasi, dapat menyulitkan mereka untuk memahami kebutuhan akan izin akses. Hal ini dapat memicu alarm dan mencegah pengguna berinteraksi lebih lanjut dengan aplikasi Anda.
- Berikan justifikasi kepada pengguna sebelum meminta permintaan otorisasi. Jelaskan mengapa aplikasi Anda membutuhkan izin yang diminta, apa yang akan Anda lakukan dengan data pengguna, dan bagaimana pengguna akan mendapat manfaat dari menyetujui permintaan. Riset kami menunjukkan bahwa penjelasan ini meningkatkan kepercayaan dan interaksi pengguna.
- Penggunaan otorisasi inkremental kapan pun aplikasi Anda meminta cakupan agar tidak perlu mengelola banyak token akses.
- Periksa cakupan mana yang diberikan pengguna. Saat meminta beberapa sekaligus, pengguna mungkin tidak dapat memberikan semua cakupan yang diminta aplikasi Anda. Aplikasi Anda harus selalu memeriksa cakupan yang diberikan oleh pengguna dan menangani setiap penolakan cakupan dengan menonaktifkan baru. Mengikuti kebijakan Google OAuth 2.0 tentang menangani izin untuk beberapa cakupan dan hanya meminta persetujuan pengguna lagi setelah mereka menyatakannya dengan jelas maksud untuk menggunakan fitur tertentu yang memerlukan cakupan.
Mengupdate aplikasi untuk menangani izin terperinci
Aplikasi Android
Anda harus membaca dokumentasi SDK yang digunakan untuk berinteraksi dengan Google OAuth 2.0 dan mengupdate aplikasi untuk menangani izin terperinci berdasarkan praktik terbaik.
Jika menggunakan
SDK auth.api.signin
dari Layanan Play untuk berinteraksi dengan Google OAuth 2.0, Anda dapat menggunakan
fungsi requestPermissions
untuk meminta kumpulan cakupan terkecil yang diperlukan,
dan fungsi
hasPermissions
untuk memeriksa cakupan yang diberikan pengguna saat
meminta izin terperinci.
Aplikasi ekstensi Chrome
Sebaiknya Anda menggunakan Chrome Identity API agar berfungsi dengan Google OAuth 2.0 berdasarkan praktik terbaik.
Contoh berikut menunjukkan cara menangani izin terperinci dengan benar.
manifest.json
Contoh file manifes mendeklarasikan dua cakupan non-Login untuk ekstensi Chrome aplikasi.
{ "name": "Example Chrome extension application", ... "permissions": [ "identity" ], "oauth2" : { "client_id": "YOUR_CLIENT_ID", "scopes":["https://www.googleapis.com/auth/calendar.readonly", "https://www.googleapis.com/auth/contacts.readonly"] } }
Pendekatan yang Salah
Semua atau tidak sama sekali
Pengguna mengklik tombol tersebut untuk memulai proses otorisasi. Cuplikan kode ini mengasumsikan
pengguna akan dihadapkan pada “semuanya atau tidak sama sekali” layar persetujuan untuk dua cakupan yang ditentukan
dalam file manifest.json
. AI mengabaikan pemeriksaan cakupan mana yang diberikan pengguna.
oauth.js
... document.querySelector('button').addEventListener('click', function () { chrome.identity.getAuthToken({ interactive: true }, function (token) { if (token === undefined) { // User didn't authorize both scopes. // Updating the UX and application accordingly ... } else { // User authorized both or one of the scopes. // It neglects to check which scopes users granted and assumes users granted all scopes. // Calling the APIs, etc. ... } }); });
Pendekatan yang Benar
Cakupan terkecil
Pilih kumpulan cakupan terkecil yang diperlukan
Aplikasi hanya boleh meminta serangkaian cakupan terkecil yang diperlukan. Disarankan aplikasi Anda meminta satu ruang lingkup pada satu waktu ketika diperlukan untuk menyelesaikan tugas.
Dalam contoh ini, diasumsikan bahwa kedua cakupan yang dideklarasikan dalam manifest.json
adalah kumpulan cakupan terkecil yang dibutuhkan. File oauth.js
menggunakan Chrome
Identity API untuk memulai proses otorisasi dengan Google. Anda harus memilih ikut serta dalam
mengaktifkan izin terperinci, sehingga pengguna memiliki kontrol yang lebih besar
aplikasi. Aplikasi Anda harus menangani respons dari pengguna dengan benar dengan memeriksa cakupan mana yang diotorisasi pengguna.
oauth.js
... document.querySelector('button').addEventListener('click', function () { chrome.identity.getAuthToken({ interactive: true, enableGranularPermissions: true }, function (token, grantedScopes) { if (token === undefined) { // User didn't authorize any scope. // Updating the UX and application accordingly ... } else { // User authorized the request. Now, check which scopes were granted. if (grantedScopes.includes('https://www.googleapis.com/auth/calendar.readonly')) { // User authorized Calendar read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Calendar read permission. // Update UX and application accordingly ... } if (grantedScopes.includes('https://www.googleapis.com/auth/contacts.readonly')) { // User authorized Contacts read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Contacts read permission. // Update UX and application accordingly ... } } }); });
Aplikasi iOS, iPadOS, dan macOS
Anda harus membaca dokumentasi SDK yang digunakan untuk berinteraksi dengan Google OAuth 2.0 dan mengupdate aplikasi untuk menangani izin terperinci berdasarkan praktik terbaik.
Jika Anda menggunakan library Login dengan Google untuk iOS dan macOS untuk berinteraksi dengan Google OAuth 2.0, Anda harus meninjau dokumentasi tentang penanganan terperinci izin akses.
Aplikasi web
Sebaiknya baca dokumentasi SDK yang Anda gunakan untuk berinteraksi dengan Google OAuth 2.0 dan perbarui aplikasi Anda untuk menangani izin akses terperinci berdasarkan praktik terbaik kami.
Akses sisi server (offline)
- Siapkan server dan tentukan endpoint yang dapat diakses secara publik untuk menerima otorisasi pada kode sumber.
- Konfigurasikan URI pengalihan endpoint publik Anda di konsol Google Cloud.
Cuplikan kode berikut menunjukkan contoh NodeJS yang meminta dua cakupan non-Login. Pengguna akan melihat layar persetujuan izin yang terperinci.
Pendekatan yang Salah
Semua atau tidak sama sekali
Pengguna dialihkan ke URL otorisasi. Cuplikan kode mengasumsikan bahwa pengguna akan melihat
layar izin "semua atau tidak sama sekali" untuk dua cakupan yang ditentukan dalam
array scopes
. AI mengabaikan pemeriksaan cakupan mana yang diberikan pengguna.
main.js
... const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for two non-Sign-In scopes - Google Calendar and Contacts const scopes = [ 'https://www.googleapis.com/auth/contacts.readonly', 'https://www.googleapis.com/auth/calendar.readonly' ]; // Generate a url that asks permissions for the Google Calendar and Contacts scopes const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', // Pass in the scopes array defined above scope: scopes, // Enable incremental authorization. Recommended as best practices. include_granted_scopes: true }); async function main() { const server = http.createServer(async function (req, res) { // Example on redirecting user to Google OAuth 2.0 server. if (req.url == '/') { res.writeHead(301, { "Location": authorizationUrl }); } // Receive the callback from Google OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the Google OAuth 2.0 server response let q = url.parse(req.url, true).query; if (q.error) { // User didn't authorize both scopes. // Updating the UX and application accordingly ... } else { // User authorized both or one of the scopes. // It neglects to check which scopes users granted and assumes users granted all scopes. // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); // Calling the APIs, etc. ... } } res.end(); }).listen(80); }
Pendekatan yang Benar
Cakupan terkecil
Pilih kumpulan cakupan terkecil yang diperlukan
Aplikasi hanya boleh meminta kumpulan cakupan terkecil yang diperlukan. Disarankan aplikasi Anda meminta satu ruang lingkup pada satu waktu ketika diperlukan untuk menyelesaikan tugas. Kapan pun aplikasi Anda meminta cakupan, aplikasi itu harus menggunakan otorisasi inkremental agar tidak perlu mengelola banyak token akses.
Jika aplikasi Anda harus meminta beberapa cakupan selain Masuk, Anda harus selalu menggunakan otorisasi inkremental saat meminta dan memeriksa cakupan mana yang diberikan pengguna.
Dalam contoh ini, diasumsikan bahwa kedua cakupan yang dinyatakan diperlukan agar aplikasi berfungsi dengan baik. Anda harus memilih untuk mengaktifkan izin terperinci, sehingga pengguna memiliki kontrol yang lebih besar untuk memberikan izin ke aplikasi Anda. Aplikasi Anda harus menangani respons dari pengguna dengan tepat dengan memeriksa cakupan mana yang telah mereka izinkan.
main.js
... const oauth2Client = new google.auth.OAuth2( YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, YOUR_REDIRECT_URL ); // Access scopes for two non-Sign-In scopes - Google Calendar and Contacts const scopes = [ 'https://www.googleapis.com/auth/contacts.readonly', 'https://www.googleapis.com/auth/calendar.readonly' ]; // Generate a url that asks permissions for the Google Calendar and Contacts scopes const authorizationUrl = oauth2Client.generateAuthUrl({ // 'online' (default) or 'offline' (gets refresh_token) access_type: 'offline', // Pass in the scopes array defined above scope: scopes, // Enable incremental authorization. Recommended as best practices. include_granted_scopes: true, // Set to true to enable more granular permissions for Google OAuth 2.0 client IDs created before 2019. // No effect for newer Google OAuth 2.0 client IDs, since more granular permissions is always enabled for them. enable_granular_consent: true }); async function main() { const server = http.createServer(async function (req, res) { // Redirect users to Google OAuth 2.0 server. if (req.url == '/') { res.writeHead(301, { "Location": authorizationUrl }); } // Receive the callback from Google OAuth 2.0 server. if (req.url.startsWith('/oauth2callback')) { // Handle the Google OAuth 2.0 server response let q = url.parse(req.url, true).query; if (q.error) { // User didn't authorize both scopes. // Updating the UX and application accordingly ... } else { // Get access and refresh tokens (if access_type is offline) let { tokens } = await oauth2Client.getToken(q.code); oauth2Client.setCredentials(tokens); // User authorized the request. Now, check which scopes were granted. if (tokens.scope.includes('https://www.googleapis.com/auth/calendar.readonly')) { // User authorized Calendar read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Calendar read permission. // Calling the APIs, etc. ... } // Check which scopes user granted the permission to application if (tokens.scope.includes('https://www.googleapis.com/auth/contacts.readonly')) { // User authorized Contacts read permission. // Calling the APIs, etc. ... } else { // User didn't authorize Contacts read permission. // Update UX and application accordingly ... } } } res.end(); }).listen(80); }
Ulas panduan aplikasi web sisi server terkait cara mengakses Google API dari aplikasi berbasis server.
Akses khusus sisi klien
- Untuk aplikasi yang menggunakan Google Identity Services library JavaScript untuk berinteraksi dengan Google OAuth 2.0, Anda harus meninjau dokumentasi tentang penanganan izin akses terperinci.
- Untuk aplikasi yang langsung melakukan panggilan menggunakan JavaScript ke endpoint otorisasi OAuth 2.0 Google, Anda harus meninjau dokumentasi ini tentang cara menangani izin terperinci.
Menguji aplikasi yang diupdate dalam menangani izin terperinci
- Uraikan semua kasus yang dapat direspons pengguna terhadap permintaan izin dan perilaku yang diharapkan dari aplikasi Anda. Misalnya, jika pengguna hanya mengotorisasi dua kali dari tiga cakupan yang diminta, aplikasi Anda harus berperilaku sesuai.
-
Uji aplikasi Anda dengan mengaktifkan izin terperinci. Ada dua cara untuk mengaktifkan
izin terperinci:
- Periksa layar izin OAuth 2.0 aplikasi Anda untuk melihat apakah izin terperinci sudah diaktifkan untuk aplikasi Anda. Anda juga dapat membuat client ID Google OAuth 2.0 Web, Android, atau iOS baru melalui konsol Google Cloud untuk tujuan pengujian, karena izin terperinci akan selalu diaktifkan untuk pod.
-
Menetapkan parameter
enable_granular_consent
ketrue
saat memanggil Google OAuth endpoint otorisasi. Beberapa SDK memiliki dukungan eksplisit untuk hal ini . Untuk yang lainnya, periksa dokumentasi untuk melihat bagaimana Anda dapat menambahkan parameter ini dan nilainya secara manual. Jika penerapan Anda tidak mendukung penambahan parameter, Anda dapat membuat client ID Google OAuth 2.0 Web, Android, atau iOS baru melalui konsol Google Cloud hanya untuk tujuan pengujian seperti yang dinyatakan pada poin sebelumnya.
- Saat menguji aplikasi yang telah diupdate, gunakan Akun Google pribadi (@gmail.com), bukan akun Workspace. Hal ini karena aplikasi Workspace Enterprise dengan delegasi tingkat domain atau ditandai sebagai Tepercaya tidak terpengaruh oleh perubahan pada izin terperinci saat ini. Oleh karena itu, melakukan pengujian dengan Workspace akun dari organisasi Anda mungkin tidak menampilkan layar izin terperinci yang baru sebagaimana mestinya.