Tüm Ürünler
Search

Bu Ürün

    API Gateway:key-auth Eklentisi

    Belge Merkezi

    API Gateway:key-auth Eklentisi

    Son Güncelleme:Oct 04, 2026

    key-auth eklentisi, API anahtarlarını URL parametrelerinden veya HTTP üst bilgilerinden ayrıştırıp erişim izinlerini doğrulayarak isteklerin kimliğini doğrular.

    API anahtarı (kimlik bilgisi) edinin

    Her çağırıcı, eklenti yapılandırmasında tanımladığınız bir dize anahtarı olan credential değeriyle kimlik doğrular. Konsol uygulaması gerekmez.

    Bir credential tanımlarken aşağıdaki kurallara uyun:

    • Örneğin UUID biçiminde 32 veya daha fazla karakterden oluşan rastgele bir dize kullanın: 2bda943c-ba2b-11ec-ba07-00163e125d8f

    • Anahtarı güvenli tutun. İstemci tarafı kodunda veya genel belgelerde paylaşmayın.

    • Birden çok çağırıcıya farklı izinler atamak için her biri için benzersiz bir credential tanımlayın ve bunları consumers alanında yapılandırın.

    Eklenti türü

    Kimlik doğrulama ve yetkilendirme.

    Alanlar

    Kimlik doğrulama yapılandırması


    Yapılandırma öğesi


    Veri türü


    Gerekli


    Varsayılan değer


    Açıklama


    consumers


    nesne dizisi


    Evet


    -


    İstek kimlik doğrulaması için hizmet çağrıları.


    keys


    dize dizisi


    Evet


    -


    API anahtarlarının çıkarılacağı URL parametrelerinin veya HTTP üst bilgilerinin adları.


    in_query


    bool


    in_query ve in_header alanlarından en az biri true olarak ayarlanmalıdır.


    true


    true olarak ayarlandığında ağ geçidi, API anahtarlarını URL parametrelerinden ayrıştırır.


    in_header


    bool


    in_query ve in_header alanlarından en az biri true olarak ayarlanmalıdır.


    true


    true olarak ayarlandığında ağ geçidi, API anahtarlarını HTTP üst bilgilerinden ayrıştırır.


    global_auth


    dize dizisi


    Hayır (Yalnızca örnek düzeyi yapılandırmalar için gereklidir)


    -


    Yalnızca örnek düzeyi. True ise kimlik doğrulama genel olarak uygulanır. False ise kimlik doğrulama yalnızca yapılandırılmış etki alanları ve rotalara uygulanır. Ayarlanmazsa global kimlik doğrulama yalnızca hiçbir etki alanı veya rota yapılandırılmadığında etkinleşir.

    consumers nesnesindeki alanlar:


    Yapılandırma öğesi


    Veri türü


    Gerekli


    Varsayılan değer


    Açıklama


    credential


    dize


    Evet


    -


    Tüketici için erişim kimlik bilgisi.


    name


    dize


    Evet


    -


    Tüketici adı.

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


    Yapılandırma öğesi


    Veri türü


    Gerekli


    Varsayılan değer


    Açıklama


    allow


    dize dizisi


    Hayır (Örnek dışı düzey yapılandırmalar için gereklidir)


    -


    Yalnızca rota veya etki alanı düzeyi. Eşleşen isteklere erişmesine izin verilen tüketicileri listeler.
    Önemli

    • Yetkilendirme ve kimlik doğrulama yapılandırmaları tek bir kuralda birlikte bulunamaz.

    • Kimliği doğrulanmış istekler için, çağrıyı tanımlamak amacıyla bir X-Mse-Consumer üst bilgisi eklenir.

    Örnek

    Rota düzeyi yetkilendirme ile global kimlik doğrulama

    Bu örnekte kimlik doğrulama örnek düzeyinde; yetkilendirme ise rota ve etki alanı düzeyinde yapılandırılır. Her credential değeri benzersiz olmalıdır.

    Örnek düzeyi eklenti yapılandırması:

    global_auth: false
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e125***
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc40***
  name: consumer2
keys:
- apikey
- x-api-key

    route-a ve route-b rotaları için eklenti yapılandırması:

    allow:
- consumer1

    *.example.com ve test.com etki alanları için eklenti yapılandırması:

    allow:
- consumer2
    Not

    • Bir istek route-a veya route-b ile eşleştiğinde yalnızca name değeri consumer1 olarak ayarlanmış olan çağırıcının erişimine izin verilir.

    • Bir istek *.example.com veya test.com ile eşleştiğinde yalnızca name değeri consumer2 olarak ayarlanmış olan çağırıcının erişimine izin verilir.

    İzin verilen istekler (route-a rotasıyla eşleşen):

    • URL parametresinde API anahtarı:

      curl  http://xxx.hello.com/test?apikey=2bda943c-ba2b-11ec-ba07-00163e1***

    • HTTP üst bilgisinde API anahtarı:

      curl  http://xxx.hello.com/test -H 'x-api-key: 2bda943c-ba2b-11ec-ba07-00163e1***'

    Kimlik doğrulama başarılı olduktan sonra X-Mse-Consumer üst bilgisi çağırıyı tanımlar. Bu örnekte değer consumer1 olur.

    Reddedilen istekler:

    • API anahtarı sağlanmamış. HTTP 401 döndürür.

      curl  http://xxx.hello.com/test

    • Geçersiz API anahtarı. HTTP 401 döndürür.

      curl  http://xxx.hello.com/test?apikey=926d90ac-ba2e-11ec-ab68-00163e1***

    • Eşleşen çağırıcının erişim izni yok. HTTP 403 döndürür.

      # The caller consumer2 is not in the whitelist of route-a.
curl  http://xxx.hello.com/test?apikey=c8c8e9ca-558e-4a2d-bb62-e700dcc***

    Ağ geçidi genelinde kimlik doğrulamayı etkinleştirin

    Aşağıdaki örnek düzeyi yapılandırmayla tüm istekler key-auth kimlik doğrulaması gerektirir.

    global_auth: true
consumers:
- credential: 2bda943c-ba2b-11ec-ba07-00163e1***
  name: consumer1
- credential: c8c8e9ca-558e-4a2d-bb62-e700dcc***
  name: consumer2
keys:
- apikey
- x-api-key

    Hata kodları


    HTTP durum kodu


    Hata mesajı


    Neden


    401


    No API key found in request.


    İstekte API anahtarı yok.


    401


    Request denied by Key Auth check. Invalid API key.


    API anahtarı geçerli değil.


    403


    Request denied by Key Auth check. Unauthorized consumer.


    Çağırıcının erişim izni yok.