Configure the jwt-auth plugin - API Gateway - Alibaba Cloud Dokümantasyon Merkezi

jwt-auth eklentisi, JSON Web Token (JWT) tabanlı istek kimlik doğrulama ve yetkilendirme işlemlerini gerçekleştirir. URL parametrelerinden, istek başlıklarından veya çerezlerden JWT ayrıştırır ve erişim izni vermek veya reddetmek için belirteci doğrular. JWT ile kimlik doğrulama ve yetkilendirme çözümünden farklı olarak bu eklenti, çağrı yapanları da tanımlayarak her biri için ayrı JWT kimlik bilgileri yapılandırmanıza olanak tanır.

Yapılandırma alanları

Kimlik doğrulama yapılandırması

Ad	Veri türü	Zorunluluk	Varsayılan değer	Açıklama
consumers	object dizisi	Zorunlu	-	İstek kimlik doğrulamasında kullanılan hizmet tüketicileri.
global_auth	Dize dizisi	İsteğe bağlı (yalnızca örnek düzeyinde yapılandırma)	-	Yalnızca örnek düzeyinde yapılandırılabilir. true olarak ayarlanırsa kimlik doğrulama genel olarak uygulanır. false olarak ayarlanırsa kimlik doğrulama yalnızca yapılandırılmış etki alanı adları ve rotalar için geçerli olur. Yapılandırılmazsa, geriye dönük uyumluluğu korumak amacıyla yalnızca etki alanı adı veya rota yapılandırması yoksa genel olarak uygulanır.

Aşağıdaki tabloda, consumers içindeki her bir öğenin alanları açıklanmaktadır.

Ad	Veri türü	Zorunluluk	Varsayılan değer	Açıklama
name	string	Zorunlu	-	Tüketici adı.
jwks	string	İsteğe bağlı. `jwks` veya `remote_jwks` alanlarından biri zorunludur.	-	JSON Web Key (JWK) standardında belirtilen JSON Web Key Set (JWKS) dizesi. JWT imzasını doğrulamak için kullanılan genel anahtarı veya simetrik anahtarı içerir.
remote_jwks	object	İsteğe bağlı. `jwks` veya `remote_jwks` alanlarından birini seçin.	{"uri":"http://127.0.0.1/keys","service":"test.static","port":"80","ttl":30000,"timeout":3000}	Belirtilen hizmet URI'sinden JWKS'i periyodik olarak çeker. Hem `jwks` hem de `remote_jwks` yapılandırılırsa uzaktan çekilen JWKS öncelik kazanır. Not `remote_jwks` tarafından döndürülen JWKS boyutu 1 MB'tan küçük olmalıdır. Boyut bu sınırı aşar ve hata oluşursa 88010006189 numaralı DingTalk grubuna katılın veya destek talebi oluşturun.
issuer	string	İsteğe bağlı	-	JWT yayıncısı. Payload'daki `iss` alanıyla eşleşmelidir.
claims	object	İsteğe bağlı	-	Payload'daki anahtar-değer çiftleriyle eşleşen ve birden fazla alanın payload ile uyumlu olduğunu doğrulamak için kullanılan anahtar-değer çiftleri. Örneğin, `aud: mobile-site` yapılandırırsanız payload'daki `aud` alanının değeri `mobile-site` olmalıdır.
claims_to_headers	object dizisi	İsteğe bağlı	-	Belirtilen JWT payload alanlarını çıkarır ve arka uca iletmeden önce bunları istek başlığı olarak ayarlar.
from_headers	object dizisi	İsteğe bağlı	[{"name":"Authorization","value_prefix":"Bearer"}]	JWT'yi belirtilen istek başlıklarından çıkarır.
from_params	dize dizisi	İsteğe bağlı	access_token	JWT'yi belirtilen URL parametrelerinden çıkarır.
from_cookies	dize dizisi	İsteğe bağlı	-	JWT'yi belirtilen çerezlerden çıkarır.
clock_skew_seconds	number	İsteğe bağlı	60	JWT'nin `exp` ve `iat` alanlarını doğrularken izin verilen saniye cinsinden saat farkı.
keep_token	bool	İsteğe bağlı	true	İstek arka uca iletilirken JWT'nin korunup korunmayacağını belirtir.

