Konfigurasikan plugin jwt-auth - API Gateway - Alibaba Cloud Documentation Center

Plugin jwt-auth menyediakan autentikasi dan otorisasi berbasis JSON Web Token (JWT). Plugin ini mengurai JWT dari parameter URL, header permintaan, atau cookie dalam permintaan HTTP, lalu memverifikasi token tersebut untuk memberikan atau menolak akses. Berbeda dengan autentikasi dan otorisasi JWT, plugin jwt-auth juga mengidentifikasi pemanggil, sehingga Anda dapat mengonfigurasi kredensial JWT yang berbeda untuk pemanggil yang berbeda.

Bidang konfigurasi

Konfigurasi autentikasi

Name	Data type	Required	Default value	Description
consumers	array of object	Required	-	Konsumen layanan untuk autentikasi permintaan.
global_auth	Array of strings	Optional (instance-level configuration only)	-	Hanya dapat dikonfigurasi di tingkat instans. Jika diatur ke true, autentikasi diterapkan secara global. Jika diatur ke false, autentikasi hanya berlaku untuk nama domain dan rute yang dikonfigurasi. Jika tidak dikonfigurasi, autentikasi diterapkan secara global hanya ketika tidak ada konfigurasi nama domain atau rute, guna memastikan kompatibilitas bagi pengguna yang sudah ada.

Tabel berikut menjelaskan bidang-bidang untuk setiap item dalam consumers.

Name	Data type	Required	Default value	Description
name	string	Required	-	Nama konsumen.
jwks	string	Optional. `jwks` atau `remote_jwks` wajib diisi.	-	String berformat JSON sesuai spesifikasi JSON Web Key (JWK). Ini adalah JSON Web Key Set yang berisi kunci publik atau kunci simetris yang digunakan untuk memverifikasi signature JWT.
remote_jwks	object	Optional. Pilih salah satu antara `jwks` atau `remote_jwks`.	{"uri":"http://127.0.0.1/keys","service":"test.static","port":"80","ttl":30000,"timeout":3000}	Secara berkala mengambil JWKS dari URI tertentu pada layanan tertentu. Jika kedua bidang `jwks` dan `remote_jwks` dikonfigurasi, JWKS yang diambil melalui bidang ini akan didahulukan. Catatan Ukuran JWKS yang dikembalikan oleh `remote_jwks` harus kurang dari 1 MB. Jika ukurannya melebihi batas ini dan terjadi error, bergabunglah dengan grup DingTalk 88010006189 atau submit a ticket untuk mendapatkan dukungan.
issuer	string	Optional	-	Penerbit JWT. Nilai ini harus sesuai dengan bidang `iss` dalam muatan (payload).
claims	object	Optional	-	Pasangan kunci-nilai yang sesuai dengan pasangan kunci-nilai dalam muatan (payload), digunakan untuk memverifikasi bahwa beberapa bidang sesuai dengan muatan tersebut. Misalnya, jika Anda mengonfigurasi `aud: mobile-site`, maka bidang `aud` dalam muatan harus bernilai `mobile-site`.
claims_to_headers	array of object	Optional	-	Mengekstraksi bidang tertentu dari muatan JWT dan menetapkannya ke header permintaan yang ditentukan sebelum meneruskan ke backend.
from_headers	array of object	Optional	[{"name":"Authorization","value_prefix":"Bearer"}]	Mengekstraksi JWT dari header permintaan yang ditentukan.
from_params	array of string	Optional	access_token	Mengekstraksi JWT dari parameter URL yang ditentukan.
from_cookies	array of string	Optional	-	Mengekstraksi JWT dari cookie yang ditentukan.
clock_skew_seconds	number	Optional	60	Skew jam yang diizinkan dalam detik saat memverifikasi bidang `exp` dan `iat` pada JWT.
keep_token	bool	Optional	true	Apakah JWT tetap disertakan saat permintaan diteruskan ke backend.

Catatan

Nilai default hanya digunakan ketika from_headers, from_params, dan from_cookies tidak dikonfigurasi.

Tabel berikut menjelaskan bidang-bidang untuk setiap item dalam from_headers.

Name	Data type	Required	Default value	Description
name	string	Required	-	Header permintaan tempat JWT diekstraksi.
value_prefix	string	required	-	Awalan yang akan dihapus dari nilai header. Bagian yang tersisa dianggap sebagai JWT.

Tabel berikut menjelaskan bidang-bidang untuk setiap item dalam claims_to_headers.

