Plugin ini memungkinkan Anda mengonfigurasi layanan otentikasi sendiri untuk mengotentikasi akses API.
1. Ikhtisar
Sebelum memanggil layanan backend, API Gateway terlebih dahulu memanggil layanan otentikasi Anda. API Gateway hanya akan melanjutkan panggilan ke layanan backend setelah menerima tanggapan sukses dari layanan otentikasi Anda. Jika tidak, API Gateway akan mengembalikan tanggapan kegagalan otentikasi kepada klien. Plugin otentikasi pihak ketiga mendukung fitur-fitur berikut:
Menyesuaikan parameter permintaan yang dikirim ke layanan otentikasi.
Menyimpan cache tanggapan otentikasi di API Gateway selama periode tertentu untuk memastikan ketersediaan layanan.
Menyesuaikan tanggapan untuk kegagalan otentikasi.

2. Konfigurasi plug-in
Jika konfigurasi tidak berlaku pada Instans khusus yang dibeli sebelum 9 Mei 2023, submit a ticket untuk menghubungi kami guna meningkatkan versi instans Anda.
2.1 Ketika layanan otentikasi menggunakan titik akhir Internet
---
parameters: # Definisi parameter yang digunakan dalam ekspresi hasil otentikasi.
statusCode: "StatusCode" # Kode respons HTTP.
authUriType: "HTTP" # Jenis layanan otentikasi. HTTP: titik akhir di Internet. HTTP-VPC: alamat yang diotorisasi di VPC.
authUri: # Definisi layanan otentikasi.
address: "http://auth.com:8080" # Titik akhir layanan otentikasi, termasuk nomor Port.
path: "/auth" # Jalur layanan otentikasi.
timeout: 7000 # Periode waktu habis (timeout) untuk layanan otentikasi. Nilai maksimum adalah 10 detik.
method: POST # Metode HTTP layanan otentikasi.
passThroughBody: false # Menentukan apakah badan permintaan diteruskan ke layanan otentikasi.
passThroughPath: true # Jika parameter ini diatur ke true, jalur permintaan ditempatkan dalam header X-Ca-Remote-Auth-Raw-Path dan dikirim ke layanan otentikasi.
cachedTimeBySecond: 10 # Periode waktu penyimpanan cache tanggapan otentikasi oleh API Gateway. Periode maksimum adalah 10 menit. Saat ini, cache menggunakan kombinasi UID API dan semua parameter otentikasi sebagai kunci utama.
trimAuthorizationHeaderPrefix: true # Jika parameter otentikasi berada di header Authorization, fitur ini secara cerdas melewati awalan untuk mengekstrak nilai parameternya. Misalnya, jika Anda mengekstrak nilai dari header "Authorization: bearer hello", nilai yang diekstrak adalah "hello", bukan "bearer hello".
authParameters: # Pemetaan parameter yang dikirim ke layanan otentikasi.
- targetParameterName: x-userId # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: userId # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
- targetParameterName: x-password # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: password # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
- targetParameterName: token
sourceParameterName: Authorization
targetLocation: query
sourceLocation: header
successCondition: "${statusCode} = 200" # Ekspresi yang menentukan apakah otentikasi berhasil berdasarkan tanggapan. Jika ekspresi bernilai True, otentikasi berhasil.
errorMessage: "auth failed" # Nilai header x-ca-errormessage yang diterima klien saat otentikasi gagal.
errorStatusCode : 401 # Kode status HTTP yang diterima klien saat otentikasi gagal.
errorPassThroughHeaderList: auth-result1,auth-result2 # Header tertentu dari tanggapan otentikasi yang diteruskan ke klien saat otentikasi gagal.
errorPassThroughBody: true # Menentukan apakah badan tanggapan otentikasi diteruskan ke klien saat otentikasi gagal.
ignoreAuthException: true # Jika terjadi pengecualian, seperti timeout atau kesalahan koneksi, selama otentikasi, hasil otentikasi diabaikan dan layanan backend diakses langsung.Ketika API Gateway memproses permintaan untuk API yang telah ditautkan dengan plug-in ini, API Gateway pertama-tama merakit permintaan otentikasi berdasarkan konfigurasi plug-in dan mengirimkannya ke "http://auth.com:8080". API Gateway kemudian menentukan apakah otentikasi berhasil berdasarkan tanggapan tersebut. Jika otentikasi gagal, Anda dapat menyesuaikan tanggapan kegagalan yang dikembalikan ke klien.
2.2 Jika layanan otentikasi berada di VPC
---
parameters: # Definisi parameter yang digunakan dalam ekspresi hasil otentikasi.
statusCode: "StatusCode" # Kode respons HTTP.
authUriType: "HTTP-VPC" # Jenis layanan otentikasi. HTTP: titik akhir di Internet. HTTP-VPC: alamat yang diotorisasi di VPC.
authUri: # Definisi layanan otentikasi.
vpcAccessName: "slbAccessForVip" # Nama otorisasi VPC untuk layanan otentikasi.
path: "/auth" # Jalur layanan otentikasi.
timeout: 7000 # Periode waktu habis (timeout) untuk layanan otentikasi. Nilai maksimum adalah 10 detik.
method: POST # Metode HTTP layanan otentikasi.
passThroughBody: false # Menentukan apakah badan permintaan diteruskan ke layanan otentikasi.
cachedTimeBySecond: 10 # Periode waktu penyimpanan cache tanggapan otentikasi oleh API Gateway. Periode maksimum adalah 10 menit. Saat ini, cache menggunakan kombinasi UID API dan semua parameter otentikasi sebagai kunci utama.
authParameters: # Pemetaan parameter yang dikirim ke layanan otentikasi.
- targetParameterName: x-userId # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: userId # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
- targetParameterName: x-password # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: password # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
successCondition: "${statusCode} = 200" # Ekspresi yang menentukan apakah otentikasi berhasil berdasarkan tanggapan. Jika ekspresi bernilai True, otentikasi berhasil.
errorMessage: "auth failed" # Nilai header x-ca-errormessage yang diterima klien saat otentikasi gagal.
errorStatusCode : 401 # Kode status HTTP yang diterima klien saat otentikasi gagal.
errorPassThroughHeaderList: auth-result1,auth-result2 # Header tertentu dari tanggapan otentikasi yang diteruskan ke klien saat otentikasi gagal.
errorPassThroughBody: true # Menentukan apakah badan tanggapan otentikasi diteruskan ke klien saat otentikasi gagal.
ignoreAuthException: true # Jika terjadi pengecualian, seperti timeout atau kesalahan koneksi, selama otentikasi, hasil otentikasi diabaikan dan layanan backend diakses langsung.2.3 Mengekstrak bidang dari badan JSON tanggapan otentikasi
---
parameters: # Definisi parameter yang digunakan dalam ekspresi hasil otentikasi.
clientId: "BodyJsonField:$.clientId"# Parameter bernama clientId dalam struktur JSON badan tanggapan otentikasi.
authUriType: "HTTP-VPC" # Jenis layanan otentikasi. HTTP: titik akhir di Internet. HTTP-VPC: alamat yang diotorisasi di VPC.
authUri: # Definisi layanan otentikasi.
vpcAccessName: "slbAccessForVip" # Nama otorisasi VPC untuk layanan otentikasi.
vpcScheme: "https" # Protokol layanan otentikasi. Jika Anda tidak menentukan parameter ini, HTTP digunakan secara default.
path: "/auth" # Jalur layanan otentikasi.
timeout: 7000 # Periode waktu habis (timeout) untuk layanan otentikasi. Nilai maksimum adalah 10 detik.
method: POST # Metode HTTP layanan otentikasi.
passThroughBody: false # Menentukan apakah badan permintaan diteruskan ke layanan otentikasi.
cachedTimeBySecond: 10 # Periode waktu penyimpanan cache tanggapan otentikasi oleh API Gateway. Periode maksimum adalah 10 menit. Saat ini, cache menggunakan kombinasi UID API dan semua parameter otentikasi sebagai kunci utama.
authParameters: # Pemetaan parameter yang dikirim ke layanan otentikasi.
- targetParameterName: x-userId # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: userId # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
- targetParameterName: x-password # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: password # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
successCondition: "${clientId} = 10086" # Ekspresi yang menentukan apakah otentikasi berhasil berdasarkan tanggapan. Jika ekspresi bernilai True, otentikasi berhasil.
errorMessage: "auth failed" # Nilai header x-ca-errormessage yang diterima klien saat otentikasi gagal.
errorStatusCode : 401 # Kode status HTTP yang diterima klien saat otentikasi gagal.
errorPassThroughHeaderList: auth-result1,auth-result2 # Header tertentu dari tanggapan otentikasi yang diteruskan ke klien saat otentikasi gagal.
errorPassThroughBody: true # Menentukan apakah badan tanggapan otentikasi diteruskan ke klien saat otentikasi gagal.
ignoreAuthException: true # Jika terjadi pengecualian, seperti timeout atau kesalahan koneksi, selama otentikasi, hasil otentikasi diabaikan dan layanan backend diakses langsung.Jika nilai bidang clientId dalam tanggapan yang dikembalikan oleh layanan otentikasi adalah 10086, otentikasi berhasil.
{"code":200,"clientId":10086}2.4 Menggunakan set data plug-in untuk otentikasi identitas dan daftar putih dinamis
Anda dapat menyimpan daftar putih dalam set data plug-in. API Gateway mengekstrak bidang identitas pengguna dari tanggapan otentikasi pihak ketiga dan memeriksa apakah pengguna tersebut ada dalam daftar putih. Otentikasi hanya berhasil untuk pengguna yang ada dalam daftar putih.
---
parameters: # Definisi parameter yang digunakan dalam ekspresi hasil otentikasi.
statusCode: "StatusCode" # Kode respons HTTP.
clientId: "BodyJsonField:$.clientId"# Parameter bernama clientId dalam struktur JSON badan tanggapan otentikasi.
authUriType: "HTTP-VPC" # Jenis layanan otentikasi. HTTP: titik akhir di Internet. HTTP-VPC: alamat yang diotorisasi di VPC.
authUri: # Definisi layanan otentikasi.
vpcAccessName: "slbAccessForVip" # Nama otorisasi VPC untuk layanan otentikasi.
path: "/auth" # Jalur layanan otentikasi.
timeout: 7000 # Periode waktu habis (timeout) untuk layanan otentikasi. Nilai maksimum adalah 10 detik.
method: POST # Metode HTTP layanan otentikasi.
passThroughBody: false # Menentukan apakah badan permintaan diteruskan ke layanan otentikasi.
cachedTimeBySecond: 10 # Periode waktu penyimpanan cache tanggapan otentikasi oleh API Gateway. Periode maksimum adalah 10 menit. Saat ini, cache menggunakan kombinasi UID API dan semua parameter otentikasi sebagai kunci utama.
authParameters: # Pemetaan parameter yang dikirim ke layanan otentikasi.
- targetParameterName: x-userId # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: userId # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
- targetParameterName: x-password # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: password # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
successCondition: "${statusCode} = 200" # Ekspresi yang menentukan tanggapan otentikasi.
accessParameterName: clientId # Nama parameter yang dibandingkan dengan data dalam set data.
accessByDataSet: dataset_test # Set data yang digunakan untuk otentikasi. Jika data dalam set data berisi nilai clientId, otentikasi berhasil.
errorMessage: "auth failed" # Nilai header x-ca-errormessage yang diterima klien saat otentikasi gagal.
errorStatusCode : 401 # Kode status HTTP yang diterima klien saat otentikasi gagal.
errorPassThroughHeaderList: auth-result1,auth-result2 # Header tertentu dari tanggapan otentikasi yang diteruskan ke klien saat otentikasi gagal.
errorPassThroughBody: true # Menentukan apakah badan tanggapan otentikasi diteruskan ke klien saat otentikasi gagal.
ignoreAuthException: true # Jika terjadi pengecualian, seperti timeout atau kesalahan koneksi, selama otentikasi, hasil otentikasi diabaikan dan layanan backend diakses langsung.Jika nilai bidang clientId dalam tanggapan yang dikembalikan oleh layanan otentikasi ada dalam set data plug-in bernama dataset_test, otentikasi berhasil.
2.5 Mengintegrasikan dengan otentikasi aplikasi
---
parameters: # Definisi parameter yang digunakan dalam ekspresi hasil otentikasi.
statusCode: "StatusCode" # Kode respons HTTP.
authUriType: "HTTP-VPC" # Jenis layanan otentikasi. HTTP: titik akhir di Internet. HTTP-VPC: alamat yang diotorisasi di VPC.
authUri: # Definisi layanan otentikasi.
vpcAccessName: "slbAccessForVip" # Nama otorisasi VPC untuk layanan otentikasi.
path: "/auth" # Jalur layanan otentikasi.
timeout: 7000 # Periode waktu habis (timeout) untuk layanan otentikasi. Nilai maksimum adalah 10 detik.
method: POST # Metode HTTP layanan otentikasi.
cachedTimeBySecond: 10 # Periode waktu penyimpanan cache tanggapan otentikasi oleh API Gateway. Periode maksimum adalah 10 menit. Saat ini, cache menggunakan kombinasi UID API dan semua parameter otentikasi sebagai kunci utama.
authParameters: # Pemetaan parameter yang dikirim ke layanan otentikasi.
- targetParameterName: x-password # Nama parameter yang dikirim ke layanan otentikasi.
sourceParameterName: password # Nama parameter dalam permintaan asli.
targetLocation: query # Lokasi parameter yang dikirim ke layanan otentikasi.
sourceLocation: query # Lokasi parameter dalam permintaan asli.
successCondition: "${statusCode} = 200" # Ekspresi yang menentukan tanggapan otentikasi.
errorMessage: "auth failed" # Nilai header x-ca-errormessage yang diterima klien saat otentikasi gagal.
errorStatusCode : 401 # Kode status HTTP yang diterima klien saat otentikasi gagal.
errorPassThroughHeaderList: auth-result1,auth-result2 # Header tertentu dari tanggapan otentikasi yang diteruskan ke klien saat otentikasi gagal.
errorPassThroughBody: true # Menentukan apakah badan tanggapan otentikasi diteruskan ke klien saat otentikasi gagal.
ignoreAuthException: true # Jika terjadi pengecualian, seperti timeout atau kesalahan koneksi, selama otentikasi, hasil otentikasi diabaikan dan layanan backend diakses langsung.
orAppAuth: true # Jika salah satu dari otentikasi aplikasi atau otentikasi pihak ketiga berhasil, otentikasi keseluruhan dianggap berhasil.Setelah Anda mengonfigurasi parameter orAppAuth: true, otentikasi dianggap berhasil jika salah satu dari otentikasi aplikasi atau otentikasi pihak ketiga berhasil.
2.6 Mengekstrak bidang dari tanggapan layanan otentikasi dan mengirimkannya ke layanan backend
Untuk mengekstrak bidang dari tanggapan yang dikembalikan oleh layanan otentikasi dan mengirimkannya ke layanan backend, gunakan parameter authResultPassThrough untuk mengonfigurasi pemetaan parameter.
Parameter dapat diekstrak dari lokasi sumber berikut dalam tanggapan: StatusCode, Header, dan JsonBody.
Lokasi target yang didukung dalam permintaan layanan backend meliputi Header, Query, dan Formdata.
---
parameters: # Definisi parameter yang digunakan dalam ekspresi hasil otentikasi.
statusCode: "StatusCode" # Kode respons HTTP.
clientId: "BodyJsonField:$.Body" # Badan JSON yang dikembalikan oleh layanan otentikasi.
authUriType: "HTTP" # Jenis layanan otentikasi. HTTP: titik akhir di Internet. HTTP-VPC: alamat yang diotorisasi di VPC.
authUri: # Definisi layanan otentikasi.
address: "http://127.0.0.1:8080" # Titik akhir layanan otentikasi, termasuk nomor Port.
path: "/web" # Jalur layanan otentikasi.
timeout: 7000 # Periode waktu habis (timeout) untuk layanan otentikasi, dalam milidetik (ms). Nilai maksimum adalah 10 detik.
method: POST # Metode HTTP layanan otentikasi.
passThroughBody: true # Menentukan apakah badan permintaan diteruskan ke layanan otentikasi.
cachedTimeBySecond: 10 # Periode waktu penyimpanan cache tanggapan otentikasi oleh API Gateway. Periode maksimum adalah 10 menit. Saat ini, cache menggunakan kombinasi UID API dan semua parameter otentikasi sebagai kunci utama.
authResultPassThrough: # Pemetaan parameter yang dikirim ke layanan backend.
- targetParameterName: x-echo-header-client-id # Nama parameter yang dikirim ke layanan backend.
targetLocation: header # Lokasi parameter dalam permintaan layanan backend.
sourceParameterName: clientId # Parameter yang diekstrak dari tanggapan layanan otentikasi.
- targetParameterName: x-echo-header-status-code
targetLocation: query
sourceParameterName: statusCode
successCondition: "${statusCode} = 200" # Ekspresi yang menentukan tanggapan otentikasi.
errorMessage: "auth failed" # Nilai header x-ca-errormessage yang diterima klien saat otentikasi gagal.
errorStatusCode: 401 # Kode status HTTP yang diterima klien saat otentikasi gagal.
errorPassThroughHeaderList: auth-result1,auth-result2 # Header tertentu dari tanggapan otentikasi yang diteruskan ke klien saat otentikasi gagal.
errorPassThroughBody: true # Menentukan apakah badan tanggapan otentikasi diteruskan ke klien saat otentikasi gagal.Parameter yang diekstrak dari tanggapan layanan otentikasi dapat digunakan sebagai parameter untuk plug-in lain. Kode berikut memberikan contoh:
parameters: # Daftar parameter yang dapat digunakan untuk fitur seperti pembatasan laju.
clientId: "Parameter:x-echo-header-client-id" # Nama parameter yang dikirim ke layanan backend.2.7 Menyimpan cache tanggapan otentikasi
Untuk meningkatkan ketersediaan layanan dan mengurangi beban pada layanan otentikasi Anda, API Gateway mendukung penyimpanan cache tanggapan otentikasi. Cache menggunakan kombinasi UID API dan semua parameter otentikasi sebagai kunci utama serta tanggapan otentikasi sebagai nilainya. Durasi cache maksimum adalah 10 menit.
2.8 Melewatkan otentikasi pihak ketiga berdasarkan nilai parameter
Jika konfigurasi tidak berlaku pada Instans khusus yang dibeli sebelum 26 Mei 2025, submit a ticket untuk menghubungi kami guna meningkatkan versi instans Anda.
Fitur ini mendukung perutean otentikasi bersyarat berdasarkan nilai parameter permintaan. Hal ini memungkinkan Anda memilih kebijakan otentikasi secara dinamis berdasarkan aturan yang telah ditentukan. Fitur ini berguna dalam skenario di mana beberapa permintaan memerlukan otentikasi pihak ketiga dan yang lainnya memerlukan otentikasi aplikasi.
Blok konfigurasi skipRemoteAuthOnRequestParametersCondition digunakan untuk melewatkan otentikasi pihak ketiga. Otentikasi pihak ketiga dilewatkan ketika semua kondisi parameter terpenuhi. Untuk parameter sourceParameterConditionValues, Anda dapat menentukan daftar nilai. Sub-kondisi terpenuhi jika bidang permintaan cocok dengan salah satu nilai dalam daftar tersebut. Jika sourceParameterConditionValues diatur ke null, sub-kondisi terpenuhi hanya jika bidang tersebut tidak ada. Jika sourceParameterConditionValues diatur ke *, sub-kondisi terpenuhi untuk nilai bidang apa pun. Kode berikut memberikan contoh konfigurasi.
parameters:
statusCode: "StatusCode"
userId: "BodyJsonField:$.Headers.tokenUserId"
authUriType: "HTTP"
authUri:
address: "https://auth.com"
path: "/auth"
timeout: 7000
method: POST
passThroughBody: false
cachedTimeBySecond: 1
authParameters:
- targetParameterName: tokenUserId
sourceParameterName: userId
targetLocation: Header
sourceLocation: Query
successCondition: "${userId} = 'admin'"
skipRemoteAuthOnRequestParametersCondition: // Melewatkan otentikasi pihak ketiga jika semua kondisi berikut terpenuhi.
- sourceParameterName: userId // Nama parameter permintaan.
sourceLocation: Query // Lokasi parameter permintaan.
sourceParameterConditionValues: admin1,admin2 // Daftar nilai parameter. Sub-kondisi terpenuhi jika nilai parameter permintaan ini ada dalam daftar.
- sourceParameterName: password // Nama parameter permintaan.
sourceLocation: Query // Lokasi parameter permintaan.
sourceParameterConditionValues: null // Sub-kondisi terpenuhi jika parameter permintaan ini tidak ada.2.9 Mengirim parameter konstan ke layanan otentikasi pihak ketiga
Jika konfigurasi tidak berlaku pada Instans khusus yang dibeli sebelum 22 Maret 2025, submit a ticket untuk menghubungi kami guna meningkatkan versi instans Anda.
Fitur ini memungkinkan Anda menyisipkan parameter konstan ke permintaan yang dikirim ke layanan otentikasi pihak ketiga. Saat Anda mengonfigurasi parameter otentikasi, jika Anda langsung mengatur properti targetParameterValue tanpa menentukan properti sourceLocation dan sourceParameterName, sistem secara otomatis memperlakukan parameter ini sebagai parameter konstan.
parameters:
userId: "BodyJsonField:$.Headers.tokenUserId"
authUriType: "HTTP"
authUri:
address: "https://auth.com"
path: "/auth"
timeout: 7000
method: POST
passThroughBody: false
cachedTimeBySecond: 1
authParameters:
- targetParameterName: tokenUserId
sourceParameterName: userId
targetLocation: Header
sourceLocation: Query
- targetParameterName: constantParam1 // Parameter konstan otentikasi. Anda hanya perlu mengatur nilai parameternya. Tidak perlu mengonfigurasi parameter sumber.
targetParameterValue: "test"
targetLocation: Header
successCondition: "${userId} = 'A101' and ${constantParam} = 'test'"3. Log
Dalam log yang dikirimkan ke Simple Log Service (SLS), bidang `plugin` menunjukkan hasil otentikasi pihak ketiga. `"authSuccess":"0"` menunjukkan bahwa otentikasi gagal. `"authSuccess":"1"` menunjukkan bahwa otentikasi berhasil.
plugin:[{"context":{"authSuccess":"0"},"pluginName":"remoteAuth"}]