OpenID Connect

OAuth 2.0 API Google dapat digunakan untuk autentikasi dan otorisasi. Dokumen ini menjelaskan implementasi OAuth 2.0 kami untuk autentikasi, yang sesuai dengan spesifikasi OpenID Connect, dan Bersertifikat OpenID. Dokumentasi yang ditemukan di 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 di Stack Overflow, beri tag pada pertanyaan Anda dengan 'google-oauth'.

Catatan: Untuk menyediakan tombol "Login dengan Google" di situs Anda, gunakan Google Identity Services, library klien login kami yang dibuat berdasarkan protokol OpenID Connect. Library ini menyediakan Token ID berformat OpenID Connect. Aplikasi Android harus menggunakan Credential Manager API untuk menerapkan alur Login dengan Google.

Menyiapkan OAuth 2.0

Sebelum aplikasi Anda dapat menggunakan sistem autentikasi OAuth 2.0 Google untuk login pengguna, Anda harus menyiapkan project di Konsol Google Cloud 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 Konsol Cloud untuk membuat akun layanan, mengaktifkan penagihan, menyiapkan pemfilteran, dan melakukan tugas lainnya. Untuk mengetahui detail selengkapnya, lihat Bantuan Konsol Google Cloud.

Mendapatkan kredensial OAuth 2.0

Anda memerlukan kredensial OAuth 2.0, termasuk client ID dan rahasia klien, untuk mengautentikasi pengguna dan mendapatkan akses ke Google API.

Untuk melihat client ID dan rahasia klien untuk kredensial OAuth 2.0 tertentu, klik teks berikut: Select credential. Di jendela yang terbuka, pilih project dan kredensial yang Anda inginkan, lalu klik View.

Atau, lihat client ID dan rahasia klien Anda dari halaman Clients di Konsol Cloud:

1. Buka halaman Klien.
2. Klik nama klien Anda atau ikon edit (). Client ID dan rahasia klien Anda berada di bagian atas halaman.

Menetapkan URI pengalihan

URI pengalihan yang Anda tetapkan di Konsol Cloud menentukan tempat Google mengirim respons ke permintaan autentikasi Anda.

Untuk membuat, melihat, atau mengedit URI pengalihan untuk kredensial OAuth 2.0 tertentu, lakukan hal berikut:

1. Buka halaman Klien.
2. Klik klien.
3. Lihat atau edit URI pengalihan.

Jika tidak ada klien yang tercantum di halaman Clients, berarti project Anda tidak memiliki kredensial OAuth. Untuk membuatnya, klik Buat klien.

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 login, pengguna mungkin diminta untuk memberi aplikasi Anda akses ke alamat email dan informasi akun dasar mereka. 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 Konsol Cloud.

Untuk mengaktifkan layar izin project Anda:

1. Buka halaman Branding di Konsol Google Cloud.
2. Jika diminta, pilih project, atau buat project baru.
3. Isi formulir lalu klik Simpan.

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 Konsol Cloud.)

Gambar 1. Screenshot halaman izin

Mengakses layanan

Google dan pihak ketiga menyediakan library yang dapat Anda gunakan untuk menangani banyak detail implementasi autentikasi pengguna dan mendapatkan akses ke Google API. Contohnya mencakup Google Identity Services dan library klien Google, yang tersedia untuk berbagai platform.

Catatan: Mengingat implikasi keamanan dari penerapan yang benar, sebaiknya Anda memanfaatkan library atau layanan yang telah ditulis sebelumnya. Mengautentikasi pengguna dengan benar penting untuk keselamatan dan keamanan mereka dan Anda, dan menggunakan kode yang telah di-debug dengan baik yang ditulis oleh orang lain umumnya merupakan praktik terbaik. Untuk mengetahui informasi selengkapnya, lihat Library klien.

Jika Anda memilih untuk tidak menggunakan library, ikuti petunjuk di bagian selanjutnya dalam dokumen ini, yang menjelaskan alur permintaan HTTP yang mendasari library yang tersedia.