Name	Data type	Required	Default value	Description
claim	string	Required	-	Bidang tertentu dalam muatan JWT. Nilainya harus berupa string atau bilangan bulat tak bertanda.
header	string	Required	-	Nilai bidang dari muatan yang akan ditetapkan ke header permintaan ini dan diteruskan ke backend.
override	bool	Optional	true	Jika true, menimpa header permintaan jika memiliki nama yang sama. Jika false, header permintaan duplikat akan ditambahkan.

Tabel berikut menjelaskan bidang-bidang untuk setiap item dalam remote_jwks.

Name	Data type	Required	Default value	Description
uri	string	Required	-	URL permintaan.
service	string	Required	-	Contoh untuk layanan Kubernetes: foo.default.svc.cluster.local. Contoh untuk layanan Nacos: foo.DEFAULT-GROUP.public.nacos. Untuk layanan DNS bernama test, masukkan test.dns. Untuk layanan IP statis bernama test, masukkan test.static.
port	bool	Required	-	Port layanan.
timeout	bool	Optional	3000	Timeout permintaan layanan dalam milidetik.
ttl	bool	Optional	30000	Durasi cache dalam milidetik.

Konfigurasi otorisasi (opsional)

Name	Data type	Required	Default value	Description
allow	array of string	Optional (not for instance-level configuration)	-	Hanya dapat dikonfigurasi pada aturan detail halus seperti rute atau nama domain. Menentukan konsumen yang diizinkan mengakses sumber daya untuk permintaan yang memenuhi kondisi pencocokan, sehingga memungkinkan kontrol akses detail halus.

Penting

Konfigurasi otorisasi dan autentikasi tidak dapat digunakan dalam aturan yang sama.
Untuk permintaan yang lolos autentikasi dan otorisasi, header X-Mse-Consumer ditambahkan ke permintaan untuk mengidentifikasi nama pemanggil.

Contoh konfigurasi

Konfigurasi autentikasi global dan otorisasi tingkat rute

Konfigurasi berikut mengaktifkan autentikasi dan otorisasi JWT untuk rute gateway atau nama domain tertentu.

Catatan

Jika JWT cocok dengan beberapa JWKS, konsumen pertama yang sesuai dalam urutan konfigurasi akan digunakan.

Konfigurasi plugin

Konfigurasikan plugin di tingkat instans sebagai berikut:

consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

Konfigurasi rute dan nama domain

Untuk rute route-a dan route-b, konfigurasikan plugin sebagai berikut:

allow:
- consumer1

Untuk nama domain *.example.com dan test.com, konfigurasikan plugin sebagai berikut:

allow:
- consumer2

Catatan

Dalam contoh ini, route-a dan route-b adalah nama rute yang dimasukkan saat Anda membuat rute gateway. Ketika permintaan cocok dengan rute-rute ini, pemanggil dengan nama consumer1 diizinkan mengakses. Pemanggil lain ditolak aksesnya.
Dalam contoh ini, *.example.com dan test.com digunakan untuk mencocokkan nama domain permintaan. Saat nama domain cocok, pemanggil dengan nama consumer2 diizinkan mengakses. Pemanggil lain ditolak aksesnya.

Contoh permintaan

Berdasarkan konfigurasi ini, permintaan berikut diizinkan. Contoh ini mengasumsikan permintaan cocok dengan rute `route-a`.

Setel JWT dalam parameter URL.

curl  'http://xxx.hello.com/test?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEy****.eyJpc3MiOiJhYmNkIiwic3ViIjoidGVzdCIsImlhdCI6MTY2NTY2MDUyNywiZXhwIjoxODY1NjczODE5fQ.-vBSV0bKeDwQcuS6eeSZN9dLTUnSnZVk8eVCXdooCQ4'

Setel JWT dalam header permintaan HTTP.

curl  http://xxx.hello.com/test -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCIsImtpZCI6IjEyMyJ9.eyJpc3MiOiJhYmNkIiwic3ViIjoidGVzdCIsImlhdCI6MTY2NTY2MDUyNywiZXhwIjoxODY1NjczODE5fQ.-vBSV0bKeDwQcuS6eeSZN9dLTUnSnZVk8eVCXdooCQ4'

Verifikasi hasil

Setelah autentikasi berhasil, header X-Mse-Consumer ditambahkan ke permintaan dengan nama pemanggil. Dalam contoh ini, nilainya adalah consumer1.

Permintaan berikut akan ditolak.

Permintaan tidak menyediakan JWT, sehingga mengembalikan error 401.
Pemanggil yang dicocokkan oleh JWT yang diberikan tidak memiliki izin akses, sehingga mengembalikan error 403.

