Akses API Aman dengan Plugin OAuth 2.0 & Token JWT - API Gateway

Plugin OAuth digunakan untuk menerbitkan token akses OAuth 2.0 berdasarkan JSON Web Tokens (JWTs). Plugin ini mematuhi spesifikasi RFC9068. Dokumen ini menjelaskan cara mengonfigurasi Plugin OAuth.

Jenis plugin

Plugin untuk otentikasi dan otorisasi.

Deskripsi konfigurasi

Bidang

Konfigurasi otorisasi

Bidang	Tipe data	Diperlukan	Nilai default	Deskripsi
konsumen	array of object	Ya	-	Nama konsumen yang merupakan pemanggil layanan. Bidang ini digunakan untuk mengotentikasi permintaan.
penerbit	string	Tidak	Higress-Gateway	Penerbit JWT.
auth_path	string	Tidak	/oauth2/token	Akhiran jalur yang ditentukan. Akhiran ini digunakan untuk menerbitkan token. Saat Anda mengonfigurasi bidang ini di tingkat rute, Anda harus memastikan bahwa rute yang ditentukan dapat dicocokkan. Saat Anda menggunakan fitur manajemen API untuk membuat API, Anda harus membuat API dengan jalur yang sama.
kredensial_global	bool	Tidak	true	Menentukan apakah akan menggunakan kredensial yang diterbitkan oleh rute apa pun untuk akses jika otentikasi konsumen berhasil.
auth_header_name	string	Tidak	Authorization	Header permintaan dari mana Anda bisa mendapatkan JWT.
token_ttl	number	Tidak	7.200	Durasi waktu hidup (TTL) token setelah diterbitkan. Unit: detik.
clock_skew_seconds	number	Tidak	60	Penyimpangan waktu yang diizinkan saat memverifikasi bidang exp dan iat dalam JWT. Unit: detik.
keep_token	bool	Tidak	true	Menentukan apakah akan menyimpan JWT dalam permintaan saat permintaan diteruskan ke layanan backend.
global_auth	array of string	Tidak (Diperlukan hanya untuk konfigurasi tingkat instance)	-	Bidang ini hanya dapat dikonfigurasi di tingkat instance. Jika bidang ini disetel ke true, mekanisme otentikasi secara global berlaku. Jika bidang ini disetel ke false, mekanisme otentikasi hanya berlaku untuk nama domain dan rute yang dikonfigurasi. Jika bidang ini tidak dikonfigurasi, mekanisme otentikasi secara global hanya berlaku ketika tidak ada nama domain dan rute yang dikonfigurasi. Ini mempertimbangkan kebiasaan pengguna lama.

Tabel berikut menjelaskan bidang dalam konsumen.

Bidang	Tipe data	Diperlukan	Nilai default	Deskripsi
nama	string	Ya	-	Nama konsumen.
client_id	string	Ya	-	ID klien OAuth 2.0.
client_secret	string	Ya	-	Rahasia klien OAuth 2.0.

Penting

Untuk rute dengan konfigurasi sebelumnya diaktifkan, jika akhiran jalur dan auth_path cocok, sistem tidak meneruskan informasi rute ke layanan tujuan, tetapi menggunakan rute tersebut untuk menghasilkan token.
Jika bidang global_credentials disetel ke false, pastikan bahwa rute dengan plugin yang diaktifkan tidak menggunakan pencocokan eksak. Jika rute lain ada dan menggunakan pencocokan awalan, masalah tak terduga dapat terjadi.
Untuk permintaan yang telah diautentikasi, bidang X-Mse-Consumer ditambahkan ke header permintaan untuk mengidentifikasi nama pemanggil.

(Opsional) Konfigurasi otorisasi

Bidang	Tipe data	Diperlukan	Nilai default	Deskripsi
allow	array of string	Tidak (Diperlukan untuk konfigurasi non-tingkat instance)	-	Anda hanya dapat mengonfigurasi bidang ini pada granularitas halus seperti rute atau nama domain. Untuk permintaan yang memenuhi kondisi pencocokan, Anda dapat mengonfigurasi konsumen yang diizinkan untuk akses. Ini mengimplementasikan kontrol izin granularitas halus.

Penting

Konfigurasi otorisasi dan konfigurasi otentikasi tidak dapat berkoeksistensi dalam aturan.

Contoh

Konfigurasi otorisasi tingkat rute

Terapkan konfigurasi plugin berikut ke rute route-a dan route-b:

