Halaman ini diterjemahkan oleh Cloud Translation API.
Switch to English

OpenID Connect

Titik akhir OpenID Connect Google Tersertifikasi OpenID.

API OAuth 2.0 Google dapat digunakan untuk otentikasi dan otorisasi. Dokumen ini menjelaskan penerapan 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 menjelajahi protokol ini secara interaktif, kami merekomendasikan Google OAuth 2.0 Playground . Untuk mendapatkan bantuan tentang Stack Overflow , beri tag 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, menyetel URI pengalihan, dan (opsional) menyesuaikan informasi branding yang dilihat pengguna Anda di pengguna- layar persetujuan. Anda juga dapat menggunakan API Console untuk membuat akun layanan, mengaktifkan penagihan, menyiapkan pemfilteran, dan melakukan tugas lainnya. Untuk lebih jelasnya, lihat Bantuan Google API Console .

Dapatkan kredensial OAuth 2.0

Anda memerlukan kredensial OAuth 2.0, termasuk ID klien 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.

Setel URI pengalihan

URI pengalihan yang Anda setel di API Console menentukan ke mana Google mengirimkan tanggapan ke permintaan autentikasi Anda.

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 .

Sesuaikan layar persetujuan pengguna

Untuk pengguna Anda, pengalaman autentikasi OAuth 2.0 menyertakan layar persetujuan yang menjelaskan informasi yang dirilis pengguna dan persyaratan yang berlaku. Misalnya, saat pengguna login, mereka mungkin diminta untuk memberikan akses aplikasi Anda ke alamat email dan informasi akun dasar mereka. Anda meminta akses ke informasi ini menggunakan parameter scope , yang disertakan aplikasi Anda dalam permintaan autentikasinya . Anda juga dapat menggunakan cakupan untuk meminta akses ke Google API lainnya.

Layar persetujuan pengguna juga menampilkan informasi merek seperti nama produk, logo, dan URL beranda Anda. Anda mengontrol informasi merek 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 persetujuan berikut menunjukkan apa yang akan dilihat pengguna jika kombinasi cakupan OAuth 2.0 dan Google Drive ada dalam permintaan. (Dialog umum ini dibuat menggunakan Google OAuth 2.0 Playground , jadi tidak menyertakan informasi pencitraan merek yang akan disetel di API Console.)

Tangkapan layar halaman persetujuan

Mengakses layanan

Google dan pihak ketiga menyediakan pustaka yang dapat Anda gunakan untuk menangani banyak detail implementasi dari otentikasi pengguna dan mendapatkan akses ke Google API. Contohnya termasuk Masuk dengan Google dan perpustakaan klien Google , yang tersedia untuk berbagai platform.

Jika Anda memilih untuk tidak menggunakan pustaka, ikuti instruksi di sisa dokumen ini, yang menjelaskan aliran permintaan HTTP yang mendasari pustaka yang tersedia.

Mengautentikasi pengguna

Mengautentikasi pengguna melibatkan 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 aliran "server" dan aliran "implisit". Alur server memungkinkan server back-end suatu aplikasi untuk memverifikasi identitas orang tersebut 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-endnya.

Dokumen ini menjelaskan cara menjalankan aliran server untuk mengautentikasi pengguna. Aliran implisit jauh lebih rumit karena risiko keamanan dalam menangani dan menggunakan token di sisi klien. Jika Anda perlu menerapkan aliran implisit, kami sangat menyarankan menggunakan Masuk dengan Google .

Alur server

Pastikan Anda menyiapkan aplikasi Anda di API Console untuk mengaktifkannya menggunakan protokol ini dan mengautentikasi pengguna Anda. Saat pengguna mencoba masuk dengan Google, Anda perlu:

  1. Buat token status anti-pemalsuan
  2. Kirim permintaan otentikasi ke Google
  3. Konfirmasikan token status anti-pemalsuan
  4. Tukarkan code untuk token akses dan token ID
  5. Dapatkan informasi pengguna dari token ID
  6. Otentikasi pengguna

1. Buat token status anti-pemalsuan

