OpenID Connect

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 Tersertifikasi OpenID. Dokumentasi yang terdapat dalam Menggunakan OAuth 2.0 untuk Mengakses Google API juga berlaku untuk layanan ini. Jika Anda ingin mempelajari protokol ini secara interaktif, sebaiknya Google OAuth 2.0 Playground. Untuk mendapatkan bantuan terkait Stack Overflow, beri tag pertanyaan Anda dengan 'google-oauth'.

Menyiapkan OAuth 2.0

Sebelum aplikasi Anda dapat menggunakan sistem autentikasi OAuth 2.0 dari Google untuk login pengguna, Anda harus menyiapkan project di Google API Console untuk mendapatkan kredensial OAuth 2.0, menetapkan URI pengalihan, dan (secara 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 BantuanGoogle 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 :

  1. Go to the Credentials page.
  2. Klik nama kredensial Anda atau ikon pensil ( ). ID dan rahasia klien Anda ada di bagian atas halaman.

Menyetel URI pengalihan

URI pengalihan yang Anda tetapkan di API Console menentukan tempat Google mengirimkan respons ke permintaan autentikasi.

Untuk membuat, melihat, atau mengedit URI redirect untuk kredensial OAuth 2.0 yang diberikan, lakukan hal berikut:

  1. Go to the Credentials page.
  2. Di bagian OAuth 2.0 klien ID halaman, klik kredensial.
  3. 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

Untuk pengguna Anda, pengalaman autentikasi OAuth 2.0 menyertakan 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 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 mengontrol informasi branding di API Console.

Untuk mengaktifkan layar persetujuan proyek Anda:

  1. Buka Consent Screen page di Google API Console .
  2. If prompted, select a project, or create a new one.
  3. Isi formulir dan klik Simpan .

Dialog izin berikut menampilkan 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 disetel di API Console.)

Screenshot halaman izin

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 Login dengan Google dan library klien Google, yang tersedia untuk berbagai platform.

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

Mengautentikasi pengguna

Untuk mengautentikasi, pengguna harus 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 memperoleh token ID disebut alur "server" dan alur "implisit". Alur server memungkinkan server backend aplikasi untuk memverifikasi identitas pengguna yang menggunakan browser atau perangkat seluler. Alur implisit digunakan jika 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 melakukan alur server untuk mengautentikasi pengguna. Alur implisit secara signifikan lebih rumit karena risiko keamanan dalam menangani dan menggunakan token di sisi klien. Jika perlu menerapkan alur implisit, kami sangat merekomendasikan penggunaan Login dengan Google.

Alur server

Pastikan Anda menyiapkan aplikasi di API Console agar dapat menggunakan protokol ini dan mengautentikasi pengguna. Saat pengguna mencoba login dengan Google, Anda perlu:

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

1. Membuat token status anti-pemalsuan

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. Kemudian, Anda akan mencocokkan token sesi unik ini dengan respons autentikasi yang ditampilkan oleh layanan Login Google OAuth untuk memverifikasi bahwa pengguna membuat permintaan tersebut 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 karakter atau lebih yang dibuat menggunakan generator angka acak berkualitas tinggi. Cara lainnya adalah hash yang dihasilkan dengan menandatangani beberapa variabel status sesi dengan kunci yang dirahasiakan pada back-end Anda.

Kode berikut menunjukkan pembuatan token sesi 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 agar dapat 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 selanjutnya 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 bahwa 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 code. (Baca selengkapnya di response_type.)
  • scope, yang dalam permintaan dasar harus openid email. (Baca selengkapnya di scope.)
  • redirect_uri harus menjadi endpoint HTTP di server Anda yang akan menerima respons dari Google. Nilai harus sama persis dengan salah satu URI pengalihan resmi untuk klien OAuth 2.0, yang Anda konfigurasikan di API ConsoleCredentials page. Jika nilai ini tidak cocok dengan URI yang diberi otorisasi, 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 dibuat oleh aplikasi Anda yang memungkinkan perlindungan replay ketika 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 saat ini sudah 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 Cloud. (Baca selengkapnya di hd.)

Berikut adalah contoh URI autentikasi OpenID Connect yang lengkap, dengan jeda baris dan spasi agar 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//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 harus 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

Respons dikirim ke redirect_uri yang Anda tentukan dalam permintaan. Semua respons ditampilkan dalam string kueri, seperti ditunjukkan di bawah ini:

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 bolak-balik ini membantu memastikan bahwa penggunalah yang membuat permintaan, 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 agar dapat 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 tersebut mencakup parameter code, kode otorisasi satu kali yang dapat ditukarkan oleh server Anda untuk 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 bahwa endpoint-nya adalah https://oauth2.googleapis.com/token. Permintaan tersebut 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 peroleh dari API Console Credentials page, seperti 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 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//oauth2.example.com/code&
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 pakai 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 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.

5. Memperoleh informasi pengguna dari token ID