Mengautentikasi pengguna

Mengautentikasi pengguna melibatkan proses mendapatkan token ID dan memvalidasinya. Token ID adalah fitur standar OpenID Connect yang dirancang untuk digunakan dalam berbagi 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 aplikasi memverifikasi identitas orang yang 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 menggunakan server backend-nya.

Dokumen ini menjelaskan cara menjalankan alur server untuk mengautentikasi pengguna. Alur implisit jauh lebih rumit karena risiko keamanan dalam menangani dan menggunakan token di sisi klien. Jika Anda perlu menerapkan alur implisit, sebaiknya gunakan Google Identity Services.

Alur server

Pastikan Anda menyiapkan aplikasi di Konsol Cloud agar dapat menggunakan protokol ini dan mengautentikasi pengguna. Saat pengguna mencoba login dengan Google, Anda harus:

1. Membuat token status anti-pemalsuan
2. Mengirim permintaan autentikasi ke Google
3. Mengonfirmasi token status anti-pemalsuan
4. Menukarkan code dengan token akses dan token ID
5. Mendapatkan informasi pengguna dari token ID
6. Mengautentikasi pengguna

1. Membuat token status antipemalsuan

Anda harus melindungi keamanan pengguna dengan mencegah serangan pemalsuan permintaan. Langkah pertama adalah membuat token sesi unik yang menyimpan status antara aplikasi Anda dan klien pengguna. Anda nantinya akan mencocokkan token sesi unik ini dengan respons autentikasi yang ditampilkan oleh layanan Login OAuth Google untuk memverifikasi bahwa pengguna yang membuat permintaan, 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 sekitar 30 karakter yang dibuat menggunakan generator angka acak berkualitas tinggi. Cara lainnya adalah hash yang dihasilkan dengan menandatangani beberapa variabel status sesi Anda dengan kunci yang dirahasiakan di backend Anda.

Kode berikut menunjukkan cara membuat 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 untuk 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. Mengirim permintaan autentikasi ke Google

Langkah berikutnya adalah membuat permintaan GET HTTPS dengan parameter URI yang sesuai. Perhatikan penggunaan HTTPS, bukan HTTP, di semua langkah proses ini; koneksi HTTP ditolak. Anda harus mengambil URI dasar dari dokumen Discovery menggunakan nilai metadata authorization_endpoint. Pembahasan berikut mengasumsikan URI dasar adalah https://accounts.google.com/o/oauth2/v2/auth.

Untuk permintaan dasar, tentukan parameter berikut:

• client_id, yang Anda dapatkan dari halaman Klien Konsol Cloud.
• response_type, yang dalam permintaan alur kode otorisasi dasar harus berupa code. (Baca selengkapnya di response_type.)
• scope, yang dalam permintaan dasar harus berupa openid email. (Baca selengkapnya di scope.)
• redirect_uri harus berupa endpoint HTTP di server Anda yang akan menerima respons dari Google. Nilai harus sama persis dengan salah satu URI pengalihan yang diizinkan untuk klien OAuth 2.0, yang Anda konfigurasi di halaman Kredensial Konsol Cloud. Jika nilai ini tidak cocok dengan URI yang diizinkan, permintaan akan gagal dengan error redirect_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 di state.)
• nonce adalah nilai acak yang dihasilkan oleh aplikasi Anda yang mengaktifkan perlindungan replay jika ada.
• login_hint dapat berupa alamat email pengguna atau string sub, yang setara dengan ID Google pengguna. Jika Anda tidak memberikan login_hint dan pengguna login, layar izin akan menyertakan permintaan persetujuan untuk merilis alamat email pengguna ke aplikasi Anda. (Baca selengkapnya di login_hint.)
• Gunakan parameter hd untuk mengoptimalkan alur OpenID Connect bagi pengguna domain tertentu yang terkait dengan organisasi Google Workspace atau Cloud (baca selengkapnya di hd).
Catatan: Berikut adalah beberapa parameter yang paling umum digunakan. Untuk mengetahui daftar lengkap, serta detail selengkapnya tentang semua parameter, lihat Parameter URI autentikasi.