Anda harus melindungi keamanan pengguna Anda dengan mencegah serangan pemalsuan permintaan. Langkah pertama adalah membuat token sesi unik yang menahan status antara aplikasi Anda dan klien pengguna. Nanti Anda mencocokkan token sesi unik ini dengan respons autentikasi yang dikembalikan oleh layanan Masuk OAuth Google untuk memverifikasi bahwa pengguna membuat permintaan dan bukan penyerang jahat. Token ini sering disebut sebagai token pemalsuan permintaan lintas situs ( CSRF ).

Satu pilihan yang baik untuk token status adalah string yang terdiri dari 30 karakter atau lebih yang dibuat menggunakan generator nomor acak berkualitas tinggi. Lainnya adalah hash yang dihasilkan dengan menandatangani beberapa variabel status sesi Anda dengan kunci yang dirahasiakan di back-end Anda.

Kode berikut menunjukkan pembuatan token sesi unik.

PHP

Anda harus mengunduh pustaka klien Google API agar PHP 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
));

Jawa

Anda harus mengunduh pustaka 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 mengunduh pustaka 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 otentikasi ke Google

Langkah selanjutnya adalah membentuk permintaan GET HTTPS dengan parameter URI yang sesuai. Perhatikan penggunaan HTTPS daripada HTTP di 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 aliran kode otorisasi dasar harus berupa code . (Baca selengkapnya di response_type .)
  • scope , yang dalam permintaan dasar harus openid email . (Baca lebih lanjut di scope .)
  • redirect_uri harus menjadi titik akhir HTTP di server Anda yang akan menerima tanggapan dari Google. Nilai harus sama persis dengan salah satu URI pengalihan resmi untuk klien OAuth 2.0, yang Anda konfigurasikan di API Console Credentials page. Jika nilai ini tidak cocok dengan URI resmi, permintaan akan gagal dengan kesalahan 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 lebih lanjut di state .)
  • nonce adalah nilai acak yang dihasilkan oleh aplikasi Anda yang memungkinkan perlindungan pemutaran ulang saat ada.
  • login_hint dapat berupa alamat email pengguna atau sub string, yang setara dengan ID Google pengguna. Jika Anda tidak memberikan login_hint dan pengguna saat ini masuk, layar persetujuan menyertakan permintaan persetujuan untuk merilis alamat email pengguna ke aplikasi Anda. (Baca selengkapnya di login_hint .)
  • Gunakan parameter hd untuk mengoptimalkan aliran OpenID Connect untuk pengguna domain G Suite tertentu. (Baca lebih lanjut di hd .)

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 harus memberikan persetujuan jika aplikasi Anda meminta informasi baru tentang mereka, atau jika aplikasi Anda meminta akses akun yang sebelumnya tidak mereka setujui.

3. Konfirmasikan token status anti-pemalsuan

Tanggapan dikirim ke redirect_uri yang Anda tentukan dalam permintaan . Semua tanggapan dikembalikan dalam string kueri, seperti yang 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 diterima dari Google cocok dengan token sesi yang Anda buat pada Langkah 1 . Verifikasi bolak-balik ini membantu memastikan bahwa pengguna, bukan skrip berbahaya, yang membuat permintaan.

Kode berikut menunjukkan konfirmasi token sesi yang Anda buat di Langkah 1:

PHP

Anda harus mengunduh pustaka klien Google API agar PHP 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);
}

Jawa

Anda harus mengunduh pustaka 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 mengunduh pustaka 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 untuk token akses dan token ID

Responsnya mencakup parameter code , kode otorisasi satu kali yang dapat ditukar server Anda dengan token akses dan token ID. Server Anda melakukan pertukaran ini dengan mengirimkan permintaan HTTPS POST . Permintaan POST dikirim ke titik akhir token, yang harus Anda ambil dari dokumen Discovery menggunakan nilai metadata token_endpoint . Diskusi berikut mengasumsikan titik akhir adalah https://oauth2.googleapis.com/token . Permintaan tersebut harus menyertakan parameter berikut di badan POST :

Fields
code Kode otorisasi yang dikembalikan dari permintaan awal .
client_id ID klien yang Anda peroleh dari API Console Credentials page, seperti yang dijelaskan di Mendapatkan kredensial OAuth 2.0 .
client_secret Rahasia klien yang Anda peroleh dari API Console Credentials page, seperti yang dijelaskan di Mendapatkan kredensial OAuth 2.0 .
redirect_uri URI pengalihan resmi untuk client_id tertentu yang ditentukan dalam API Console Credentials page, seperti yang dijelaskan dalam Menyetel URI pengalihan .
grant_type Bidang ini harus berisi nilai authorization_code , seperti yang ditentukan dalam spesifikasi OAuth 2.0 .