Token ID adalah JWT (Token Web JSON), yaitu objek JSON berenkode Base64 yang ditandatangani secara kriptografis. Biasanya, sangat penting bagi Anda untuk memvalidasi token ID sebelum menggunakannya, tetapi karena Anda berkomunikasi langsung dengan Google melalui saluran HTTPS bebas perantara dan menggunakan rahasia klien untuk mengautentikasi Anda ke Google, Anda dapat merasa yakin bahwa token yang Anda terima benar-benar berasal dari Google dan valid. Jika server meneruskan token ID ke komponen lain pada aplikasi Anda, sangat penting bagi komponen lain 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 ini contohnya, 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": "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 ditujukan untuk token ID ini. 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 diterima. Ditunjukkan dalam waktu Unix (integer detik).
iat selalu Waktu token ID dikeluarkan. Diwakili dalam waktu Unix (integer 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-beda, tetapi nilai sub tidak pernah diubah. 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 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 Anda tidak perlu memverifikasi token akses jika mengikuti Langkah 1 dan Langkah 3.
azp client_id presenter yang diotorisasi. Klaim ini hanya diperlukan jika pihak yang meminta token ID tidak sama dengan audiens token ID. Hal ini dapat dilakukan di Google untuk aplikasi campuran yang aplikasi webnya 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, salah.
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 Google Cloud pengguna. Disediakan hanya jika pengguna adalah anggota organisasi Google Cloud.
locale Lokal pengguna, yang diwakili oleh tag bahasa BCP 47. Dapat diberikan jika ada klaim name.
name Nama lengkap pengguna, dalam bentuk yang dapat ditampilkan. Mungkin akan diberikan jika:
  • Cakupan permintaan mencakup string "profile"
  • Token ID ditampilkan dari pembaruan token

Jika klaim name ada, Anda dapat menggunakannya untuk memperbarui data pengguna aplikasi Anda. Perlu diperhatikan bahwa klaim ini tidak pernah dijamin akan ada.

nonce Nilai nonce yang diberikan oleh aplikasi Anda dalam permintaan autentikasi. Anda harus menerapkan perlindungan terhadap serangan replay dengan memastikannya hanya ditampilkan sekali.
picture URL foto profil pengguna. Mungkin akan diberikan jika:
  • Cakupan permintaan mencakup string "profile"
  • Token ID ditampilkan dari pembaruan token

Jika klaim picture ada, Anda dapat menggunakannya untuk memperbarui data pengguna aplikasi Anda. Perlu diperhatikan bahwa klaim ini tidak pernah dijamin akan ada.

profile URL halaman profil pengguna. Mungkin akan diberikan jika:
  • Cakupan permintaan mencakup string "profile"
  • Token ID ditampilkan dari pembaruan token

Jika klaim profile ada, Anda dapat menggunakannya untuk memperbarui data pengguna aplikasi Anda. Perlu diperhatikan bahwa klaim ini tidak pernah dijamin akan ada.

6. Mengautentikasi pengguna

Setelah memperoleh informasi pengguna dari token ID, Anda harus mengueri database pengguna aplikasi Anda. Jika pengguna sudah ada dalam database Anda, 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 diterima dari Google, atau setidaknya Anda dapat mengisi otomatis banyak kolom yang Anda wajibkan di formulir pendaftaran. Selain informasi dalam token ID, Anda juga dapat memperoleh informasi profil pengguna tambahan di endpoint profil pengguna kami.

Topik lanjutan

Bagian berikut menjelaskan API Google OAuth 2.0 secara lebih mendetail. Informasi ini ditujukan bagi developer yang memiliki persyaratan lanjutan terkait 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 butuhkan dalam permintaan autentikasi yang Anda kirim ke Google. Misalnya, untuk menambahkan kelompok usia pengguna ke permintaan autentikasi Anda, teruskan parameter cakupan openid email https://www.googleapis.com/auth/profile.agerange.read. Pengguna akan diminta diminta dengan tepat di 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.

Refresh token

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. Untuk meminta token refresh, tambahkan parameter access_type ke offline dalam permintaan autentikasi Anda.

Pertimbangan:

  • Pastikan Anda menyimpan token refresh dengan aman dan permanen, karena Anda hanya dapat memperoleh token refresh saat pertama kali melakukan alur pertukaran kode.
  • Ada batas jumlah token refresh yang dikeluarkan: satu batas per kombinasi klien/pengguna, dan satu lagi per pengguna di seluruh klien. Jika meminta terlalu banyak token refresh, aplikasi Anda mungkin akan mencapai batas tersebut. Jika demikian, token refresh yang lama akan berhenti berfungsi.

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

Anda dapat meminta pengguna untuk mengotorisasi 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 saat diperlukan.

Untuk 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 API Console Credentials page, seperti yang dijelaskan dalam Mendapatkan kredensial OAuth 2.0.
nonce (Wajib diisi) Nilai acak yang dibuat oleh aplikasi Anda yang memungkinkan perlindungan replay.
response_type (Wajib diisi) Jika nilainya adalah code, luncurkan Alur kode otorisasi dasar, yang mengharuskan POST ke endpoint token untuk mendapatkan token. Jika nilainya adalah token id_token atau id_token token, akan meluncurkan alur Implisit, yang mengharuskan penggunaan JavaScript pada 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 diotorisasi yang Anda tetapkan di API ConsoleCredentials page (termasuk skema HTTP atau HTTPS, kasus, dan akhiran &33;/', jika ada).
scope (Wajib diisi)

Parameter cakupan harus dimulai dengan nilai openid, lalu menyertakan nilai profile, nilai email, atau keduanya.

Jika terdapat nilai cakupan profile, token ID mungkin (tetapi tidak dijamin) menyertakan klaim profile default pengguna.

Jika terdapat nilai cakupan email, token ID mencakup 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 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 bolak-balik dalam protokol; artinya, metode tersebut 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 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 beberapa status klien (misalnya, cookie) dalam variabel state ini, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama. Tindakan ini memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs.

access_type (Opsional) Nilai yang diizinkan adalah offline dan online. Efek didokumentasikan dalam Akses Offline; jika token akses diminta, klien tidak akan menerima token refresh kecuali 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 memengaruhi perilakunya: page, popup, touch, dan wap.
hd (Opsional)

Sederhanakan 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 cocok dengan yang Anda harapkan (misalnya mycolledge.edu). Tidak seperti parameter permintaan, klaim token ID hd 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 ke kombinasi pengguna/aplikasi ini untuk cakupan lainnya; lihat Otorisasi inkremental.

Perlu diperhatikan bahwa Anda tidak dapat melakukan otorisasi inkremental dengan alur Aplikasi Terinstal.

login_hint (Opsional) Saat mengetahui pengguna yang ingin diautentikasi, aplikasi Anda dapat memberikan parameter ini sebagai petunjuk ke server autentikasi. Meneruskan petunjuk ini akan menekan pemilih akun dan mengisi kotak email terlebih dahulu pada formulir login, atau memilih sesi yang tepat (jika pengguna menggunakan fitur 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. Kemungkinan nilainya adalah:
  • none

    Server otorisasi tidak menampilkan layar persetujuan pengguna atau autentikasi apa pun; 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 sudah ada.

  • consent

    Server otorisasi meminta izin pengguna sebelum mengembalikan informasi ke 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 saat ini.

Jika tidak ada nilai yang ditentukan dan pengguna sebelumnya tidak memiliki akses yang sah, maka layar izin akan ditampilkan kepada pengguna.

Memvalidasi token ID

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

Berikut adalah situasi yang umum terjadi saat Anda mungkin mengirimkan token ID ke server:

  • Mengirim token ID dengan permintaan yang perlu diautentikasi. Token ID memberi tahu Anda pengguna tertentu yang membuat permintaan dan untuk klien mana token ID diberikan.

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

Satu hal yang membuat token ID bermanfaat adalah Anda dapat meneruskannya ke berbagai komponen aplikasi. Komponen ini dapat menggunakan token ID sebagai mekanisme autentikasi ringan untuk mengautentikasi aplikasi dan pengguna. Namun, sebelum dapat menggunakan informasi dalam token ID atau mengandalkannya sebagai pernyataan yang telah diautentikasi pengguna, Anda harus memvalidasinya.

Validasi token ID memerlukan beberapa langkah:

  1. Verifikasikan bahwa token ID ditandatangani dengan benar oleh penerbit. Token yang diterbitkan Google ditandatangani menggunakan salah satu sertifikat yang ditemukan di URI yang ditetapkan dalam nilai metadata jwks_uri 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 bahwa masa berlaku (exp klaim) 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 sederhana, 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 Anda. 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 men-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 dikenakan error yang berselang-seling.

Karena Google jarang mengubah kunci publiknya, Anda dapat meng-cache-nya menggunakan perintah cache respons HTTP dan, dalam sebagian besar kasus, melakukan validasi lokal secara jauh lebih efisien daripada menggunakan endpoint tokeninfo. Validasi ini mengharuskan pengambilan dan penguraian sertifikat, serta membuat 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:

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

    Jika ingin menyertakan alamat email pengguna, 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 ke header otorisasi dan buat permintaan GET HTTPS ke endpoint info pengguna, 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 dokumen Discovery. Pengguna atau organisasinya dapat memilih untuk menyediakan atau menahan kolom tertentu, sehingga Anda mungkin tidak akan mendapatkan informasi untuk setiap kolom dalam cakupan akses yang Anda beri otorisasi.

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," 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 endpoint 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 dari Google, Anda harus meng-hardcode 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 ini) sebagai URI dasar untuk permintaan autentikasi yang dikirim ke Google.

Berikut adalah contoh dokumen; nama kolom adalah yang ditetapkan dalam OpenID Connect Discovery 1.0 (lihat arti dari dokumen tersebut). Nilai tersebut hanya untuk ilustrasi dan mungkin berubah, meskipun nilai tersebut 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 menyimpan nilai dari dokumen Discovery ke dalam cache. Header penyimpanan cache 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 dari spesifikasi OpenID Connect Core. Setiap klien yang dirancang untuk bekerja dengan OpenID Connect harus berinteroperasi dengan layanan ini (kecuali OpenID Request Object).