OAuth 2.0 API Google dapat digunakan untuk autentikasi dan otorisasi. Dokumen ini menjelaskan penerapan OAuth 2.0 kami untuk autentikasi, yang sesuai dengan spesifikasi OpenID Connect, dan OpenID Certified. Dokumentasi yang terdapat pada Menggunakan OAuth 2.0 untuk Mengakses Google API juga berlaku untuk layanan ini. Jika Anda ingin mempelajari protokol ini secara interaktif, sebaiknya gunakan Google OAuth 2.0 Playground. Untuk mendapatkan bantuan tentang Stack Overflow, beri tag pada pertanyaan Anda dengan 'google-oauth'.
Menyiapkan OAuth 2.0
Sebelum aplikasi Anda dapat menggunakan sistem autentikasi OAuth 2.0 Google untuk login pengguna, Anda harus menyiapkan project di Google API Console untuk mendapatkan kredensial OAuth 2.0, menetapkan URI pengalihan, dan (opsional) menyesuaikan informasi branding yang dilihat pengguna di layar izin pengguna. Anda juga dapat menggunakan API Console untuk membuat akun layanan, mengaktifkan penagihan, menyiapkan pemfilteran, dan melakukan tugas lainnya. Untuk detail selengkapnya, lihat Bantuan Google API Console.
Mendapatkan kredensial OAuth 2.0
Anda memerlukan kredensial OAuth 2.0, termasuk client ID dan rahasia klien, untuk mengautentikasi pengguna dan mendapatkan akses ke API Google.
Untuk melihat ID klien dan rahasia klien untuk kredensial OAuth 2.0 yang diberikan, klik teks berikut: Pilih kredensial . Di jendela yang terbuka, pilih proyek Anda dan kredensial yang Anda inginkan, lalu klik Lihat .
Atau, lihat ID klien Anda dan rahasia klien dari halaman Kredensial di API Console :
- Go to the Credentials page.
- Klik nama kredensial Anda atau ikon pensil ( create ). ID dan rahasia klien Anda ada di bagian atas halaman.
Menetapkan URI pengalihan
URI pengalihan yang Anda tetapkan dalam API Console menentukan tempat Google mengirimkan respons terhadap permintaan autentikasi.
Untuk membuat, melihat, atau mengedit URI redirect untuk kredensial OAuth 2.0 yang diberikan, lakukan hal berikut:
- Go to the Credentials page.
- Di bagian OAuth 2.0 klien ID halaman, klik kredensial.
- Lihat atau edit URI pengalihan.
Jika tidak ada bagian ID klien OAuth 2.0 di halaman Kredensial, maka proyek Anda tidak memiliki kredensial OAuth. Untuk membuatnya, klik Buat kredensial .
Menyesuaikan layar izin pengguna
Bagi pengguna Anda, pengalaman autentikasi OAuth 2.0 mencakup layar izin yang menjelaskan informasi yang dirilis pengguna dan persyaratan yang berlaku. Misalnya, saat pengguna login, mereka mungkin diminta untuk memberi aplikasi Anda akses ke alamat email dan informasi akun dasar miliknya. Anda meminta akses ke informasi ini menggunakan parameter
scope
, yang disertakan aplikasi Anda dalam
permintaan autentikasi. Anda juga dapat menggunakan cakupan untuk meminta akses ke Google API lainnya.
Layar izin pengguna juga menampilkan informasi branding seperti nama produk, logo, dan URL halaman beranda Anda. Anda mengontrol informasi branding di API Console.
To enable your project's consent screen:
- Open the Consent Screen page in the Google API Console.
- If prompted, select a project, or create a new one.
- Fill out the form and click Save.
Dialog izin berikut menunjukkan apa yang akan dilihat pengguna saat kombinasi cakupan OAuth 2.0 dan Google Drive ada dalam permintaan. (Dialog umum ini dibuat menggunakan Google OAuth 2.0 Playground, sehingga tidak menyertakan informasi branding yang akan ditetapkan di API Console.)