Permintaan 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 bidang berikut dalam larik JSON:

Fields
access_token Token yang dapat dikirim ke Google API.
expires_in Masa pakai token akses yang tersisa 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 peka huruf besar / kecil yang dipisahkan spasi.
token_type Mengidentifikasi jenis token yang dikembalikan. Saat ini, field ini selalu memiliki nilai Bearer .
refresh_token (pilihan)

Bidang ini hanya ada jika parameter access_type disetel ke offline dalam permintaan otentikasi . Untuk mengetahui detailnya, lihat Segarkan token .

5. Dapatkan informasi pengguna dari token ID

Token ID adalah JWT (JSON Web Token), yaitu objek JSON yang dikodekan 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 Anda untuk mengautentikasi diri Anda ke Google, Anda dapat yakin bahwa token itu adalah terima benar-benar berasal dari Google dan valid. Jika server Anda meneruskan token ID ke komponen lain dari aplikasi Anda, sangat penting bahwa komponen lain memvalidasi token sebelum menggunakannya.

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

Payload token ID

Token ID adalah objek JSON yang berisi sekumpulan pasangan nama / nilai. Berikut adalah contoh, 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 mungkin berisi bidang berikut (dikenal sebagai klaim ):

Klaim Disediakan Deskripsi
aud selalu Audiens yang menjadi tujuan token ID ini. Ini harus merupakan salah satu ID klien OAuth 2.0 dari aplikasi Anda.
exp selalu Waktu kedaluwarsa pada atau setelah itu token ID tidak boleh diterima. Diwakili dalam waktu Unix (detik integer).
iat selalu Waktu penerbitan token ID. Diwakili dalam waktu Unix (detik integer).
iss selalu Penerbit Identifier untuk Penerbit respons. Selalu https://accounts.google.com atau accounts.google.com untuk token ID Google.
sub selalu Pengenal 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 pengenal unik untuk pengguna. Panjang maksimum 255 karakter ASCII peka huruf besar / kecil.
at_hash Akses token hash. Memberikan validasi bahwa token akses terkait dengan token identitas. Jika token ID diterbitkan dengan nilai access_token di aliran 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 , tidak perlu memverifikasi token akses.
azp client_id dari presenter resmi. Klaim ini hanya diperlukan jika pihak yang meminta token ID tidak sama dengan audiens token ID. Ini mungkin terjadi di Google untuk aplikasi hibrid di mana aplikasi web dan aplikasi Android memiliki OAuth 2.0 client_id berbeda tetapi berbagi proyek Google API yang sama.
email Alamat email pengguna. Nilai ini mungkin tidak unik untuk pengguna ini dan tidak cocok untuk digunakan sebagai kunci utama. Diberikan hanya jika cakupan Anda menyertakan nilai cakupan email .
email_verified Benar 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 G Suite pengguna yang dihosting. Disediakan hanya jika pengguna termasuk dalam domain yang dihosting.
locale Lokal pengguna, diwakili oleh tag bahasa BCP 47 . Dapat diberikan jika ada klaim name .
name Nama lengkap pengguna, dalam bentuk yang dapat ditampilkan. Dapat diberikan jika:
  • Cakupan permintaan menyertakan string "profile"
  • Token ID dikembalikan dari penyegaran token

Jika ada klaim name , Anda dapat menggunakannya untuk memperbarui catatan pengguna aplikasi Anda. Perhatikan bahwa klaim ini tidak pernah dijamin akan ada.

nonce Nilai nonce diberikan oleh aplikasi Anda dalam permintaan autentikasi. Anda harus menerapkan perlindungan terhadap serangan replay dengan memastikannya hanya ditampilkan sekali.
picture URL gambar profil pengguna. Dapat diberikan jika:
  • Cakupan permintaan menyertakan string "profile"
  • Token ID dikembalikan dari penyegaran token

Jika ada klaim picture , Anda dapat menggunakannya untuk memperbarui catatan 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 dikembalikan dari penyegaran token

Jika ada klaim profile , Anda dapat menggunakannya untuk memperbarui catatan pengguna aplikasi Anda. Perhatikan bahwa klaim ini tidak pernah dijamin akan ada.