Berikut adalah contoh URI autentikasi OpenID Connect lengkap, dengan baris baru dan spasi agar lebih mudah dibaca:

https://accounts.google.com/o/oauth2/v2/auth?
 response_type=code&
 client_id=424911365001.apps.googleusercontent.com&
 scope=openid%20email&
 redirect_uri=https%3A//developers.google.com/oauthplayground&
 state=security_token%3D138r5719ru3e1%26url%3Dhttps%3A%2F%2Foauth2-login-demo.example.com%2FmyHome&
 login_hint=[e-mail]&
 nonce=0394852-3190485-2490358&
 hd=example.com

Pengguna harus memberikan izin jika aplikasi Anda meminta informasi baru tentang mereka, atau jika aplikasi Anda meminta akses akun yang belum pernah mereka setujui sebelumnya.

3. Mengonfirmasi token status anti-pemalsuan

Respons dikirim ke redirect_uri yang Anda tentukan dalam permintaan. Semua respons ditampilkan dalam string kueri:

https://developers.google.com/oauthplayground?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

Sesuai dengan RFC 6749, klien HARUS mengabaikan parameter respons yang tidak dikenali. Di server, Anda harus mengonfirmasi bahwa state yang diterima dari Google cocok dengan token sesi yang Anda buat di Langkah 1. Verifikasi bolak-balik ini membantu memverifikasi bahwa pengguna, bukan skrip berbahaya, yang membuat permintaan.

Kode berikut menunjukkan cara mengonfirmasi 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 untuk 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. Menukarkan code dengan token akses dan token ID

Responsnya mencakup parameter code, kode otorisasi satu kali 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. Pembahasan berikut mengasumsikan endpoint-nya 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 peroleh dari halaman Klien Konsol Cloud, seperti yang dijelaskan dalam Mendapatkan kredensial OAuth 2.0.
client_secret	Rahasia klien yang Anda peroleh dari halaman Klien Konsol Cloud, seperti yang dijelaskan dalam Mendapatkan kredensial OAuth 2.0.
redirect_uri	URI pengalihan yang diotorisasi untuk client_id tertentu yang ditentukan di halaman Klien Konsol Cloud, seperti yang dijelaskan dalam Menetapkan URI pengalihan.
grant_type	Kolom ini harus berisi nilai authorization_code, seperti yang ditentukan 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//developers.google.com/oauthplayground&
grant_type=authorization_code

Respons yang berhasil untuk permintaan ini berisi kolom berikut dalam array JSON:

Kolom
access_token	Token yang dapat dikirim ke Google API.
expires_in	Sisa masa aktif token akses dalam detik.
id_token	JWT yang berisi informasi identitas tentang pengguna yang ditandatangani secara digital oleh Google.
scope	Cakupan akses yang diberikan oleh access_token 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 access_type ditetapkan ke offline dalam permintaan autentikasi. Untuk mengetahui detailnya, lihat Token refresh.

Catatan: Ada batas jumlah token per akun pengguna Google, dan setiap permintaan autentikasi yang melebihi batas ini dapat secara diam-diam membatalkan token refresh yang belum digunakan. Untuk mengetahui detailnya, lihat Masa berlaku token.

5. Mendapatkan 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 tanpa perantara dan menggunakan rahasia klien untuk mengautentikasi diri Anda ke Google, Anda dapat yakin bahwa token yang Anda terima benar-benar berasal dari Google dan valid. Jika server Anda meneruskan token ID ke komponen lain dari aplikasi Anda, sangat penting bagi komponen lain tersebut untuk memvalidasi token sebelum menggunakannya.

Karena sebagian besar library API menggabungkan validasi dengan pekerjaan mendekode nilai berenkode base64url dan mengurai JSON di dalamnya, Anda mungkin akan tetap memvalidasi token saat mengakses klaim dalam token ID.

Payload token ID