Aktifkan di tingkat instans gateway tetapi nonaktifkan untuk rute tertentu

Konfigurasikan plugin di tingkat instans sebagai berikut:

global_auth: true
consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

Untuk rute route-b, konfigurasikan plugin sebagai berikut:

_disable_: true

Dalam contoh ini, route-b adalah nama rute yang dimasukkan saat Anda membuat rute gateway. Karena _disable_ diatur ke true, ketika permintaan cocok dengan rute ini, plugin dinonaktifkan. Tidak ada autentikasi JWT yang dilakukan, dan semua pengguna diizinkan mengakses.

Ketika permintaan tidak cocok dengan rute route-b, autentikasi JWT dilakukan karena global_auth diatur ke true dalam konfigurasi global, yang mengaktifkan autentikasi untuk semua permintaan. Baik consumer1 maupun consumer2 diizinkan mengakses.

Aktifkan di tingkat nama domain tetapi nonaktifkan untuk rute tertentu

Konfigurasikan plugin di tingkat instans sebagai berikut:

consumers:
- name: consumer1
  issuer: abcd
  jwks: |
    {
      "keys": [
        {
          "kty": "oct",
          "kid": "123",
          "k": "hM0k3AbXBPpKOGg__Ql2Obcq7s60myWDpbHXzgKUQdYo7YCRp0gUqkCnbGSvZ2rGEl4YFkKqIqW7mTHdj-bcqXpNr-NOznEyMpVPOIlqG_NWVC3dydBgcsIZIdD-MR2AQceEaxriPA_VmiUCwfwL2Bhs6_i7eolXoY11EapLQtutz0BV6ZxQQ4dYUmct--7PLNb4BWJyQeWu0QfbIthnvhYllyl2dgeLTEJT58wzFz5HeNMNz8ohY5K0XaKAe5cepryqoXLhA-V-O1OjSG8lCNdKS09OY6O0fkyweKEtuDfien5tHHSsHXoAxYEHPFcSRL4bFPLZ0orTt1_4zpyfew",
          "alg": "HS256"
        }
      ]
    }
- name: consumer2
  issuer: abc
  jwks: |
    {
      "keys": [
        {
          "kty": "RSA",
          "e": "AQAB",
          "use": "sig",
          "kid": "123",
          "alg": "RS256",
          "n": "i0B67f1jggT9QJlZ_8QL9QQ56LfurrqDhpuu8BxtVcfxrYmaXaCtqTn7OfCuca7cGHdrJIjq99rz890NmYFZuvhaZ-LMt2iyiSb9LZJAeJmHf7ecguXS_-4x3hvbsrgUDi9tlg7xxbqGYcrco3anmalAFxsbswtu2PAXLtTnUo6aYwZsWA6ksq4FL3-anPNL5oZUgIp3HGyhhLTLdlQcC83jzxbguOim-0OEz-N4fniTYRivK7MlibHKrJfO3xa_6whBS07HW4Ydc37ZN3Rx9Ov3ZyV0idFblU519nUdqp_inXj1eEpynlxH60Ys_aTU2POGZh_25KXGdF_ZC_MSRw"
        }
      ]
    }

Untuk rute route-b, konfigurasikan plugin sebagai berikut:

_disable_: true

Untuk nama domain *.example.com, konfigurasikan plugin sebagai berikut:

allow:
- consumer1
- consumer2

Dalam contoh ini, *.example.com digunakan untuk mencocokkan nama domain permintaan. Saat nama domain cocok, pemanggil dengan nama consumer1 atau consumer2 diizinkan mengakses. Pemanggil lain ditolak aksesnya.

Aturan konfigurasi dicocokkan secara berurutan. Ketika suatu aturan cocok, konfigurasinya dieksekusi dan aturan selanjutnya tidak dievaluasi. Pencocokan rute memiliki prioritas lebih tinggi daripada pencocokan nama domain, sehingga plugin dapat diaktifkan untuk suatu nama domain tetapi dinonaktifkan untuk rute tertentu di bawah nama domain tersebut.

Kode kesalahan terkait

HTTP status code	Error message	Cause
401	Jwt missing	Header permintaan tidak menyediakan JWT.
401	Jwt expired	JWT telah kedaluwarsa.
401	Jwt verification fails	Validasi muatan JWT gagal. Misalnya, `iss` tidak sesuai.
403	Access Denied	Tidak memiliki izin untuk mengakses rute saat ini.