Mengakses layanan
Google dan pihak ketiga menyediakan library yang dapat Anda gunakan untuk menangani banyak detail implementasi dalam mengautentikasi pengguna dan mendapatkan akses ke Google API. Contohnya meliputi Layanan Identitas Google dan library klien Google, yang tersedia untuk berbagai platform.
Jika Anda memilih untuk tidak menggunakan library, ikuti petunjuk di bagian lain dokumen ini, yang menjelaskan alur permintaan HTTP yang pada dasarnya berada di library yang tersedia.
Mengautentikasi pengguna
Mengautentikasi pengguna melibatkan perolehan token ID dan memvalidasinya. Token ID adalah fitur standar OpenID Connect yang dirancang untuk digunakan dalam membagikan pernyataan identitas di Internet.
Pendekatan yang paling umum digunakan untuk mengautentikasi pengguna dan mendapatkan token ID disebut alur "server" dan alur "implisit". Alur server memungkinkan server backend untuk memverifikasi identitas pengguna menggunakan browser atau perangkat seluler. Alur implisit digunakan saat aplikasi sisi klien (biasanya aplikasi JavaScript yang berjalan di browser) perlu mengakses API secara langsung, bukan melalui server back-end-nya.
Dokumen ini menjelaskan cara menjalankan alur server untuk mengautentikasi pengguna. Alur implisit secara signifikan lebih rumit karena risiko keamanan dalam menangani dan menggunakan token di sisi klien. Jika Anda perlu menerapkan alur implisit, sebaiknya gunakan Layanan Identitas Google.
Alur server
Pastikan Anda menyiapkan aplikasi di API Console agar dapat menggunakan protokol tersebut dan mengautentikasi pengguna. Saat pengguna mencoba login dengan Google, Anda harus:
- Membuat token status anti-pemalsuan
- Mengirim permintaan autentikasi ke Google
- Mengonfirmasi token status anti-pemalsuan
- Tukarkan
code
dengan token akses dan token ID - Mendapatkan informasi pengguna dari token ID
- Mengautentikasi pengguna
1. Membuat token status anti-pemalsuan
Anda harus melindungi keamanan pengguna dengan mencegah permintaan pemalsuan permintaan. Langkah pertama adalah membuat token sesi unik yang menyimpan status antara aplikasi Anda dan klien pengguna. Kemudian Anda mencocokkan token sesi unik ini dengan respons autentikasi yang ditampilkan oleh layanan Login dengan Google OAuth untuk memverifikasi bahwa pengguna membuat permintaan dan bukan penyerang berbahaya. Token ini sering disebut sebagai token pemalsuan permintaan lintas situs (CSRF).
Salah satu pilihan yang baik untuk token status adalah string yang terdiri dari 30 atau lebih karakter yang dibuat menggunakan generator angka acak berkualitas tinggi. Yang lainnya adalah hash yang dihasilkan dengan menandatangani beberapa variabel status sesi Anda dengan kunci yang dirahasiakan di backend Anda.
Kode berikut menunjukkan pembuatan token sesi yang unik.
PHP
Anda harus mendownload library klien Google API untuk PHP agar dapat menggunakan contoh ini.
// Create a state token to prevent request forgery. // Store it in the session for later validation. $state = bin2hex(random_bytes(128/8)); $app['session']->set('state', $state); // Set the client ID, token state, and application name in the HTML while // serving it. return $app['twig']->render('index.html', array( 'CLIENT_ID' => CLIENT_ID, 'STATE' => $state, 'APPLICATION_NAME' => APPLICATION_NAME ));
Java
Anda harus mendownload library klien Google API untuk Java agar dapat menggunakan contoh ini.
// Create a state token to prevent request forgery. // Store it in the session for later validation. String state = new BigInteger(130, new SecureRandom()).toString(32); request.session().attribute("state", state); // Read index.html into memory, and set the client ID, // token state, and application name in the HTML before serving it. return new Scanner(new File("index.html"), "UTF-8") .useDelimiter("\\A").next() .replaceAll("[{]{2}\\s*CLIENT_ID\\s*[}]{2}", CLIENT_ID) .replaceAll("[{]{2}\\s*STATE\\s*[}]{2}", state) .replaceAll("[{]{2}\\s*APPLICATION_NAME\\s*[}]{2}", APPLICATION_NAME);
Python
Anda harus mendownload library klien Google API untuk Python untuk menggunakan contoh ini.
# Create a state token to prevent request forgery. # Store it in the session for later validation. state = hashlib.sha256(os.urandom(1024)).hexdigest() session['state'] = state # Set the client ID, token state, and application name in the HTML while # serving it. response = make_response( render_template('index.html', CLIENT_ID=CLIENT_ID, STATE=state, APPLICATION_NAME=APPLICATION_NAME))
2. Kirim permintaan autentikasi ke Google
Langkah berikutnya adalah membuat permintaan GET
HTTPS dengan parameter URI yang sesuai.
Perhatikan penggunaan HTTPS, bukan HTTP dalam semua langkah proses ini; koneksi HTTP ditolak. Anda harus mengambil URI dasar dari dokumen Discovery
menggunakan nilai metadata authorization_endpoint
. Diskusi berikut mengasumsikan
URI dasar adalah https://accounts.google.com/o/oauth2/v2/auth
.
Untuk permintaan dasar, tentukan parameter berikut:
client_id
, yang Anda peroleh dari API Console Credentials page .response_type
, yang dalam permintaan alur kode otorisasi dasar harus berupacode
. (Baca selengkapnya diresponse_type
.)scope
, yang dalam permintaan dasar harusopenid email
. (Baca selengkapnya discope
.)redirect_uri
harus menjadi endpoint HTTP pada server Anda yang akan menerima respons dari Google. Nilai harus sama persis dengan salah satu URI pengalihan yang diberi otorisasi untuk klien OAuth 2.0, yang Anda konfigurasikan di API Console Credentials page. Jika nilai ini tidak cocok dengan URI yang diotorisasi, permintaan akan gagal dengan errorredirect_uri_mismatch
.state
harus menyertakan nilai token sesi unik anti-pemalsuan, serta informasi lain yang diperlukan untuk memulihkan konteks saat pengguna kembali ke aplikasi Anda, misalnya, URL awal. (Baca selengkapnya distate
.)nonce
adalah nilai acak yang dihasilkan oleh aplikasi Anda yang memungkinkan perlindungan replay saat ada.login_hint
dapat berupa alamat email pengguna atau stringsub
, yang setara dengan ID Google pengguna. Jika Anda tidak memberikanlogin_hint
dan pengguna saat ini sudah login, layar izin akan menyertakan permintaan persetujuan untuk merilis alamat email pengguna ke aplikasi Anda. (Baca selengkapnya dilogin_hint
.)- Gunakan parameter
hd
untuk mengoptimalkan alur OpenID Connect bagi pengguna domain tertentu yang terkait dengan organisasi Google Cloud. (Baca selengkapnya dihd
.)
Berikut adalah contoh URI autentikasi OpenID Connect lengkap, dengan jeda baris dan spasi untuk keterbacaan:
https://accounts.google.com/o/oauth2/v2/auth? response_type=code& client_id=424911365001.apps.googleusercontent.com& scope=openid%20email& redirect_uri=https%3A//oauth2.example.com/code& state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome& login_hint=jsmith@example.com& nonce=0394852-3190485-2490358& hd=example.com
Pengguna diwajibkan untuk memberikan izin jika aplikasi Anda meminta informasi baru tentang mereka, atau jika aplikasi Anda meminta akses akun yang belum disetujui sebelumnya.
3. Konfirmasi token status anti-pemalsuan
Responsnya dikirim ke redirect_uri
yang Anda tentukan dalam permintaan. Semua respons ditampilkan dalam string kueri, seperti yang ditunjukkan di bawah:
https://oauth2.example.com/code?state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foa2cb.example.com%2FmyHome&code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7&scope=openid%20email%20https://www.googleapis.com/auth/userinfo.email
Di server, Anda harus mengonfirmasi bahwa state
yang diterima dari Google cocok dengan
token sesi yang Anda buat di Langkah 1. Verifikasi dua arah ini
membantu memastikan bahwa yang membuat permintaan adalah pengguna, bukan skrip berbahaya.
Kode berikut menunjukkan konfirmasi token sesi yang Anda buat di Langkah 1:
PHP
Anda harus mendownload library klien Google API untuk PHP agar dapat menggunakan contoh ini.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if ($request->get('state') != ($app['session']->get('state'))) { return new Response('Invalid state parameter', 401); }
Java
Anda harus mendownload library klien Google API untuk Java agar dapat menggunakan contoh ini.
// Ensure that there is no request forgery going on, and that the user // sending us this connect request is the user that was supposed to. if (!request.queryParams("state").equals( request.session().attribute("state"))) { response.status(401); return GSON.toJson("Invalid state parameter."); }
Python
Anda harus mendownload library klien Google API untuk Python untuk menggunakan contoh ini.
# Ensure that the request is not a forgery and that the user sending # this connect request is the expected user. if request.args.get('state', '') != session['state']: response = make_response(json.dumps('Invalid state parameter.'), 401) response.headers['Content-Type'] = 'application/json' return response
4. Tukarkan code
dengan token akses dan token ID
Respons ini mencakup parameter code
, yaitu kode otorisasi sekali pakai yang dapat ditukarkan oleh server Anda dengan token akses dan token ID. Server Anda melakukan pertukaran ini dengan mengirimkan
permintaan POST
HTTPS. Permintaan POST
dikirim ke endpoint token, yang harus Anda ambil dari dokumen Discovery menggunakan nilai metadata token_endpoint
. Diskusi berikut mengasumsikan endpoint adalah https://oauth2.googleapis.com/token
. Permintaan harus menyertakan parameter berikut dalam
isi POST
:
Kolom | |
---|---|
code |
Kode otorisasi yang ditampilkan dari permintaan awal. |
client_id |
Client ID yang Anda dapatkan dari API Console Credentials page, seperti yang dijelaskan dalam Mendapatkan kredensial OAuth 2.0. |
client_secret |
Rahasia klien yang Anda dapatkan dari API Console Credentials page, seperti yang dijelaskan dalam Mendapatkan kredensial OAuth 2.0. |
redirect_uri |
URI pengalihan yang diotorisasi untuk client_id tertentu yang ditentukan dalam
API Console
Credentials page, seperti yang dijelaskan dalam
Menetapkan URI pengalihan. |
grant_type |
Kolom ini harus berisi nilai authorization_code ,
seperti yang ditetapkan dalam spesifikasi OAuth 2.0. |
Permintaan yang sebenarnya mungkin terlihat seperti contoh berikut:
POST /token HTTP/1.1 Host: oauth2.googleapis.com Content-Type: application/x-www-form-urlencoded code=4/P7q7W91a-oMsCeLvIaQm6bTrgtp7& client_id=your-client-id& client_secret=your-client-secret& redirect_uri=https%3A//oauth2.example.com/code& grant_type=authorization_code
Respons yang berhasil terhadap permintaan ini berisi kolom-kolom berikut dalam array JSON:
Kolom | |
---|---|
access_token |
Token yang dapat dikirim ke Google API. |
expires_in |
Sisa masa aktif token akses dalam hitungan detik. |
id_token |
JWT yang berisi informasi identitas tentang pengguna yang ditandatangani secara digital oleh Google. |
scope |
Cakupan akses yang diberikan oleh access_token yang dinyatakan sebagai daftar string yang dipisahkan spasi dan peka huruf besar/kecil. |
token_type |
Mengidentifikasi jenis token yang ditampilkan. Saat ini, kolom ini selalu memiliki nilai
Bearer .
|
refresh_token |
(opsional)
Kolom ini hanya ada jika
parameter |
5. Memperoleh informasi pengguna dari token ID
Token ID adalah JWT (JSON Web Token), yaitu objek JSON berenkode Base64 yang ditandatangani secara kriptografis. Biasanya, Anda harus memvalidasi token ID sebelum menggunakannya, tetapi karena Anda berkomunikasi langsung dengan Google melalui saluran HTTPS bebas perantara dan menggunakan rahasia klien untuk mengautentikasi diri Anda ke Google, Anda bisa yakin bahwa token yang Anda terima benar-benar berasal dari Google dan valid. Jika server Anda meneruskan token ID ke komponen lain pada aplikasi, sangat penting bagi komponen lain untuk memvalidasi token sebelum menggunakannya.
Karena sebagian besar library API menggabungkan validasi dengan pekerjaan mendekode nilai yang dienkode base64url dan mengurai JSON di dalamnya, Anda mungkin tetap akan memvalidasi token saat mengakses klaim di token ID.
Payload token ID
Token ID adalah objek JSON yang berisi sekumpulan pasangan nama/nilai. Berikut adalah contoh yang diformat agar lebih mudah dibaca:
{ "iss": "https://accounts.google.com", "azp": "1234987819200.apps.googleusercontent.com", "aud": "1234987819200.apps.googleusercontent.com", "sub": "10769150350006150715113082367", "at_hash": "HK6E_P6Dh8Y93mRNtsDB1Q", "hd": "example.com", "email": "jsmith@example.com", "email_verified": "true", "iat": 1353601026, "exp": 1353604926, "nonce": "0394852-3190485-2490358" }
Token ID Google dapat berisi kolom berikut (dikenal sebagai klaim):
Klaim | Tersedia | Deskripsi |
---|---|---|
aud |
selalu | Audiens yang dituju oleh token ID ini. Harus berupa salah satu client ID OAuth 2.0 aplikasi Anda. |
exp |
selalu | Waktu habis masa berlaku pada atau setelah token ID tidak boleh diterima. Diwakili dalam waktu Unix (detik bilangan bulat). |
iat |
selalu | Waktu token ID diterbitkan. Diwakili dalam waktu Unix (bilangan bulat detik). |
iss |
selalu | ID Penerbit untuk Penerbit respons. Selalu
https://accounts.google.com atau accounts.google.com untuk token
ID Google. |
sub |
selalu | ID untuk pengguna, unik di antara semua Akun Google dan tidak pernah digunakan kembali. Akun Google
dapat memiliki beberapa alamat email pada waktu yang berbeda, tetapi
nilai sub tidak pernah berubah. Gunakan sub dalam aplikasi Anda
sebagai kunci ID unik untuk pengguna. Panjang maksimum 255 karakter ASCII yang peka huruf besar/kecil. |
at_hash |
Hash token akses. Memberikan validasi bahwa token akses terkait dengan token identitas. Jika token ID diterbitkan dengan nilai access_token dalam alur server, klaim ini selalu disertakan. Klaim ini dapat digunakan sebagai mekanisme alternatif untuk
melindungi dari serangan pemalsuan permintaan lintas situs, tetapi jika Anda mengikuti
Langkah 1 dan Langkah 3, token
tidak perlu diverifikasi. |
|
azp |
client_id presenter yang diberi otorisasi. Klaim ini hanya diperlukan jika pihak yang meminta token ID tidak sama dengan audiens token ID. Hal ini
dapat terjadi di Google untuk aplikasi hybrid, yang membuat aplikasi web dan aplikasi Android memiliki
client_id OAuth 2.0 yang berbeda, tetapi menggunakan project Google API yang sama. |
|
email |
Alamat email pengguna. Nilai ini mungkin tidak unik untuk pengguna ini dan tidak cocok untuk digunakan sebagai kunci utama. Disediakan hanya jika cakupan Anda menyertakan nilai cakupan email . |
|
email_verified |
True jika alamat email pengguna telah diverifikasi. Jika tidak, false. | |
family_name |
Nama belakang atau nama belakang pengguna. Dapat diberikan jika ada klaim name . |
|
given_name |
Nama depan atau nama depan pengguna. Dapat diberikan jika ada klaim name . |
|
hd |
Domain yang terkait dengan organisasi pengguna Google Cloud. Disediakan hanya jika pengguna termasuk dalam organisasi Google Cloud. | |
locale |
Lokal pengguna, yang direpresentasikan oleh tag bahasa BCP 47.
Mungkin akan diberikan jika ada klaim name . |
|
name |
Nama lengkap pengguna, dalam bentuk yang dapat ditampilkan. Dapat diberikan jika:
Jika ada klaim |
|
nonce |
Nilai nonce yang diberikan oleh aplikasi Anda dalam permintaan autentikasi.
Anda harus menerapkan perlindungan terhadap serangan replay dengan memastikannya hanya ditampilkan
satu kali. |
|
picture |
URL foto profil pengguna. Dapat diberikan jika:
Jika ada klaim |
|
profile |
URL halaman profil pengguna. Dapat diberikan jika:
Jika ada klaim |
6. Mengautentikasi pengguna
Setelah mendapatkan informasi pengguna dari token ID, Anda harus mengkueri database pengguna aplikasi Anda. Jika pengguna sudah ada dalam database, Anda harus memulai sesi aplikasi untuk pengguna tersebut jika semua persyaratan login terpenuhi oleh respons Google API.
Jika pengguna tidak ada dalam database pengguna, Anda harus mengalihkan pengguna ke alur pendaftaran pengguna baru. Anda mungkin dapat mendaftarkan pengguna secara otomatis berdasarkan informasi yang Anda terima dari Google, atau setidaknya Anda dapat mengisi otomatis banyak kolom yang Anda wajibkan pada formulir pendaftaran. Selain informasi dalam token ID, Anda bisa mendapatkan informasi profil pengguna tambahan di endpoint profil pengguna kami.
Topik lanjutan
Bagian berikut menjelaskan Google OAuth 2.0 API secara lebih mendetail. Informasi ini ditujukan bagi developer yang memiliki persyaratan lanjutan seputar autentikasi dan otorisasi.
Akses ke Google API lainnya
Salah satu keuntungan menggunakan OAuth 2.0 untuk autentikasi adalah aplikasi Anda dapat memperoleh
izin untuk menggunakan Google API lainnya atas nama pengguna (seperti YouTube, Google Drive,
Kalender, atau Kontak) secara bersamaan dengan saat Anda mengautentikasi pengguna. Untuk melakukannya, sertakan cakupan lain yang Anda perlukan dalam permintaan autentikasi yang Anda kirim ke Google. Misalnya, untuk menambahkan kelompok usia pengguna ke permintaan autentikasi, teruskan
parameter cakupan
openid email https://www.googleapis.com/auth/profile.agerange.read
. Pengguna
diminta dengan tepat pada layar izin. Token akses yang Anda terima kembali dari Google memungkinkan Anda mengakses semua API yang terkait dengan cakupan akses yang Anda minta dan diberikan.
Token refresh
Dalam permintaan akses API, Anda dapat meminta agar token refresh ditampilkan selama
bursa code
. Token refresh memberi aplikasi Anda akses berkelanjutan ke Google API saat pengguna tidak ada dalam aplikasi. Untuk meminta token refresh, tambahkan parameter access_type
ke offline
dalam permintaan autentikasi.
Pertimbangan:
- Pastikan untuk menyimpan token refresh dengan aman dan permanen, karena Anda hanya dapat memperoleh token refresh saat pertama kali melakukan alur pertukaran kode.
- Ada batasan jumlah token refresh yang dikeluarkan: satu batas per kombinasi klien/pengguna, dan satu lagi per pengguna di semua klien. Jika meminta terlalu banyak token refresh, aplikasi Anda mungkin akan mencapai batas ini, sehingga token refresh lama akan berhenti berfungsi.
Untuk mengetahui informasi selengkapnya, baca Memperbarui token akses (akses offline).
Meminta izin ulang
Anda dapat meminta pengguna untuk memberi otorisasi ulang aplikasi dengan menyetel parameter prompt
ke consent
dalam permintaan autentikasi. Jika prompt=consent
disertakan, layar izin akan ditampilkan setiap kali aplikasi meminta otorisasi cakupan akses, meskipun semua cakupan sebelumnya diberikan ke project Google API Anda. Karena
alasan ini, sertakan prompt=consent
hanya jika diperlukan.
Untuk mengetahui informasi selengkapnya tentang parameter prompt
, lihat prompt
di tabel Parameter URI autentikasi.
Parameter URI autentikasi
Tabel berikut memberikan deskripsi yang lebih lengkap tentang parameter yang diterima oleh API autentikasi OAuth 2.0 Google.
Parameter | Diperlukan | Deskripsi |
---|---|---|
client_id |
(Wajib diisi) | String client ID yang Anda peroleh dari Credentials page API Console, sebagaimana dijelaskan dalam Mendapatkan kredensial OAuth 2.0. |
nonce |
(Wajib diisi) | Nilai acak yang dihasilkan oleh aplikasi Anda yang memungkinkan perlindungan replay. |
response_type |
(Wajib diisi) | Jika nilainya adalah code , peluncuran alur kode otorisasi Dasar, yang memerlukan POST ke endpoint token untuk mendapatkan token. Jika nilainya adalah
token id_token atau id_token token , luncurkan
Alur implisit,
yang mengharuskan penggunaan JavaScript pada URI pengalihan untuk mengambil token dari
ID #fragment URI. |
redirect_uri |
(Wajib diisi) | Menentukan tempat respons dikirimkan. Nilai parameter ini harus sama persis dengan salah satu nilai pengalihan yang sah yang Anda tetapkan dalam API Console Credentials page (termasuk skema HTTP atau HTTPS, kasus, dan akhiran '/', jika ada). |
scope |
(Wajib diisi) | Parameter cakupan harus diawali dengan nilai Jika terdapat nilai cakupan Jika terdapat nilai cakupan Selain cakupan khusus OpenID ini, argumen cakupan Anda juga dapat mencakup nilai cakupan
lainnya. Semua nilai cakupan harus dipisahkan dengan spasi. Misalnya, jika Anda ingin
akses per file ke Google Drive pengguna, parameter cakupan Anda mungkin adalah
Untuk informasi tentang cakupan yang tersedia, lihat Cakupan OAuth 2.0 untuk Google API atau dokumentasi untuk Google API yang ingin Anda gunakan. |
state |
(Opsional, tetapi sangat direkomendasikan) | String buram yang digunakan secara acak dalam protokol; yaitu, string ini ditampilkan sebagai parameter URI dalam Alur dasar, dan dalam ID
|
access_type |
(Opsional) | Nilai yang diizinkan adalah offline dan online . Efeknya
didokumentasikan dalam
Akses Offline; jika token
akses diminta, klien tidak akan menerima token refresh kecuali jika nilai
offline ditentukan. |
display |
(Opsional) | Nilai string ASCII untuk menentukan cara server otorisasi menampilkan
halaman antarmuka pengguna autentikasi dan izin. Nilai berikut ditentukan, dan diterima oleh server Google, tetapi tidak berpengaruh pada perilakunya: page , popup , touch , dan wap . |
hd |
(Opsional) | Sederhanakan proses login untuk akun milik organisasi Google Cloud. Dengan
menyertakan domain organisasi Google Cloud (misalnya, mycollege.edu),
Anda dapat menunjukkan bahwa UI pemilihan akun harus dioptimalkan untuk akun di
domain tersebut. Untuk mengoptimalkan akun organisasi Google Cloud secara umum, bukan hanya satu
domain organisasi Google Cloud, tetapkan nilai tanda bintang ( Jangan andalkan pengoptimalan UI ini untuk mengontrol siapa yang dapat mengakses aplikasi Anda, karena permintaan sisi klien dapat diubah. Pastikan untuk memvalidasi bahwa
token ID yang ditampilkan memiliki nilai klaim |
include_granted_scopes |
(Opsional) | Jika parameter ini disediakan dengan nilai true , dan permintaan otorisasi
diberikan, otorisasi akan menyertakan otorisasi sebelumnya yang diberikan ke
kombinasi pengguna/aplikasi ini untuk cakupan lainnya; lihat
Otorisasi inkremental.
Perlu diperhatikan bahwa Anda tidak dapat melakukan otorisasi inkremental dengan alur Aplikasi yang Diinstal. |
login_hint |
(Opsional) | Jika aplikasi Anda mengetahui pengguna yang ingin diautentikasi, aplikasi ini dapat memberikan parameter ini sebagai petunjuk ke server autentikasi. Meneruskan petunjuk ini akan menekan pemilih akun dan mengisi otomatis kotak email pada formulir login, atau memilih sesi yang tepat (jika pengguna menggunakan login multipel), yang dapat membantu Anda menghindari masalah yang terjadi jika aplikasi login ke akun pengguna yang salah.
Nilainya dapat berupa alamat email atau string sub , yang
setara dengan ID Google pengguna. |
prompt |
(Opsional) | Daftar nilai string yang dipisahkan spasi yang menentukan apakah server otorisasi meminta pengguna untuk mengautentikasi ulang dan memberikan izin. Nilainya dapat berupa:
Jika tidak ada nilai yang ditentukan dan pengguna belum memiliki akses yang diizinkan sebelumnya, pengguna akan melihat layar izin. |
Memvalidasi token ID
Anda perlu memvalidasi semua token ID di server Anda kecuali Anda tahu bahwa token tersebut langsung berasal dari Google. Misalnya, server Anda harus memverifikasi setiap token ID yang diterimanya dari aplikasi klien Anda sebagai asli.
Berikut adalah situasi umum saat Anda dapat mengirim token ID ke server:
- Mengirim token ID dengan permintaan yang perlu diautentikasi. Token ID memberi tahu Anda pengguna tertentu yang membuat permintaan dan klien mana yang diberikan token ID.
Token ID bersifat sensitif dan dapat disalahgunakan jika dicegat. Anda harus memastikan bahwa token ini ditangani dengan aman dengan mentransmisikannya hanya melalui HTTPS dan hanya melalui data POST atau dalam header permintaan. Jika Anda menyimpan token ID di server, Anda juga harus menyimpannya dengan aman.
Hal yang membuat token ID berguna adalah fakta bahwa Anda dapat meneruskannya di sekitar komponen yang berbeda dari aplikasi Anda. Komponen ini dapat menggunakan token ID sebagai mekanisme autentikasi ringan yang mengautentikasi aplikasi dan pengguna. Namun, sebelum dapat menggunakan informasi dalam token ID atau mengandalkannya sebagai pernyataan bahwa pengguna telah melakukan autentikasi, Anda harus memvalidasinya.
Validasi token ID memerlukan beberapa langkah:
- Verifikasikan bahwa token ID ditandatangani dengan benar oleh penerbit. Token yang dikeluarkan Google ditandatangani menggunakan salah satu sertifikat yang ada di URI yang ditetapkan dalam nilai metadata
jwks_uri
dokumen Discovery. - Pastikan nilai klaim
iss
dalam token ID sama denganhttps://accounts.google.com
atauaccounts.google.com
. - Pastikan nilai klaim
aud
dalam token ID sama dengan client ID aplikasi Anda. - Pastikan masa berlaku (klaim
exp
) token ID belum berlalu. - Jika Anda menentukan nilai parameter hd dalam permintaan, pastikan token ID memiliki klaim
hd
yang cocok dengan domain yang diterima yang terkait dengan organisasi Google Cloud.
Langkah 2 hingga 5 hanya melibatkan perbandingan string dan tanggal yang cukup mudah, jadi kami tidak akan merincinya di sini.
Langkah pertama lebih kompleks, dan melibatkan pemeriksaan tanda tangan kriptografi. Untuk tujuan
proses debug, Anda dapat menggunakan endpoint tokeninfo
Google untuk membandingkan
pemrosesan lokal yang diterapkan di server atau perangkat. Misalnya nilai token ID Anda adalah
XYZ123
. Kemudian Anda akan membatalkan referensi URI
https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123
. Jika tanda tangan
token valid, responsnya adalah payload JWT dalam bentuk objek JSON yang didekode.
Endpoint tokeninfo
berguna untuk proses debug, tetapi untuk tujuan
produksi, ambil kunci publik Google dari endpoint kunci dan lakukan validasi secara lokal. Anda harus mengambil URI kunci dari Dokumen penemuan
menggunakan nilai metadata jwks_uri
. Permintaan ke endpoint proses debug dapat dibatasi atau mengalami error sesekali.
Karena Google jarang mengubah kunci publiknya, Anda dapat meng-cache-nya menggunakan perintah cache dari respons HTTP dan, dalam sebagian besar kasus, melakukan validasi lokal secara lebih efisien daripada menggunakan endpoint tokeninfo
. Validasi ini memerlukan pengambilan dan penguraian sertifikat, serta melakukan panggilan kriptografis yang sesuai untuk memeriksa tanda tangan. Untungnya, ada library yang di-debug dengan baik yang tersedia dalam berbagai bahasa untuk melakukannya (lihat jwt.io).
Memperoleh informasi profil pengguna
Untuk mendapatkan informasi profil tambahan tentang pengguna, Anda dapat menggunakan token akses (yang diterima aplikasi Anda selama alur autentikasi) dan standar OpenID Connect:
Agar sesuai dengan OpenID, Anda harus menyertakan nilai cakupan
openid profile
di permintaan autentikasi.Jika ingin menyertakan alamat email pengguna, Anda dapat menentukan nilai cakupan tambahan
email
. Untuk menentukanprofile
danemail
, Anda dapat menyertakan parameter berikut dalam URI permintaan autentikasi:scope=openid%20profile%20email
- Tambahkan token akses ke header otorisasi dan buat permintaan
GET
HTTPS ke endpoint userinfo, yang harus Anda ambil dari dokumen Discovery menggunakan nilai metadatauserinfo_endpoint
. Respons userinfo mencakup informasi tentang pengguna, seperti yang dijelaskan dalamOpenID Connect Standard Claims
dan nilai metadataclaims_supported
dokumen Discovery. Pengguna atau organisasinya dapat memilih untuk menyediakan atau menahan kolom tertentu, sehingga Anda mungkin tidak mendapatkan informasi untuk setiap kolom untuk cakupan akses yang Anda otorisasi.
Dokumen Discovery
Protokol OpenID Connect mengharuskan penggunaan beberapa endpoint untuk mengautentikasi pengguna, dan untuk meminta resource, termasuk token, informasi pengguna, serta kunci publik.
Untuk menyederhanakan implementasi dan meningkatkan fleksibilitas, OpenID Connect memungkinkan penggunaan dokumen "Discovery," dokumen JSON yang ditemukan di lokasi terkenal yang berisi pasangan nilai kunci yang memberikan detail tentang konfigurasi penyedia OpenID Connect, termasuk URI otorisasi, token, pencabutan, userinfo, dan kunci publik. Dokumen Discovery untuk layanan OpenID Connect dari Google dapat diambil dari:
https://accounts.google.com/.well-known/openid-configuration
Untuk menggunakan layanan OpenID Connect Google, Anda harus melakukan hard code URI dokumen Discovery (https://accounts.google.com/.well-known/openid-configuration
) ke dalam aplikasi Anda.
Aplikasi Anda mengambil dokumen, menerapkan aturan caching dalam respons, lalu mengambil URI endpoint darinya sesuai kebutuhan. Misalnya, untuk mengautentikasi pengguna, kode Anda akan mengambil nilai metadata authorization_endpoint
(https://accounts.google.com/o/oauth2/v2/auth
dalam contoh di bawah) sebagai URI dasar untuk permintaan autentikasi yang dikirim ke Google.
Berikut adalah contoh dokumen tersebut; nama kolom adalah yang ditentukan dalam OpenID Connect Discovery 1.0 (lihat dokumen tersebut untuk mengetahui artinya). Nilainya hanyalah ilustrasi dan mungkin berubah, meskipun nilai tersebut disalin dari versi terbaru dokumen Google Discovery aktual:
{ "issuer": "https://accounts.google.com", "authorization_endpoint": "https://accounts.google.com/o/oauth2/v2/auth", "device_authorization_endpoint": "https://oauth2.googleapis.com/device/code", "token_endpoint": "https://oauth2.googleapis.com/token", "userinfo_endpoint": "https://openidconnect.googleapis.com/v1/userinfo", "revocation_endpoint": "https://oauth2.googleapis.com/revoke", "jwks_uri": "https://www.googleapis.com/oauth2/v3/certs", "response_types_supported": [ "code", "token", "id_token", "code token", "code id_token", "token id_token", "code token id_token", "none" ], "subject_types_supported": [ "public" ], "id_token_signing_alg_values_supported": [ "RS256" ], "scopes_supported": [ "openid", "email", "profile" ], "token_endpoint_auth_methods_supported": [ "client_secret_post", "client_secret_basic" ], "claims_supported": [ "aud", "email", "email_verified", "exp", "family_name", "given_name", "iat", "iss", "locale", "name", "picture", "sub" ], "code_challenge_methods_supported": [ "plain", "S256" ] }
Anda mungkin dapat menghindari HTTP bolak-balik dengan meng-cache nilai dari dokumen Discovery. Header caching HTTP standar digunakan dan harus dipatuhi.
Library klien
Library klien berikut mempermudah implementasi OAuth 2.0 dengan mengintegrasikan framework yang populer:
Kepatuhan OpenID Connect
Sistem autentikasi OAuth 2.0 Google mendukung fitur yang diperlukan dalam spesifikasi OpenID Connect Core. Klien apa pun yang didesain untuk bekerja dengan OpenID Connect harus beroperasi dengan layanan ini (dengan pengecualian OpenID Request Object).