Tüm Ürünler
Search
Belge Merkezi

API Gateway:Arka uç imza eklentisi

Son Güncelleme:Oct 04, 2026

Arka uç imza anahtarı, oluşturduğunuz bir anahtar ve gizli dizi çiftidir. Bu çift, API Gateway için kimlik bilgisi olarak işlev görür. Arka uç imza eklentisini bir API'ye ekledikten sonra API Gateway, istekleri arka uç hizmetinize göndermeden önce bu anahtar ve gizli diziyi kullanarak imzalar. Arka uç hizmetiniz gelen istekte simetrik imza hesaplaması yapabilir. Sunucunuzun hesapladığı imza ile ağ geçidinin imzasını karşılaştırarak ağ geçidini doğrulayabilirsiniz.

1. Arka uç imzası nedir

Arka Uç İmzası (eskiden İmza Anahtarı olarak bilinirdi), oluşturduğunuz bir Anahtar ve Gizli Dizi çiftidir. Bu çift, ağ geçidine sağladığınız bir kimlik bilgisi olarak işlev görür. Ağ geçidi arka uç hizmetinize istek gönderdiğinde bir imza hesaplar ve bunu istekle birlikte iletir. Arka uç hizmetiniz ilgili dize üzerinde simetrik hesaplama yaparak ağ geçidinin kimliğini doğrulayabilir. Arka uç hizmetiniz bir VPC içindeyse ve ağ geçidine özel bir ağ üzerinden bağlanıyorsa (örneğin, özel bir VPC ortamındaki API'ler için) kanal güvenli olduğundan arka uç imzası gerekli değildir.

Orijinal imza anahtarı özelliği artık eklenti sistemine entegre edilmiştir. Mevcut konsol arayüzü ve API'ler kullanılmaya devam edilmektedir. Orijinal imza anahtarı özelliği ile arka uç imza eklentisi aynı türde eklentilerdir ve aynı ekleme kısıtlamalarına tabidir.

Orijinal imza anahtarı özelliği için API veya konsol kullanılarak yapılan değişiklikler eklenti sistemiyle senkronize edilir. Ancak uzaktan senkronizasyon desteklenmez.

2. Eklenti ekleme

Bir API'ye anahtar ekledikten sonra ağ geçidi, o API için arka uç hizmetine gönderilen tüm isteklere imza bilgilerini dahil eder. Arka ucunuzun imzayı doğrulamak ve ağ geçidinin kimliğini doğrulamak için simetrik hesaplama yapması gerekir.

Bir API için anahtarı değiştirmek üzere eklentideki anahtar ve gizli diziyi doğrudan değiştirebilirsiniz. Değişiklikler eklenen tüm API'ler için anında etkili olur.

3. Eklenti yapılandırma

Eklentiyi JSON veya YAML formatını kullanarak yapılandırabilirsiniz. Her iki format da aynı şemayı kullanır ve bunlar arasında geçiş yapmak için YAML'den JSON'a dönüştürücü kullanabilirsiniz. Aşağıdaki kod bloğu YAML formatında bir şablon göstermektedir:

---
type: APIGW_BACKEND
key: SampleKey
secret: SampleSecret
isGenerateContentSha256Header: false   # (Optional) Specifies whether to add "x-ca-signed-payload" from the client request to the signature header. Default: false.                   

4. API Gateway imzasını okuma

Ağ geçidi tarafından hesaplanan imza X-Ca-Proxy-Signature istek başlığında saklanır.

5. Arka uç imza kuralları

İmza hesaplamasına ilişkin ayrıntılı bir Java demosu için https://github.com/aliyun/api-gateway-demo-sign-backend-java adresindeki örnek koda bakın.

İmza hesaplama prosedürü aşağıdaki gibidir:

  1. API Gateway arka uca gönderilen HTTP isteğinden belirli verileri çıkarır ve bu verileri imzalanacak bir dize halinde birleştirir. İmzalanacak dizenin formatı aşağıdaki gibidir:

    HTTPMethod
    Content-MD5
    Headers
    PathAndParameters

    Bu dört alan satır beslemeleri (\n) ile ayrılmış olarak imzalanacak dizeyi oluşturur. Boş alanlar için bile satır besleme ayırıcısını eklemeniz gerekir; tek istisna şudur: Headers alanı boşsa sonrasında satır besleme eklemeyin. İmza büyük/küçük harfe duyarlıdır. Her bir alanın çıkarılmasına ilişkin kurallar aşağıda açıklanmıştır:

    • HTTPMethod: Büyük harfle yazılmış HTTP yöntemi, örneğin POST.

    • Content-MD5: Ağ geçidi istemci isteğinden Content-MD5 başlığının değerini okur. İstemci bu başlığı göndermezse imzalanacak dizedeki Content-MD5 değeri boş olur. İstemci yalnızca istek form kodlu olmayan bir gövdeye sahip olduğunda Content-MD5 başlığını hesaplayıp göndermelidir. Aşağıdaki Java kodu Content-MD5 değerinin nasıl hesaplanacağını göstermektedir:

      String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getBytes("UTF-8")));
    • Headers: Bu alan imza hesaplamasının parçası olan tüm başlık anahtarlarını ve değerlerini içerir. İmzaya dahil edilecek başlıkların anahtarları birden fazla anahtarın virgülle ayrıldığı X-Ca-Proxy-Signature-Headers istek başlığından okunur. Bu dize bölümünü oluşturmak için önce imza hesaplamasına dahil edilen tüm başlık anahtarlarını alfabetik olarak sıralayın. Ardından başlık anahtarlarını küçük harfe dönüştürün ve anahtarları ile değerleri aşağıdaki gibi birleştirin:

      String headers = HeaderKey1.toLowerCase() + ":" + HeaderValue1 +"\n"+
       HeaderKey2.toLowerCase() + ":" + HeaderValue2 +"\n"+
       ... +
      HeaderKeyN.toLowerCase() + ":" + HeaderValueN + "\n"
    • PathAndParameters

      Bu alan yolu ve sorgu ile formdaki tüm parametreleri içerir. Bu dizeyi oluşturmak için herhangi bir sorgu veya form parametresi varsa yola bir ? ekleyin. Ardından tüm sorgu ve form parametrelerinin anahtarlarını alfabetik olarak sıralayın ve aşağıda gösterildiği gibi birleştirin. Sorgu veya form parametresi yoksa PathAndParameters sadece yoldan oluşur.

      String PathAndParameters =
       Path +
       "?" +
       Key1 + "=" + Value1 
      + "&" + Key2 + "=" + Value2 +
       ... 
      "&" + KeyN + "=" + ValueN
      Not

      Bir sorgu veya form parametresinin birden fazla değeri olabilir. Bir parametrenin birden fazla değeri varsa imza hesaplamasında yalnızca ilk değer kullanılır. Bir parametre mevcutsa değeri boş olsa bile eşittir işareti (=) imzalanacak dizeye dahil edilmelidir. Örneğin sorgu dizesi path?a=&b ise imza hesaplaması için path?a=&b= şeklinde yazılmalıdır.

  2. İmzayı hesaplayın:

    Mac hmacSha256 = Mac.getInstance("HmacSHA256");
    byte[] keyBytes = secret.getBytes("UTF-8");  // secret is the signature key attached to the API
    hmacSha256.init(new SecretKeySpec(keyBytes, 0, keyBytes.length, "HmacSHA256"));
    String sign = new String(Base64.encodeBase64(hmacSha256.doFinal(stringToSign.getBytes("UTF-8"))),"UTF-8");

    Son imza imzalanacak dizenin (StringToSign) UTF-8 kullanılarak bir byte dizisine kodlanması, elde edilen byte dizisinin bir şifreleme algoritmasıyla şifrelenmesi ve ardından şifrelenmiş sonucun Base64 algoritması kullanılarak kodlanmasıyla oluşturulur.

6. Hata ayıklama modu

Arka uç imza entegrasyonunu ve testini basitleştirmek için API Gateway'e gönderdiğiniz isteğe X-Ca-Request-Mode: debug başlığını ekleyerek hata ayıklama modunu etkinleştirebilirsiniz.

Arka uç hizmetiniz daha sonra X-Ca-Proxy-Signature-String-To-Sign başlığını okuyabilir. HTTP başlıklarında satır beslemelerine izin verilmediği için bu başlıktaki satır besleme karakterlerinin yerine # konulur.

Önemli

X-Ca-Proxy-Signature-String-To-Sign arka uç imza hesaplamasına dahil edilmez.

7. Zaman damgası doğrulama

Arka ucunuzun zaman damgası doğrulaması yapması gerekiyorsa API tanımında CaRequestHandleTime sistem parametresini seçebilirsiniz. Bu parametre ağ geçidinin isteği aldığı UTC saatini sağlar.