Token ID adalah objek JSON yang berisi kumpulan pasangan nama/nilai. Berikut adalah contoh, yang diformat agar 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": "[e-mail]",
  "email_verified": "true",
  "iat": 1353601026,
  "exp": 1353604926,
  "nonce": "0394852-3190485-2490358"
}

Peringatan: Saat menerapkan sistem pengelolaan akun, Anda tidak boleh menggunakan kolom email di token ID sebagai ID unik untuk pengguna. Selalu gunakan kolom sub karena kolom ini unik untuk Akun Google, meskipun pengguna mengubah alamat emailnya.

Token ID Google dapat berisi kolom berikut (dikenal sebagai klaim):

Klaim	Tersedia	Deskripsi
aud	selalu	Audiens yang dituju oleh token ID ini. ID ini harus merupakan salah satu client ID OAuth 2.0 aplikasi Anda.
exp	selalu	Waktu habis masa berlaku saat atau setelah token ID tidak boleh diterima. Direpresentasikan dalam waktu epoch Unix (detik bilangan bulat).
iat	selalu	Waktu penerbitan token ID. Direpresentasikan dalam waktu epoch Unix (detik bilangan bulat).
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 peka huruf besar/kecil.
amr		Array string JSON yang mengidentifikasi metode autentikasi yang digunakan untuk login ke Akun Google. Jika ada, menyertakan satu atau beberapa kemungkinan nilai [IANA.AMR] berikut: hwk kunci hardware digunakan mfa Autentikasi multi-faktor telah selesai pwd Sandi telah digunakan sms pesan SMS digunakan untuk verifikasi swk Kunci software seperti Kunci sandi telah digunakan tel panggilan telepon digunakan untuk verifikasi Hanya ada jika klaim amr disertakan dalam permintaan autentikasi dan diaktifkan di setelan.
auth_time		Waktu autentikasi pengguna dilakukan, angka JSON yang mewakili jumlah detik yang telah berlalu sejak epoch Unix (1 Januari 1970, 00.00.00 UTC). Diberikan saat klaim auth_time disertakan dalam permintaan autentikasi dan diaktifkan di setelan.
at_hash		Hash token akses. Memberikan validasi bahwa token akses terkait dengan token identitas. Jika token ID dikeluarkan 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, Anda tidak perlu memverifikasi token akses.
azp		client_id presenter yang diizinkan. Klaim ini hanya diperlukan jika pihak yang meminta token ID tidak sama dengan audiens token ID. Hal ini mungkin terjadi di Google untuk aplikasi hybrid, yaitu saat aplikasi web dan aplikasi Android memiliki client_id OAuth 2.0 yang berbeda, tetapi menggunakan project Google API yang sama.
email		Alamat email pengguna. Hanya diberikan jika Anda menyertakan cakupan email dalam permintaan Anda. Nilai klaim ini mungkin tidak unik untuk akun ini dan dapat berubah seiring waktu. Oleh karena itu, Anda tidak boleh menggunakan nilai ini sebagai ID utama untuk ditautkan ke data pengguna Anda. Anda juga tidak dapat mengandalkan domain klaim email untuk mengidentifikasi pengguna organisasi Google Workspace atau Cloud; gunakan klaim hd sebagai gantinya. Peringatan: Jangan gunakan kolom email sebagai ID unik untuk pengguna. Selalu gunakan kolom sub.
email_verified		True jika alamat email pengguna telah diverifikasi; jika tidak, false.
family_name		Nama keluarga atau nama belakang pengguna. Dapat diberikan jika ada klaim name.
given_name		Nama depan pengguna. Dapat diberikan jika ada klaim name.
hd		Domain yang terkait dengan organisasi Google Workspace atau Cloud pengguna. Hanya diberikan jika pengguna termasuk dalam organisasi Google Cloud. Anda harus memeriksa klaim ini saat membatasi akses ke resource hanya untuk anggota domain tertentu. Tidak adanya klaim ini menunjukkan bahwa akun tersebut bukan milik domain yang dihosting Google.
locale		Lokalitas pengguna, yang diwakili oleh tag bahasa BCP 47. Dapat diberikan jika klaim name ada.
name		Nama lengkap pengguna, dalam bentuk yang dapat ditampilkan. Dapat diberikan jika: Cakupan permintaan menyertakan string "profile" Token ID ditampilkan dari refresh token Jika klaim name ada, Anda dapat menggunakannya untuk memperbarui data pengguna aplikasi. Perhatikan bahwa klaim ini tidak pernah dijamin akan ada.
nonce		Nilai nonce yang diberikan oleh aplikasi Anda dalam permintaan autentikasi. Anda harus melindungi dari serangan replay dengan menampilkan nilai ini hanya sekali.
picture		URL foto profil pengguna. Dapat diberikan jika: Cakupan permintaan menyertakan string "profile" Token ID ditampilkan dari refresh token Jika klaim picture ada, Anda dapat menggunakannya untuk memperbarui data pengguna aplikasi Anda. Perhatikan bahwa klaim ini tidak pernah dijamin akan ada.
profile		URL halaman profil pengguna. Dapat diberikan jika: Cakupan permintaan menyertakan string "profile" Token ID ditampilkan dari refresh token Jika klaim profile ada, Anda dapat menggunakannya untuk memperbarui data pengguna aplikasi Anda. Perhatikan bahwa klaim ini tidak pernah dijamin akan ada.