konsumen:
- nama: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Meskipun konfigurasi yang sama digunakan, kredensial yang diterbitkan oleh route-a tidak dapat digunakan untuk mengakses route-b, dan sebaliknya.

Untuk berbagi izin akses kredensial berdasarkan konfigurasi yang sama, Anda dapat menerapkan konfigurasi berikut:

global_credentials: true
konsumen:
- nama: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Konfigurasi otorisasi global dan konfigurasi otentikasi tingkat rute

Konfigurasi berikut mengaktifkan otentikasi JWT untuk rute atau nama domain tertentu dari gateway. Jika JWT cocok dengan beberapa JSON Web Key Sets (JWKSs), konsumen pertama yang cocok akan dipilih berdasarkan urutan konfigurasi.

Terapkan konfigurasi plugin berikut di tingkat instance:

global_auth: false
konsumen:
- nama: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- nama: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Terapkan konfigurasi plugin berikut ke rute route-a dan route-b:

allow:
- consumer1

Terapkan konfigurasi plugin berikut ke nama domain *.example.com dan test.com:

allow:
- consumer2

Catatan

Dalam contoh ini, rute route-a dan route-b adalah yang ditentukan saat pembuatan rute gateway. Jika permintaan klien cocok dengan dua rute tersebut, pemanggil dengan nama consumer1 diizinkan untuk mengakses gateway. Pemanggil lainnya tidak diizinkan mengakses gateway.
Dalam contoh ini, nama domain *.example.com dan test.com digunakan untuk mencocokkan nama domain dalam permintaan. Jika permintaan klien cocok dengan dua nama domain tersebut, pemanggil dengan nama consumer2 diizinkan untuk mengakses gateway. Pemanggil lainnya tidak diizinkan mengakses gateway.

Aktifkan otentikasi di tingkat gateway

Konfigurasi berikut mengaktifkan otentikasi OAuth2 di tingkat gateway. Semua permintaan harus diautentikasi sebelum mengakses gateway.

global_auth: true
konsumen:
- nama: consumer1
  client_id: 12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx
- nama: consumer2
  client_id: 87654321-xxxx-xxxx-xxxx-xxxxxxxxxxxx
  client_secret: hgfedcba-xxxx-xxxx-xxxx-xxxxxxxxxxxx

Permintaan sampel

Gunakan tipe grant Client Credential

Peroleh token akses

# Peroleh token akses menggunakan metode GET. Kami merekomendasikan Anda menggunakan metode ini.
curl 'http://test.com/oauth2/token?grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Peroleh token akses menggunakan metode POST. Untuk melakukan operasi ini, Anda perlu mencocokkan rute yang menunjuk ke layanan tujuan nyata. Jika tidak, gateway tidak membaca body permintaan.
curl 'http://test.com/oauth2/token' -H 'content-type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=12345678-xxxx-xxxx-xxxx-xxxxxxxxxxxx&client_secret=abcdefgh-xxxx-xxxx-xxxx-xxxxxxxxxxxx'

# Peroleh nilai bidang access_token dari respons.
{
  "token_type": "bearer",
  "access_token": "eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0",
  "expires_in": 7200
}

Gunakan token akses untuk memulai permintaan

curl 'http://test.com' -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6ImFwcGxpY2F0aW9uXC9hdCtqd3QifQ.eyJhdWQiOiJkZWZhdWx0IiwiY2xpZW50X2lkIjoiMTIzNDU2NzgteHh4eC14eHh4LXh4eHgteHh4eHh4eHh4eHh4IiwiZXhwIjoxNjg3OTUxNDYzLCJpYXQiOjE2ODc5NDQyNjMsImlzcyI6IkhpZ3Jlc3MtR2F0ZXdheSIsImp0aSI6IjEwOTU5ZDFiLThkNjEtNGRlYy1iZWE3LTk0ODEwMzc1YjYzYyIsInN1YiI6ImNvbnN1bWVyMSJ9.NkT_rG3DcV9543vBQgneVqoGfIhVeOuUBwLJJ4Wycb0'

Kode kesalahan

Kode status HTTP	Pesan kesalahan	Alasan
401	Invalid Jwt token.	Tidak ada JWT yang disediakan dalam header permintaan, format JWT tidak valid, atau JWT telah kedaluwarsa.
403	Access Denied.	Konsumen tidak memiliki izin untuk mengakses rute saat ini.