Not

Varsayılan değerler yalnızca from_headers, from_params ve from_cookies yapılandırılmadığında kullanılır.

Aşağıdaki tabloda, from_headers içindeki her bir öğenin alanları açıklanmaktadır.

Ad	Veri türü	Zorunluluk	Varsayılan değer	Açıklama
name	string	Zorunlu	-	JWT'nin çıkarıldığı istek başlığı.
value_prefix	string	Zorunlu	-	Başlık değerinden kaldırılacak ön ek. Kalan kısım JWT olarak kabul edilir.

Aşağıdaki tabloda, claims_to_headers içindeki her bir öğenin alanları açıklanmaktadır.

Ad	Veri türü	Zorunluluk	Varsayılan değer	Açıklama
claim	string	Zorunlu	-	JWT payload'unda belirtilen bir alan. Değer dize veya işaretsiz tam sayı olmalıdır.
header	string	Zorunlu	-	Çıkarılan claim değerinin atanacağı ve arka uca iletileceği istek başlığı.
override	bool	İsteğe bağlı	true	true ise aynı ada sahip istek başlığının üzerine yazar. false ise değeri yinelenen bir istek başlığı olarak ekler.

Aşağıdaki tabloda, remote_jwks içindeki her bir öğenin alanları açıklanmaktadır.

Ad	Veri türü	Zorunluluk	Varsayılan değer	Açıklama
uri	string	Zorunlu	-	İstek URL'si.
service	string	Zorunlu	-	Kubernetes hizmeti örneği: foo.default.svc.cluster.local. Nacos hizmeti örneği: foo.DEFAULT-GROUP.public.nacos. test adlı DNS hizmeti için test.dns girin. test adlı statik IP hizmeti için test.static girin.
port	bool	Zorunlu	-	Hizmet bağlantı noktası.
timeout	bool	İsteğe bağlı	3000	Milisaniye cinsinden hizmet isteği zaman aşımı.
ttl	bool	İsteğe bağlı	30000	Milisaniye cinsinden önbellek süresi.

Yetkilendirme yapılandırması (isteğe bağlı)

Ad	Veri türü	Zorunluluk	Varsayılan değer	Açıklama
allow	dize dizisi	İsteğe bağlı (örnek düzeyi yapılandırma için geçerli değil)	-	Yalnızca rotalar veya etki alanı adları gibi ayrıntılı kurallarda yapılandırılabilir. Eşleşen kaynağa hangi tüketicilerin erişebileceğini belirtir.

Önemli

Yetkilendirme ve kimlik doğrulama yapılandırmaları aynı kuralda birlikte kullanılamaz.
Kimlik doğrulama ve yetkilendirmeden geçen isteklere, çağrı yapanın adını tanımlamak için bir X-Mse-Consumer başlığı eklenir.

Yapılandırma örnekleri

Genel kimlik doğrulama ve rota düzeyinde yetkilendirme yapılandırma

Bu örnekte, örnek düzeyinde genel JWT kimlik doğrulaması etkinleştirilir ve rota düzeyindeki erişim belirli tüketicilerle sınırlandırılır.

Not

Bir JWT birden fazla JWKS ile eşleşebiliyorsa yapılandırma sırasındaki ilk eşleşen tüketici kullanılır.

Eklenti yapılandırması

Eklentiyi örnek düzeyinde aşağıdaki gibi yapılandırın:

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"
        }
      ]
    }

Rota ve etki alanı adı yapılandırması

route-a ve route-b rotaları için eklentiyi aşağıdaki gibi yapılandırın:

allow:
- consumer1