6. Mengautentikasi pengguna

Setelah mendapatkan informasi pengguna dari token ID, Anda harus mengkueri database pengguna aplikasi Anda. Jika pengguna sudah ada di 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 mungkin dapat mengisi otomatis banyak kolom yang Anda perlukan di 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 dengan persyaratan lanjutan seputar autentikasi dan otorisasi.

Akses ke Google API lainnya

Salah satu keuntungan menggunakan OAuth 2.0 untuk autentikasi adalah aplikasi Anda bisa mendapatkan izin untuk menggunakan Google API lainnya atas nama pengguna (seperti YouTube, Google Drive, Kalender, atau Kontak) pada saat yang sama 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 akan diminta dengan tepat di layar izin. Token akses yang Anda terima kembali dari Google akan memungkinkan aplikasi Anda mengakses semua API yang terkait dengan cakupan akses yang Anda minta dan diberikan.

Catatan: Jika aplikasi Anda meminta banyak cakupan, layar izin akan berisi banyak baris teks. Makin banyak cakupan yang diminta aplikasi Anda, makin kecil kemungkinan pengguna akan memberikan izin, sehingga aplikasi Anda hanya boleh meminta cakupan yang diperlukan.

Token refresh

Dalam permintaan akses API, Anda dapat meminta token refresh untuk ditampilkan selama pertukaran code. Token refresh memberi aplikasi Anda akses berkelanjutan ke Google API saat pengguna tidak ada di aplikasi Anda. Untuk meminta token refresh, tambahkan setel parameter access_type ke offline dalam permintaan autentikasi Anda.

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 batas per pengguna di semua klien. Jika aplikasi Anda meminta terlalu banyak token refresh, aplikasi tersebut mungkin akan mencapai batas ini, sehingga token refresh yang lebih lama akan berhenti berfungsi.

Untuk mengetahui informasi selengkapnya, lihat Memperbarui token akses (akses offline).

Meminta izin ulang