6. Otentikasi pengguna

Setelah mendapatkan informasi pengguna dari token ID, Anda harus membuat kueri database pengguna aplikasi Anda. Jika pengguna sudah ada di database Anda, Anda harus memulai sesi aplikasi untuk pengguna tersebut jika semua persyaratan login dipenuhi oleh respons Google API.

Jika pengguna tidak ada di database pengguna Anda, Anda harus mengarahkan pengguna ke alur pendaftaran pengguna baru Anda. Anda mungkin dapat mendaftarkan pengguna secara otomatis berdasarkan informasi yang Anda terima dari Google, atau setidaknya Anda dapat mengisi lebih dulu banyak bidang yang Anda perlukan di formulir pendaftaran. Selain informasi dalam token ID, Anda bisa mendapatkan informasi profil pengguna tambahan di titik akhir profil pengguna kami.

Topik lanjutan

Bagian berikut menjelaskan Google OAuth 2.0 API secara lebih mendetail. Informasi ini ditujukan untuk pengembang dengan persyaratan lanjutan seputar otentikasi 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 lain 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 kirimkan 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 diminta dengan tepat di layar persetujuan . Token akses yang Anda terima kembali dari Google memungkinkan Anda mengakses semua API yang terkait dengan cakupan akses yang Anda minta dan diberikan.

Segarkan token

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

Pertimbangan:

  • Pastikan untuk menyimpan token penyegaran dengan aman dan permanen, karena Anda hanya bisa mendapatkan token penyegaran saat pertama kali Anda menjalankan aliran pertukaran kode.
  • Ada batasan jumlah token penyegaran yang dikeluarkan: satu batas per kombinasi klien / pengguna, dan satu lagi per pengguna di semua klien. Jika aplikasi Anda meminta terlalu banyak token penyegaran, aplikasi mungkin akan mengalami batasan ini, dalam hal ini token penyegaran yang lebih lama berhenti berfungsi.

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

Anda dapat meminta pengguna untuk memberi otorisasi ulang pada aplikasi Anda dengan menyetel parameter prompt untuk consent dalam permintaan autentikasi Anda. Jika prompt=consent disertakan, layar persetujuan ditampilkan setiap kali aplikasi Anda meminta otorisasi cakupan akses, meskipun semua cakupan sebelumnya telah diberikan ke proyek Google API Anda. Untuk alasan ini, sertakan prompt=consent hanya jika diperlukan.

Untuk informasi selengkapnya tentang parameter prompt , lihat prompt di tabel parameter Authentication URI .

Parameter URI otentikasi

Tabel berikut memberikan deskripsi yang lebih lengkap tentang parameter yang diterima oleh API otentikasi OAuth 2.0 Google.

Parameter Yg dibutuhkan Deskripsi
client_id (Yg dibutuhkan) String ID klien yang Anda peroleh dari API Console Credentials page, seperti yang dijelaskan di Mendapatkan kredensial OAuth 2.0 .
nonce (Yg dibutuhkan) Nilai acak yang dihasilkan oleh aplikasi Anda yang memungkinkan perlindungan pemutaran ulang.
response_type (Yg dibutuhkan) Jika nilainya adalah code , luncurkan alur kode otorisasi Dasar , yang memerlukan POST ke titik akhir token untuk mendapatkan token. Jika nilainya adalah token id_token atau id_token token , meluncurkan aliran Implisit , yang mengharuskan penggunaan JavaScript pada URI pengalihan untuk mengambil token dari pengenal URI #fragment .
redirect_uri (Yg dibutuhkan) Menentukan kemana respon dikirim. Nilai parameter ini harus sama persis dengan salah satu nilai pengalihan resmi yang Anda setel di API Console Credentials page (termasuk skema HTTP atau HTTPS, kapitalisasi, dan tanda '/' di belakang, jika ada).
scope (Yg dibutuhkan)

Parameter cakupan harus dimulai dengan nilai openid dan kemudian 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 menyertakan email dan klaim email_verified .

Selain cakupan khusus OpenID ini, argumen cakupan Anda juga bisa menyertakan nilai cakupan lainnya. Semua nilai cakupan harus dipisahkan spasi. Misalnya, jika Anda menginginkan akses per file ke Google Drive pengguna, parameter cakupan Anda mungkin berupa 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 disarankan)

