全部产品
Search

搜索本产品

    API Gateway：Gunakan otentikasi digest untuk memanggil API

    文档中心

    API Gateway：Gunakan otentikasi digest untuk memanggil API

    更新时间：Jun 28, 2025

    Untuk memanggil API yang menggunakan metode otentikasi digest (AppKey dan AppSecret), klien harus menghitung tanda tangan dari konten permintaan menggunakan pasangan kunci tanda tangan, lalu mengirimkan tanda tangan tersebut ke server untuk diverifikasi. SDK API Gateway menyertakan mekanisme tanda tangan. Setelah Anda mengonfigurasi pasangan kunci tanda tangan di SDK, Anda dapat memulai permintaan dengan tanda tangan yang valid. Topik ini menjelaskan cara menghitung tanda tangan pada klien.

    1. Ikhtisar

    API Gateway menyediakan fitur pembuatan dan verifikasi tanda tangan yang digunakan dalam skenario berikut:

    • Memeriksa validitas permintaan yang diterima dari klien untuk memastikan bahwa permintaan tersebut mencakup tanda tangan yang benar berdasarkan AppKey yang telah diberi otorisasi.

    • Mencegah permintaan dirusak selama transmisi.

    Penyedia API dapat membuat aplikasi di halaman Aplikasi pada Konsol API Gateway. Setiap aplikasi memiliki pasangan kunci tanda tangan yang terdiri dari AppKey dan AppSecret. Setelah penyedia API memberikan otorisasi kepada aplikasi untuk memanggil API, pemanggil API dapat menggunakan aplikasi dan pasangan kunci tanda tangan untuk memanggil API. Perhatikan bahwa aplikasi dapat diterbitkan oleh penyedia API atau dimiliki oleh pemanggil API.

    Saat klien memanggil API, klien harus menggunakan pasangan kunci tanda tangan yang diberi otorisasi untuk mengenkripsi dan menandatangani permintaan, menambahkan AppKey dan string tanda tangan ke header permintaan, lalu mengirimkan permintaan ke API Gateway. Setelah API Gateway menerima permintaan, API Gateway membaca AppKey dari header permintaan dan mendapatkan AppSecret yang sesuai. Kemudian, API Gateway menggunakan AppSecret untuk menghitung tanda tangan dari data kunci dalam permintaan dan membandingkan tanda tangan yang dihitung dengan tanda tangan dari klien untuk memverifikasi tanda tangan. Hanya permintaan yang lolos verifikasi tanda tangan yang dikirim ke layanan backend. Jika API Gateway menentukan bahwa permintaan tidak valid, API Gateway akan mengembalikan kesalahan.

    API Gateway hanya memverifikasi tanda tangan dalam permintaan untuk API yang nilai Otentikasi Keamanannya adalah Alibaba Cloud App.

    2. Pemanggilan API menggunakan SDK

    Untuk informasi lebih lanjut tentang cara menghitung tanda tangan, lihat SDK yang disediakan oleh API Gateway. Anda dapat mengunduh SDK untuk Java, Android, dan Objective-C yang dilengkapi dengan kode sumber di halaman berikut dalam Konsol API Gateway:

    • Open API > SDK

    • Panggil API > SDK API Resmi

    Untuk informasi lebih lanjut, lihat Gunakan SDK untuk Memanggil API.

    3. Prinsip otentikasi digest

    3.1. Pembuatan dan Verifikasi Tanda Tangan

    3.1.1. Prasyarat

    Pasangan kunci tanda tangan yang ditetapkan untuk API terkait diperoleh oleh pemanggil API sebelum pemanggil API memanggil API.

    • APP Key

    • APP Secret

    Nilai Otentikasi Keamanan dari API yang dipanggil adalah Alibaba Cloud App.

    3.1.2. Pembuatan Tanda Tangan di Klien

    Untuk menghasilkan tanda tangan, klien harus melakukan langkah-langkah berikut:

    1. Ekstrak data kunci dari permintaan untuk mendapatkan string tanda tangan.

    2. Gunakan algoritma enkripsi dan AppSecret untuk mengenkripsi string tanda tangan guna mendapatkan tanda tangan.

    3. Tambahkan semua header yang terkait dengan tanda tangan ke permintaan HTTP asli untuk mendapatkan permintaan HTTP akhir.

    3.1.3. Verifikasi Tanda Tangan di Server

    Untuk memverifikasi tanda tangan dari klien, server harus melakukan langkah-langkah berikut:

    1. Ekstrak data kunci dari permintaan yang diterima untuk mendapatkan string tanda tangan.

    2. Baca AppKey dari permintaan dan gunakan AppKey untuk mendapatkan AppSecret.

    3. Gunakan algoritma enkripsi dan AppSecret untuk mengenkripsi string tanda tangan guna mendapatkan tanda tangan.

    4. Baca tanda tangan sisi klien dari permintaan dan bandingkan tanda tangan sisi server dengan tanda tangan sisi klien.

    3.2. Pembuatan dan Transfer Tanda Tangan

    3.2.1. Ekstraksi String Tanda Tangan

    Klien harus mengekstrak data kunci dari permintaan HTTP dan menggabungkan data tersebut menjadi string tanda tangan. String tanda tangan berada dalam format berikut:

    HTTPMethod