Anda dapat meminta pengguna untuk memberikan otorisasi ulang pada aplikasi Anda dengan menetapkan parameter prompt ke consent dalam permintaan autentikasi Anda. Jika prompt=consent disertakan, layar izin akan ditampilkan setiap kali aplikasi Anda meminta otorisasi cakupan akses, meskipun semua cakupan sebelumnya telah diberikan ke project Google API Anda. Oleh karena itu, 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	Wajib	Deskripsi
client_id	(Wajib diisi)	String client ID yang Anda peroleh dari halaman Klien Konsol Cloud, seperti yang dijelaskan dalam Mendapatkan kredensial OAuth 2.0.
nonce	(Wajib diisi)	Nilai acak yang dihasilkan oleh aplikasi Anda yang mengaktifkan perlindungan replay.
response_type	(Wajib diisi)	Jika nilainya adalah code, meluncurkan Alur kode otorisasi dasar, yang memerlukan POST ke endpoint token untuk mendapatkan token. Jika nilainya adalah token id_token atau id_token token, meluncurkan Alur implisit, yang memerlukan penggunaan JavaScript di URI pengalihan untuk mengambil token dari ID #fragment URI.
redirect_uri	(Wajib diisi)	Menentukan tujuan pengiriman respons. Nilai parameter ini harus sama persis dengan salah satu nilai pengalihan yang diizinkan yang Anda tetapkan di halaman Klien Konsol Cloud (termasuk skema HTTP atau HTTPS, huruf besar/kecil, dan '/' di akhir, jika ada).
scope	(Wajib diisi)	Parameter cakupan harus diawali dengan nilai openid, lalu menyertakan nilai profile, nilai email, atau keduanya. Jika nilai cakupan profile ada, token ID mungkin (tetapi tidak dijamin) menyertakan klaim profile default pengguna. Jika nilai cakupan email ada, token ID akan menyertakan klaim email dan email_verified. Selain cakupan khusus OpenID ini, argumen cakupan Anda juga dapat menyertakan nilai cakupan lainnya. Semua nilai cakupan harus dipisahkan dengan spasi. Misalnya, jika Anda menginginkan akses per file ke Google Drive pengguna, parameter cakupan Anda mungkin adalah openid profile email https://www.googleapis.com/auth/drive.file. Untuk mengetahui 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 di-round-trip dalam protokol; artinya, string ini ditampilkan sebagai parameter URI dalam alur Dasar, dan dalam ID #fragment URI dalam alur Implisit. state dapat berguna untuk menghubungkan permintaan dan respons. Karena redirect_uri Anda dapat ditebak, penggunaan nilai state dapat meningkatkan jaminan bahwa koneksi masuk adalah hasil dari permintaan autentikasi yang dimulai oleh aplikasi Anda. Jika Anda membuat string acak atau mengenkode hash dari beberapa status klien (misalnya, cookie) dalam variabel state ini, Anda dapat memvalidasi respons untuk memverifikasi bahwa permintaan dan respons berasal dari browser yang sama. Hal ini memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs.
access_type	(Opsional)	Nilai yang diizinkan adalah offline dan online. Efeknya didokumentasikan dalam Akses Offline; jika token akses sedang diminta, klien tidak akan menerima token refresh kecuali jika nilai offline ditentukan.
claims	(Opsional)	Parameter klaim digunakan untuk menentukan satu atau beberapa bidang opsional yang akan disertakan dalam endpoint userinfo atau jenis respons token ID permintaan autentikasi. Nilainya adalah objek JSON yang berisi jenis respons dan klaim yang diminta. Permintaan klaim berikut diterima oleh server Google: Permintaan klaim amr Minta metode yang digunakan saat pengguna terakhir kali diautentikasi. Untuk menampilkan amr sebagai kolom dalam respons token ID, sertakan parameter permintaan claims: claims={"id_token":{"amr":{"essential":true}}} Harus diaktifkan di setelan. auth_time Minta waktu saat pengguna terakhir kali diautentikasi. Untuk menampilkan auth_time sebagai kolom dalam respons token ID, sertakan parameter permintaan claims: claims={"id_token":{"auth_time":{"essential":true}}} Harus diaktifkan di setelan.
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 perilaku alur protokol: page, popup, touch, dan wap.
hd	(Opsional)	Menyederhanakan proses login untuk akun yang dimiliki oleh 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 (*): hd=*. Jangan mengandalkan 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 hd yang sesuai dengan yang Anda harapkan (misalnya, mycolledge.edu). Tidak seperti parameter permintaan, klaim hd token ID terdapat dalam token keamanan dari Google, sehingga nilainya dapat dipercaya.
include_granted_scopes	(Opsional)	Jika parameter ini diberikan dengan nilai true, dan permintaan otorisasi diberikan, otorisasi akan menyertakan otorisasi sebelumnya yang diberikan kepada kombinasi pengguna/aplikasi ini untuk cakupan lain; lihat Otorisasi inkremental. Perhatikan bahwa Anda tidak dapat melakukan otorisasi inkremental dengan alur Aplikasi Terinstal.
login_hint	(Opsional)	Saat aplikasi Anda mengetahui pengguna yang ingin diautentikasi, aplikasi dapat memberikan parameter ini sebagai petunjuk ke server autentikasi. Dengan meneruskan petunjuk ini, pemilih akun akan ditiadakan dan kotak email pada formulir login akan diisi otomatis, atau sesi yang tepat akan dipilih (jika pengguna menggunakan multi-login), yang dapat membantu Anda menghindari masalah yang terjadi jika aplikasi Anda 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 melakukan autentikasi ulang dan memberikan izin. Nilai yang memungkinkan adalah: none Server otorisasi tidak menampilkan layar autentikasi atau izin pengguna; server akan menampilkan error jika pengguna belum diautentikasi dan belum mengonfigurasi izin untuk cakupan yang diminta. Anda dapat menggunakan none untuk memeriksa autentikasi dan/atau izin yang ada. consent Server otorisasi meminta izin pengguna sebelum menampilkan informasi kepada klien. select_account Server otorisasi meminta pengguna untuk memilih akun pengguna. Hal ini memungkinkan pengguna yang memiliki beberapa akun di server otorisasi untuk memilih di antara beberapa akun yang mungkin memiliki sesi aktif. Jika tidak ada nilai yang ditentukan dan pengguna belum pernah mengizinkan akses, pengguna akan melihat layar izin.
hl	(Opsional)	Tag bahasa BCP 47 yang digunakan untuk menentukan bahasa tampilan untuk layar login, pemilih akun, dan izin. Jika parameter ini tidak diberikan, bahasa akan ditetapkan secara default ke setelan Akun Google atau browser pengguna. Misalnya, untuk meminta UI dalam bahasa Inggris British, tetapkan parameter ke en-GB.