String buram yang dibuat trip-trip dalam protokol; artinya, ini dikembalikan sebagai parameter URI di aliran Dasar, dan di #fragment URI #fragment di aliran Implisit.

state dapat berguna untuk menghubungkan permintaan dan tanggapan. Karena redirect_uri Anda dapat ditebak, menggunakan nilai state dapat meningkatkan jaminan Anda bahwa koneksi masuk adalah hasil dari permintaan autentikasi yang dimulai oleh aplikasi Anda. Jika Anda membuat string acak atau menyandikan hash dari beberapa status klien (misalnya, cookie) dalam variabel state ini, Anda dapat memvalidasi respons untuk memastikan bahwa permintaan dan respons berasal dari browser yang sama. Ini memberikan perlindungan terhadap serangan seperti pemalsuan permintaan lintas situs.

access_type (Pilihan) Nilai yang diizinkan adalah offline dan online . Efeknya didokumentasikan di Akses Offline ; jika token akses diminta, klien tidak menerima token refresh kecuali nilai offline ditentukan.
display (Pilihan) Nilai string ASCII untuk menentukan bagaimana server otorisasi menampilkan halaman antarmuka pengguna otentikasi dan persetujuan. Nilai berikut ditentukan, dan diterima oleh server Google, tetapi tidak mempengaruhi perilakunya: page , popup , touch , dan wap .
hd (Pilihan)

Parameter hd (domain yang dihosting) menyederhanakan proses login untuk akun yang dihosting G Suite. Dengan menyertakan domain pengguna G Suite (misalnya, mycollege.edu ), Anda dapat menunjukkan bahwa UI pemilihan akun harus dioptimalkan untuk akun di domain tersebut. Untuk mengoptimalkan akun G Suite secara umum, bukan hanya satu domain, 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 dikembalikan memiliki nilai klaim hd yang sesuai dengan yang Anda harapkan (mis. mycolledge.edu ). Berbeda dengan parameter request, klaim ID token hd terdapat dalam security token dari Google, sehingga nilainya dapat dipercaya.

include_granted_scopes (Pilihan) 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 tambahan .

Perhatikan bahwa Anda tidak dapat melakukan otorisasi tambahan dengan alur Aplikasi Terinstal.

login_hint (Pilihan) Saat aplikasi Anda mengetahui pengguna mana yang coba diautentikasi, ia bisa memberikan parameter ini sebagai petunjuk ke server autentikasi. Meneruskan petunjuk ini akan menekan pemilih akun dan mengisi kotak email di formulir masuk, atau memilih sesi yang tepat (jika pengguna menggunakan banyak masuk ), yang dapat membantu Anda menghindari masalah yang terjadi jika aplikasi Anda masuk ke akun pengguna yang salah. Nilainya dapat berupa alamat email atau sub string, yang setara dengan ID Google pengguna.
prompt (Pilihan) Daftar nilai string yang dipisahkan spasi yang menentukan apakah server otorisasi meminta autentikasi ulang dan persetujuan pengguna. Nilai yang mungkin adalah:
  • none

    Server otorisasi tidak menampilkan layar otentikasi atau persetujuan pengguna; ini akan mengembalikan kesalahan jika pengguna belum diautentikasi dan belum mengonfigurasi persetujuan untuk cakupan yang diminta. Anda tidak dapat menggunakan none untuk memeriksa otentikasi dan / atau persetujuan yang ada.

  • consent

    Server otorisasi meminta persetujuan pengguna sebelum mengembalikan informasi ke klien.

  • select_account

    Server otorisasi meminta pengguna untuk memilih akun pengguna. Hal ini memungkinkan pengguna yang memiliki banyak akun di server otorisasi untuk memilih di antara beberapa akun yang mungkin mereka miliki sesinya.

Jika tidak ada nilai yang ditentukan dan pengguna sebelumnya tidak memiliki akses yang sah, maka pengguna akan diperlihatkan layar persetujuan.

Memvalidasi token ID

Anda perlu memvalidasi semua token ID di server Anda kecuali Anda tahu bahwa itu datang langsung dari Google. Misalnya, server Anda harus memverifikasi autentik semua token ID yang diterimanya dari aplikasi klien Anda.

Berikut adalah situasi umum di mana Anda mungkin mengirim token ID ke server Anda:

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

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