Accept
Content-MD5
Content-Type
Date
Headers
PathAndParameters

    Bidang-bidang di atas membentuk string tanda tangan dan dipisahkan oleh \n. Jika Anda meninggalkan bidang Headers kosong, \n tidak diperlukan. Jika Anda meninggalkan bidang lainnya kosong, \n harus tetap ada. Tanda tangan bersifat peka huruf besar-kecil. Ekstraksi data untuk setiap bidang mengikuti aturan berikut:

    • HTTPMethod: Metode HTTP yang digunakan untuk mengirim permintaan, seperti POST. Nilai bidang ini dalam huruf besar.

    • Accept: Nilai header Accept dalam permintaan. Anda dapat meninggalkan header Accept kosong. Kami sarankan Anda menentukan header Accept dalam permintaan. Jika header Accept dibiarkan kosong, klien HTTP tertentu menggunakan nilai default */* untuk Accept. Dalam kasus ini, verifikasi tanda tangan gagal.

    • Content-MD5: Nilai header Content-MD5, yang dapat dibiarkan kosong.

      • Nilai dihitung hanya ketika permintaan berisi body tipe non-Form. Jika Content-MD5 tidak dihitung di sisi klien atau klien tidak meneruskannya ke API Gateway, API Gateway tidak memvalidasi Content-MD5.

      • Contoh berikut digunakan untuk menghitung nilai header Content-MD5 dalam Java:

    String content-MD5 = Base64.encodeBase64(MD5(bodyStream.getbytes("UTF-8")));

    • Content-Type: Nilai header Content-Type, yang dapat dibiarkan kosong.

    Penting

    Pengecualian Content-Type dapat terjadi karena logika dasar atau ketika klien menggunakan mini program untuk mentransfer file di WeChat. Dalam kasus ini, Anda dapat menambahkan X-Ca-Signed-Content-Type:multipart/form-data sebagai header Content-Type kustom ke permintaan Anda. Jika klien menggunakan header ini, API Gateway juga akan menggunakan header ini.

    • Date: Nilai header Date dalam permintaan, yang dapat dibiarkan kosong.

    • Headers: Anda dapat menentukan header untuk menghitung tanda tangan. Saat Anda menggabungkan string tanda tangan, aturan berikut berlaku:

      • Kunci header diurutkan secara alfabetis, lalu digabungkan berdasarkan aturan berikut:

      HeaderKey1 + ":" + HeaderValue1 + "\n" +
HeaderKey2 + ":" + HeaderValue2 + "\n" +
...
HeaderKeyN + ":" + HeaderValueN + "\n"

      • Jika nilai header kosong, gunakan HeaderKey + ":" + "\n" untuk tanda tangan dan pertahankan kunci header dan titik dua (:).

      • Kunci header yang digunakan untuk tanda tangan dipisahkan dengan koma (,) dan ditempatkan di header yang kuncinya adalah X-Ca-Signature-Headers.

      • Anda tidak dapat menggunakan header berikut untuk menghitung tanda tangan: X-Ca-Signature, X-Ca-Signature-Headers, Accept, Content-MD5, Content-Type, dan Date.

    • Bidang PathAndParameters berisi semua parameter dari jenis berikut: Path, Query, dan Form. 

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

      • Kunci parameter Query dan Form diurutkan secara alfabetis, lalu digabungkan menggunakan metode di atas.

      • Jika Anda meninggalkan parameter Query dan Form kosong, Anda dapat menggunakan parameter Path tanpa perlu menambahkan tanda tanya (?).

      • Jika parameter dibiarkan kosong, hanya kunci yang digunakan untuk tanda tangan.

      • Jika parameter Query dan Form memiliki parameter array dengan kunci yang sama tetapi nilai berbeda, nilai pertama digunakan untuk menghitung tanda tangan.

    Contoh berikut menunjukkan parameter dalam permintaan HTTP standar:

    POST /http2test/test?param1=test HTTP/1.1
host:api.aliyun.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
content-length:33
username=xiaoming&password=123456789

    String tanda tangan berikut dihasilkan untuk permintaan di atas:

    POST
application/json; charset=utf-8
application/x-www-form-urlencoded; charset=utf-8
Wed, 09 May 2018 13:30:29 GMT+00:00
x-ca-key:203753385
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-signature-method:HmacSHA256
x-ca-timestamp:1525872629832
/http2test/test?param1=test&password=123456789&username=xiaoming

    3.2.2. Perhitungan Tanda Tangan

    Setelah klien menggabungkan data kunci yang diekstraksi dari permintaan HTTP menjadi string tanda tangan, klien harus mengenkripsi dan mengkodekan string tanda tangan untuk menghasilkan tanda tangan akhir. API Gateway mendukung algoritma enkripsi berikut:

    • HmacSHA256

    • HmacSHA1

    Contoh berikut menunjukkan metode enkripsi, di mana stringToSign adalah string tanda tangan yang diekstraksi dan secret adalah AppSecret.

    Mac hmacSha256 = Mac.getInstance("HmacSHA256");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha256.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA256"));
byte[] md5Result = hmacSha256.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

    Mac hmacSha1 = Mac.getInstance("HmacSHA1");
byte[] appSecretBytes = appSecret.getBytes(Charset.forName("UTF-8"));
hmacSha1.init(new SecretKeySpec(appSecretBytes, 0, appSecretBytes.length, "HmacSHA1"));
byte[] md5Result = hmacSha1.doFinal(stringToSign.getBytes(Charset.forName("UTF-8")));
String signature = Base64.encodeBase64String(md5Result);

    Array Byte diperoleh setelah StringToSign didekode dalam UTF-8. Kemudian, Array Byte dienkripsi dan dikodekan dalam Base64 untuk menghasilkan tanda tangan akhir.

    3.2.3. Transfer Tanda Tangan

    Klien harus menyertakan beberapa atau semua header berikut dalam permintaan yang dikirim ke API Gateway untuk verifikasi tanda tangan:

    • x-ca-key: AppKey. Parameter ini wajib.

    • x-ca-signature-method: Metode tanda tangan. Parameter ini opsional. Nilai valid: HmacSHA256 dan HmacSHA1. Nilai default: HmacSHA256.

    • X-Ca-Signature-Headers: Kunci semua header tanda tangan. Parameter ini opsional. Pisahkan beberapa kunci dengan koma (,).

    • X-Ca-Signature: Tanda tangan. Parameter ini wajib.

    Contoh berikut menunjukkan permintaan HTTP yang memiliki tanda tangan:

    POST /http2test/test?param1=test HTTP/1.1
host:api.aliyun.com
accept:application/json; charset=utf-8
ca_version:1
content-type:application/x-www-form-urlencoded; charset=utf-8
x-ca-timestamp:1525872629832
date:Wed, 09 May 2018 13:30:29 GMT+00:00
user-agent:ALIYUN-ANDROID-DEMO
x-ca-nonce:c9f15cbf-f4ac-4a6c-b54d-f51abf4b5b44
x-ca-key:203753385
x-ca-signature-method:HmacSHA256
x-ca-signature-headers:x-ca-timestamp,x-ca-key,x-ca-nonce,x-ca-signature-method
x-ca-signature:xfX+bZxY2yl7EB/qdoDy9v/uscw3Nnj1pgoU+Bm6xdM=
content-length:33
username=xiaoming&password=123456789

    3.3. Pemecahan Masalah

    Jika verifikasi tanda tangan gagal, API Gateway menambahkan string tanda tangan sisi server (StringToSign) ke header respons HTTP yang dikembalikan ke klien. Kuncinya adalah X-Ca-Error-Message. Anda dapat mengidentifikasi kesalahan saat membandingkan string tanda tangan sisi klien (StringToSign) dengan string tanda tangan sisi server.

    Jika kedua nilai tersebut sama, periksa AppSecret yang digunakan untuk menghitung tanda tangan.

    Header HTTP tidak mendukung jeda baris. Jeda baris dalam string tanda tangan (StringToSign) diganti dengan tanda pagar (#).

    errorMessage:  Invalid Signature, Server StringToSign:`GET#application/json##application/json##X-Ca-Key:200000#X-Ca-Timestamp:1589458000000#/app/v1/config/keys?keys=TEST`

    Contoh berikut menunjukkan string tanda tangan sisi server:

    GET
application/json
application/json
X-Ca-Key:200000
X-Ca-Timestamp:1589458000000
/app/v1/config/keys?keys=TEST