Panduan penerapan OAuth 2.1

Panduan ini menguraikan cara mengizinkan platform Aplikasi terhubung dengan aman untuk mengakses layanan Anda. Untuk integrasi MCP Aplikasi terhubung, kami sangat merekomendasikan penggunaan OAuth 2.1, standar industri untuk otorisasi yang didelegasikan, dengan Proof Key for Code Exchange (PKCE) guna memastikan keamanan tertinggi untuk data pengguna dan keandalan dalam alur "agentic". Platform Aplikasi terhubung mendukung jenis pemberian kode otorisasi dengan parameter Proof Key for Code Exchange (PKCE).

PKCE wajib untuk semua OAuth 2.1 dan opsional untuk OAuth2.0.

Untuk mengaktifkan penemuan otomatis dan menyederhanakan proses aktivasi, server otorisasi Anda harus mendukung ekstensi Metadata Server Otorisasi, yang juga disebut sebagai Penemuan OAuth.

Tips: Untuk menghindari pengalaman pengguna yang menjengkelkan dan keharusan menautkan ulang akun, detail yang paling penting adalah mengelola masa aktif Token Refresh menggunakan Penautan Persisten.

Cara Gemini MCP mengambil JSON konfigurasi

Konsol Gemini MCP mencoba mengambil JSON konfigurasi Anda dari URL berikut, dalam urutan yang ditampilkan di bagian ini.

Perhatian: Konsol Gemini MCP menggunakan URL pertama yang menampilkan respons—termasuk error. Pastikan endpoint pilihan Anda dapat dijangkau dan menampilkan HTTP 200.