Memvalidasi token ID

Anda harus memvalidasi semua token ID di server Anda, kecuali jika Anda tahu bahwa token tersebut berasal langsung dari Google. Misalnya, server Anda harus memverifikasi keaslian token ID yang diterima dari aplikasi klien Anda.

Berikut adalah situasi umum saat Anda mungkin 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 yang diberi token ID tersebut.

Token ID bersifat sensitif dan dapat disalahgunakan jika disadap. Anda harus memastikan bahwa token ini ditangani dengan aman dengan mengirimkannya hanya melalui HTTPS dan hanya menggunakan data POST atau dalam header permintaan. Jika Anda menyimpan token ID di server, Anda juga harus menyimpannya dengan aman.

Salah satu hal yang membuat token ID berguna adalah fakta bahwa Anda dapat meneruskannya ke berbagai komponen aplikasi. Komponen ini dapat menggunakan token ID sebagai mekanisme autentikasi ringan yang mengautentikasi aplikasi dan pengguna. Namun, sebelum Anda dapat menggunakan informasi dalam token ID atau mengandalkannya sebagai pernyataan bahwa pengguna telah melakukan autentikasi, Anda harus memvalidasinya.

Validasi token ID memerlukan beberapa langkah:

1. Pastikan token ID ditandatangani dengan benar oleh penerbit. Token yang dikeluarkan Google ditandatangani menggunakan salah satu sertifikat yang ditemukan di URI yang ditentukan dalam nilai metadata jwks_uri dari dokumen discovery.
2. Pastikan nilai klaim iss dalam token ID sama dengan https://accounts.google.com atau accounts.google.com.
3. Pastikan nilai klaim aud dalam token ID sama dengan client ID aplikasi Anda.
4. Pastikan expiry time (klaim exp) token ID belum berlalu.
5. 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 menjelaskannya secara mendetail di sini.