*.example.com ve test.com etki alanı adları için eklentiyi aşağıdaki gibi yapılandırın:

allow:
- consumer2

Not

Bu örnekte route-a ve route-b ağ geçidi rotalarını oluştururken girdiğiniz rota adlarıdır. İstek bu rotalarla eşleştiğinde adı consumer1 olan çağrı yapanlara erişim izni verilir. Diğer çağrı yapanların erişimi reddedilir.
Bu örnekte *.example.com ve test.com isteklerin etki alanı adıyla eşleştirilmesi için kullanılır. Etki alanı adı eşleştiğinde adı consumer2 olan çağrı yapanlara erişim izni verilir. Diğer çağrı yapanların erişimi reddedilir.

İstek örnekleri

Aşağıdaki istekler bu yapılandırma altında izin verilir. Bu örneklerde isteklerin route-a rotasıyla eşleştiği varsayılmaktadır.

JWT'yi URL parametresinde ayarlayın.

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

JWT'yi HTTP istek başlığında ayarlayın.

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

Sonucu doğrulama

Kimlik doğrulama başarılı olduktan sonra çağrı yapanın adını içeren X-Mse-Consumer başlığı isteğe eklenir. Bu örnekte değeri consumer1 olur.

Aşağıdaki istekler reddedilir.

İstek JWT sağlamadığından 401 hatası döndürülür.
Sağlanan JWT tarafından eşleştirilen çağrı yapanın erişim izni olmadığından 403 hatası döndürülür.

Ağ geçidi örnek düzeyinde etkinleştirme ancak belirli bir rota için devre dışı bırakma

Eklentiyi örnek düzeyinde aşağıdaki gibi yapılandırın:

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"
        }
      ]
    }

route-b rotası için eklentiyi aşağıdaki gibi yapılandırın:

_disable_: true

Bu örnekte route-b ağ geçidi rotasını oluştururken girdiğiniz rota adıdır. _disable_ değeri true olarak ayarlandığından istek bu rota ile eşleştiğinde eklenti devre dışı bırakılır. JWT kimlik doğrulaması gerçekleştirilmez ve tüm kullanıcıların erişimine izin verilir.

route-b rotasıyla eşleşmeyen istekler için örnek düzeyinde global_auth değeri true olarak ayarlandığından JWT kimlik doğrulaması gerçekleştirilir. Hem consumer1 hem de consumer2 tüketicilerine erişim izni verilir.

Etki alanı adı düzeyinde etkinleştirme ancak belirli bir rota için devre dışı bırakma

Eklentiyi örnek düzeyinde aşağıdaki gibi yapılandırın:

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"
        }
      ]
    }

route-b rotası için eklentiyi aşağıdaki gibi yapılandırın:

_disable_: true

*.example.com etki alanı adı için eklentiyi aşağıdaki gibi yapılandırın:

allow:
- consumer1
- consumer2

Bu örnekte *.example.com isteklerin etki alanı adıyla eşleştirilmesi için kullanılır. Etki alanı adı eşleştiğinde adı consumer1 veya consumer2 olan çağrı yapanlara erişim izni verilir. Diğer çağrı yapanların erişimi reddedilir.

Kurallar sırayla eşleştirilir: İlk eşleşme uygulanır ve diğer kurallar değerlendirilmez. Rota kuralları etki alanı adı kurallarına göre önceliklidir, bu nedenle bir etki alanı adı için eklentiyi etkinleştirip o etki alanı altındaki belirli bir rota için devre dışı bırakabilirsiniz.

İlgili hata kodları

HTTP durum kodu	Hata mesajı	Neden
401	Jwt missing	İstek başlığında JWT sağlanmamış.
401	Jwt expired	JWT'nin süresi dolmuş.
401	Jwt verification fails	JWT payload doğrulaması başarısız oldu. Örneğin, `iss` eşleşmiyor.
403	Access Denied	Mevcut rotaya erişim izni yok.