Jika URL server otorisasi Anda berada di tingkat teratas domain Anda (misalnya, https://auth.example.com), Gemini akan menambahkan direktori "well-known" standar ke domain Anda dan mencari server dalam urutan berikut:

1. https://auth.example.com/.well-known/oauth-authorization-server
2. https://auth.example.com/.well-known/openid-configuration

Jika URL server otorisasi Anda berada di dalam subdirektori atau jalur tertentu di domain Anda, misalnya, https://auth.example.com/realms/master, Gemini akan menambahkan jalur "well-known" yang sama langsung ke subdirektori tersebut, dalam urutan berikut.

1. .../realms/master/.well-known/oauth-authorization-server
2. .../realms/master/.well-known/openid-configuration
3. .../realms/master/.well-known/openid-configuration (dukungan jalur bertingkat)

Kemampuan JSON yang diperlukan

Respons metadata Anda harus menyertakan kolom berikut. Integrasi akan gagal jika kolom wajib diisi masih kosong atau jenis yang valid tidak ditemukan.

authorization_endpoint

Harus berupa URL string yang valid.

token_endpoint

Harus berupa URL string yang valid.

response_types_supported

Harus berisi string code.

registration_endpoint

Untuk saat ini, Konsol Play mengandalkan Dynamic Client.

Registration (RFC 7591). Anda harus memberikan endpoint pendaftaran di metadata, atau memasukkan client ID/rahasia langsung di UI Konsol Play.

Jika server otorisasi Anda tidak mendukung Dynamic Client Registration (DCR), Anda harus menerapkan dan mengisi kolom Client ID dan Client Secret secara manual dalam UI Konsol Play untuk menyelesaikan integrasi.

Jika penerapan Anda mendukung Proof Key for Code Exchange (PKCE) atau sesi persisten, Anda harus menyertakan kolom kemampuan yang relevan (seperti Challenge Methods dan Grant Types) dalam JSON penemuan Anda. Hal ini membantu memastikan kompatibilitas dengan standar keamanan dan konektivitas Gemini. Jika Anda mendukung cakupan, Anda harus menyertakan kolom scopes_supported.

Contoh konfigurasi

Berikut adalah respons JSON yang valid dan memenuhi persyaratan klien kami.

{
  "issuer": "https://auth.example.com",
  "authorization_endpoint": "https://auth.example.com/oauth/authorize",
  "token_endpoint": "https://auth.example.com/oauth/token",
  "registration_endpoint": "https://auth.example.com/oauth/register",
  "response_types_supported": [
    "code",
    "token",
    "id_token"
  ],
  "grant_types_supported": [
    "authorization_code",
    "refresh_token"
  ]
}

Untuk kasus saat Anda menyertakan PKCE, cuplikan berikut menunjukkan contoh hal yang dapat disertakan dalam blok JSON.

"grant_types_supported": ["authorization_code", "refresh_token"],
"code_challenge_methods_supported": ["S256"]

Untuk kasus saat Anda menyertakan kolom scopes_supported, cuplikan berikut menunjukkan contoh hal yang dapat disertakan dalam blok JSON.

"scopes_supported": ["mcp", "cart.order"],

Alur kode otorisasi (versi yang disederhanakan)

Langkah-langkah berikut menguraikan alur kode otorisasi standar. Urutan ini mengilustrasikan dengan tepat cara Platform aplikasi terhubung mendapatkan token akses yang diperlukan dengan aman dari server Anda untuk bertindak atas nama pengguna.

1. Permintaan otorisasi: Platform Google menentukan bahwa platform tersebut perlu memanggil fungsi Anda, tetapi pengguna belum diotorisasi. Chatbot memulai alur dengan mengalihkan browser pengguna (atau menampilkan link) ke endpoint otorisasi Anda.

   Permintaan ini menyertakan Client ID Anda (atau dibuat otomatis dengan DCR), URI Pengalihan Gemini, dan parameter PKCE penting (code_challenge dan code_challenge_method).

   Izinkan URL berikut untuk penyiapan OAuth:

   • https://oauth-redirect.googleusercontent.com/r/*
   • https://oauth-redirect-sandbox.googleusercontent.com/r/*
   • https://oauth-redirect-test.googleusercontent.com/r/*
   • https://oauth-redirect.googleusercontent.com/a/*
   • https://oauth-redirect-sandbox.googleusercontent.com/a/*
   • https://oauth-redirect-test.googleusercontent.com/a/*

2. Izin pengguna: Server otorisasi Anda memvalidasi permintaan, mengautentikasi pengguna (login), dan meminta pengguna memberikan izin kepada platform Google untuk mengakses data atau layanan mereka.

3. Pemberian kode: Setelah pengguna memberikan izin, server Anda akan mengalihkan browser pengguna kembali ke RedirectURI Gemini, dengan menambahkan kode otorisasi sementara ke URL.

4. Pertukaran token: Backend di balik Gemini mengirimkan permintaan POST ke endpoint token Anda, yang menukarkan kode otorisasi dengan token akses.

   Catatan: Permintaan ini harus menyertakan parameter PKCE (code_verifier) untuk membuktikan bahwa klien yang memulai alur adalah klien yang sama.

5. Akses diberikan: Endpoint token Anda memverifikasi kode dan parameter PKCE, menerbitkan token akses dan secara opsional token refresh, lalu menampilkannya ke Gemini.

   Tips: Meskipun token refresh bersifat opsional, sebaiknya konfigurasikan server otorisasi Anda untuk menerbitkannya. Token refresh memungkinkan Platform aplikasi terhubung mempertahankan akses tanpa harus mengautentikasi ulang pengguna.

Persyaratan utama PKCE

PKCE menambahkan lapisan keamanan untuk mencegah intersepsi kode otorisasi yang tidak sah.

Perhatian: Memenuhi persyaratan PKCE ini sangat penting untuk pengelolaan token akses dan token refresh yang tepat, yang membantu melindungi data pengguna dan menjaga integritas ekosistem.

• code_verifier: String acak kriptografis yang dihasilkan oleh Gemini di awal alur. Informasi ini dijaga kerahasiaannya.
• code_challenge: Transformasi code_verifier, biasanya hashing SHA256. Ini dikirim secara publik, seperti yang dijelaskan dalam langkah 1 alur kode otorisasi.
• Validasi: Endpoint token Anda (dijelaskan di langkah 4 alur kode otorisasi) harus memvalidasi bahwa code_verifier yang diterima, saat diubah, cocok dengan code_challenge asli.

Proses Debug

Info error penautan yang mendetail tersedia di Logs Explorer. Untuk mengaktifkan dan melihat error, ikuti petunjuk di Memantau error Penautan Akun di project Konsol Google Anda.

Persyaratan konfigurasi penautan Akun Google

Baca panduan API berikut untuk mengetahui informasi tentang konfigurasi penautan Akun Google.

• Penautan Akun Google dengan OAuth
• API Penautan Akun Anda
• Google Account Linking API

Agar berhasil mendaftarkan integrasi OAuth, Anda perlu mengonfigurasi detail spesifik tentang server otorisasi Anda. Pastikan Anda telah menyiapkan endpoint, kredensial, dan aset berikut.

Kolom Konfigurasi	Deskripsi	Tanggung Jawab Developer
Client ID dan Rahasia	Kredensial unik yang dibuat server otorisasi Anda khusus untuk Platform aplikasi terhubung. Rahasia Klien adalah kredensial keamanan (sandi) yang terkait dengan Client ID. Catatan: Jika developer menerbitkan Client ID, mereka harus memberikan Client ID ini. Jika Google menerbitkan Client ID, developer mungkin perlu mendaftarkan rahasia atau memverifikasinya.	Gunakan ID yang diberikan oleh platform dalam semua permintaan otorisasi.
Endpoint Otorisasi	URL untuk mengalihkan pengguna agar melakukan autentikasi dan memberikan izin	Menghosting endpoint—misalnya, https://yourdomain.com/oauth/authorize
Endpoint Token	Endpoint backend untuk menukar kode otorisasi dengan token Akses/Refresh, dan untuk memperbarui token yang sudah tidak berlaku.	Hosting endpoint ini—misalnya, https://yourdomain.com/oauth/token
Endpoint Pencabutan Opsional	URL untuk memberi tahu sistem Anda agar membatalkan token saat pengguna memutuskan koneksi. Saat pengguna membatalkan tautan atau memutuskan koneksi integrasi Anda dari dalam platform Aplikasi terhubung, kami akan membuat permintaan POST ke endpoint /revoke yang berisi token Akses atau token refresh. Lihat Membatalkan tautan akun untuk mengetahui informasi selengkapnya.	Menghosting endpoint—misalnya, https://yourdomain.com/oauth/revoke Server Anda harus menangani permintaan ini dengan membatalkan validitas token yang diberikan secara permanen. Hal ini memastikan bahwa setiap upaya berikutnya oleh Platform aplikasi terhubung untuk menggunakan token tersebut akan gagal, sehingga menjaga keamanan data pengguna setelah koneksi diputus.
URI Pengalihan	URL callback spesifik yang disediakan oleh platform tempat Server Otorisasi mengirimkan kembali kode setelah izin diberikan.	Konfigurasikan Server Otorisasi Anda agar hanya menerima URI Pengalihan resmi yang terdaftar dari platform.
Memuat ulang	/token dengan grant_type=refresh_token Mekanisme yang memungkinkan platform Aplikasi terhubung mendapatkan Token Akses baru saat token yang ada habis masa berlakunya, sehingga integrasi tetap terhubung dengan lancar tanpa mengharuskan pengguna login berulang kali. Saat masa berlaku Token Akses yang ada berakhir, Platform aplikasi terhubung akan otomatis membuat permintaan POST ke endpoint /token Anda. Payload permintaan akan menyertakan grant_type=refresh_token beserta Token Refresh yang sebelumnya dikeluarkan oleh server Anda.	Server Anda harus memvalidasi Token Refresh yang diberikan dan menampilkan Token Akses baru dalam respons JSON. Selain itu, untuk menerapkan Penautan Persisten, Anda harus menghindari rotasi Token Refresh selama pertukaran ini. Alih-alih menerbitkan token baru, tampilkan Token Refresh yang sama persis dalam respons JSON dan perpanjang tanggal habis masa berlakunya di backend Anda.
Jenis Respons	Ini harus dikonfigurasi ke CODE untuk mendukung alur Kode Otorisasi.
Cakupan	Serangkaian izin dan tingkat akses tertentu yang menentukan tindakan yang diizinkan untuk dilakukan oleh token. Izin dan tingkat akses ini harus ditentukan sebelumnya dalam konfigurasi Anda agar Google dapat memintanya selama handshake otorisasi awal.	Anda harus memberikan daftar cakupan default (misalnya, openid, profile, email) yang harus diminta oleh platform Aplikasi terhubung saat memulai alur. Cakupan yang diminta harus sesedikit mungkin (prinsip hak istimewa terendah), tetapi sepenuhnya memadai untuk Perjalanan Penting Pengguna (CUJ) yang didukung integrasi MCP Anda.
Aset UI: Logo	Logo developer yang akan ditampilkan di layar penautan akun dan izin.	Harus berupa gambar vektor persegi (SVG) dengan tampilan melingkar dan berukuran minimal 500 x 500 piksel. Misalnya, lihat https://[partner-domain]/assets/logo.svg atau file SVG mentah.
Penautan Aplikasi Native (App Flip)	Untuk mendukung penautan akun langsung dari aplikasi Android atau iOS native, sebaiknya jangan mengandalkan webview standar. Sebagai gantinya, sebaiknya terapkan App Flip untuk pengalaman pengguna yang lancar. Lihat Penautan Akun Google dengan App Flip berbasis OAuth untuk mengetahui informasi selengkapnya.	Selesaikan verifikasi Google Play Store dan App Store, serta sematkan URI Pengalihan Google langsung ke aplikasi native Anda untuk memastikan pengalihan otorisasi antar-aplikasi yang aman.
Masa Berlaku Token	(Opsional) Durasi masa berlaku Token Akses sebelum perlu dimuat ulang. Berguna untuk mengonfigurasi kebijakan waktu tunggu di GAL.	Waktu habis masa berlaku yang umum berkisar dari menit, jam, hari, bergantung pada kebutuhan keamanan—misalnya, 30 days)

Error integrasi umum

Berikut daftar error umum dan kemungkinan solusi yang berlaku untuk proses integrasi.

• Tidak ada pemberian "code": Sistem otomatis platform Gemini secara eksplisit memeriksa response_types_supported untuk nilai "code".
• Endpoint pendaftaran tidak ada: Meskipun server Anda mendukung Dokumen Metadata Client ID, aplikasi Gemini (yang bertindak sebagai klien OAuth yang terhubung ke server Anda) saat ini memerlukan registration_endpoint khusus untuk ada di JSON penemuan.
• Error non-200: Jika mekanisme penemuan metadata otomatis Gemini mencapai URL well-known Anda dan menerima 404 atau 500, mekanisme tersebut tidak akan mencoba menebak URL lain. Pastikan URL Discovery dapat diakses secara publik.