Langkah pertama lebih kompleks, dan melibatkan pemeriksaan tanda tangan kriptografis. Untuk tujuan proses debug, Anda dapat menggunakan endpoint tokeninfo Google untuk membandingkan dengan pemrosesan lokal yang diterapkan di server atau perangkat Anda. Misalkan nilai token ID Anda adalah XYZ123. Kemudian, Anda akan mendereferensikan URI https://oauth2.googleapis.com/tokeninfo?id_token=XYZ123. Jika tanda tangan token valid, responsnya akan berupa 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 discovery menggunakan nilai metadata jwks_uri. Permintaan ke endpoint proses debug mungkin dibatasi atau mengalami error yang terjadi sesekali.

Karena Google jarang mengubah kunci publiknya, Anda dapat meng-cache kunci tersebut menggunakan perintah cache dari respons HTTP dan, dalam sebagian besar kasus, melakukan validasi lokal dengan jauh 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 telah di-debug dengan baik dan tersedia dalam berbagai bahasa untuk melakukannya (lihat jwt.io).

Mendapatkan 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:

1. Agar mematuhi OpenID, Anda harus menyertakan nilai cakupan openid profile dalam permintaan autentikasi.

   Jika Anda ingin alamat email pengguna disertakan, Anda dapat menentukan nilai cakupan tambahan email. Untuk menentukan profile dan email, Anda dapat menyertakan parameter berikut dalam URI permintaan autentikasi:

   scope=openid%20profile%20email

2. Tambahkan token akses Anda ke header otorisasi dan buat permintaan GET HTTPS ke endpoint userinfo, yang harus Anda ambil dari Dokumen discovery menggunakan nilai metadata userinfo_endpoint. Respons userinfo mencakup informasi tentang pengguna, seperti yang dijelaskan dalam OpenID Connect Standard Claims dan nilai metadata claims_supported dari dokumen Discovery. Pengguna atau organisasi mereka dapat memilih untuk memberikan atau menyembunyikan kolom tertentu, sehingga Anda mungkin tidak mendapatkan informasi untuk setiap kolom untuk cakupan akses yang diizinkan.

Dokumen Discovery

Protokol OpenID Connect memerlukan penggunaan beberapa endpoint untuk mengautentikasi pengguna, dan untuk meminta resource termasuk token, informasi pengguna, dan kunci publik.

Untuk menyederhanakan implementasi dan meningkatkan fleksibilitas, OpenID Connect memungkinkan penggunaan "Dokumen discovery", yaitu dokumen JSON yang ditemukan di lokasi umum yang berisi pasangan nilai kunci yang memberikan detail tentang konfigurasi penyedia OpenID Connect, termasuk URI endpoint otorisasi, token, pencabutan, info pengguna, dan kunci publik. Dokumen Discovery untuk layanan OpenID Connect 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 dari dokumen tersebut 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 nama yang ditentukan dalam OpenID Connect Discovery 1.0 (lihat dokumen tersebut untuk mengetahui artinya). Nilai-nilai ini murni ilustratif dan dapat berubah, meskipun disalin dari versi terbaru dokumen Google Discovery yang sebenarnya:

{
  "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 perjalanan bolak-balik HTTP dengan meng-cache nilai dari dokumen Discovery. Header caching HTTP standar digunakan dan harus dipatuhi.

Library klien

Library klien berikut mempermudah penerapan OAuth 2.0 dengan mengintegrasikannya dengan framework populer:

• Library Klien Google API untuk Java
• Library Klien Google API untuk Python
• Library Klien Google API untuk .NET
• Library Klien Google API untuk Ruby
• Library Klien Google API untuk PHP
• Library OAuth 2.0 untuk Google Web Toolkit
• Google Toolbox for Mac OAuth 2.0 Controllers

Kepatuhan OpenID Connect

Sistem autentikasi OAuth 2.0 Google mendukung fitur yang diperlukan dari spesifikasi OpenID Connect Core. Setiap klien yang dirancang untuk berfungsi dengan OpenID Connect harus beroperasi dengan layanan ini (dengan pengecualian Objek Permintaan OpenID).