Satu hal yang membuat token ID berguna adalah fakta bahwa Anda dapat meneruskannya ke berbagai komponen aplikasi Anda. 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 penegasan bahwa pengguna telah mengautentikasi, Anda harus memvalidasinya.

Validasi token ID membutuhkan beberapa langkah:

  1. Verifikasi bahwa token ID ditandatangani dengan benar oleh penerbit. Token yang diterbitkan Google ditandatangani menggunakan salah satu sertifikat yang ditemukan di URI yang ditentukan dalam nilai metadata jwks_uri dari dokumen Discovery .
  2. Verifikasikan bahwa nilai klaim iss di token ID sama dengan https://accounts.google.com atau accounts.google.com .
  3. Pastikan nilai klaim aud dalam token ID sama dengan ID klien aplikasi Anda.
  4. Verifikasi bahwa waktu kedaluwarsa (klaim exp ) dari token ID belum lewat.
  5. Jika Anda menentukan nilai parameter hd dalam permintaan, verifikasi bahwa token ID memiliki klaim hd yang cocok dengan domain yang dihosting G Suite yang diterima.

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 debugging , 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 merujuk URI https://oauth2.googleapis.com/tokeninfo?id_token= XYZ123 . Jika tanda tangan token valid, responsnya adalah payload JWT dalam bentuk objek JSON yang didekodekan.

Endpoint tokeninfo berguna untuk debugging, 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 titik akhir debugging mungkin akan terhambat atau terkadang mengalami error yang terputus-putus.

Karena Google jarang mengubah kunci publiknya, Anda dapat menyimpannya dalam cache menggunakan arahan cache dari respons HTTP dan, dalam sebagian besar kasus, melakukan validasi lokal jauh lebih efisien daripada menggunakan titik akhir tokeninfo . Validasi ini memerlukan pengambilan dan penguraian sertifikat, dan melakukan panggilan kriptografi yang sesuai untuk memeriksa tanda tangan. Untungnya, ada pustaka 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 aliran otentikasi ) dan standar OpenID Connect :

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

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

    scope=openid%20profile%20email
  2. Tambahkan token akses Anda ke header otorisasi dan buat permintaan HTTPS GET ke titik akhir userinfo, yang harus Anda ambil dari dokumen Discovery menggunakan nilai metadata userinfo_endpoint . Respons userinfo mencakup informasi tentang pengguna, seperti yang dijelaskan di OpenID Connect Standard Claims dan nilai metadata yang claims_supported dari dokumen Discovery. Pengguna atau organisasi mereka dapat memilih untuk menyediakan atau menahan bidang tertentu, jadi Anda mungkin tidak mendapatkan informasi untuk setiap bidang untuk cakupan akses resmi Anda.

Dokumen Penemuan

Protokol OpenID Connect memerlukan penggunaan beberapa titik akhir untuk mengautentikasi pengguna, dan untuk meminta sumber daya termasuk token, informasi pengguna, dan kunci publik.

Untuk menyederhanakan implementasi dan meningkatkan fleksibilitas, OpenID Connect mengizinkan penggunaan "dokumen Discovery", dokumen JSON yang ditemukan di lokasi terkenal yang berisi key-value pair yang memberikan detail tentang konfigurasi penyedia OpenID Connect, termasuk URI otorisasi , token, pencabutan, info pengguna, dan titik akhir 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 membuat kode keras URI dokumen Penemuan ( https://accounts.google.com/.well-known/openid-configuration ) ke dalam aplikasi Anda. Aplikasi Anda mengambil dokumen, menerapkan aturan caching dalam responsnya, 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 pada contoh di bawah) sebagai URI dasar untuk permintaan otentikasi yang dikirim ke Google.

Berikut adalah contoh dokumen semacam itu; nama bidang adalah yang ditentukan dalam OpenID Connect Discovery 1.0 (lihat dokumen itu untuk artinya). Nilainya hanya ilustrasi dan mungkin 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 HTTP round-trip dengan menyimpan nilai-nilai dari dokumen Discovery. Header cache HTTP standar digunakan dan harus dipatuhi.

Perpustakaan klien

Pustaka klien berikut membuat penerapan OAuth 2.0 lebih sederhana dengan mengintegrasikan kerangka kerja 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 beroperasi dengan layanan ini (dengan pengecualian Objek Permintaan OpenID ).