HMACSHA256 Kimlik Doğrulama

iyzico hizmetlerindeki kimlik doğrulama, Base64 ve HmacSHA256 hashleme dahil olmak üzere hassas bir şifreleme teknikleri dizisi aracılığıyla güvenliği artırır.

API'ımıza güvenli bir şekilde erişmek için kimlik doğrulama gereklidir. Kimlik doğrulama, API Anahtarı ve base64EncodedAuthorization'ın HTTP isteklerinizin başlığına dahil edilmesiyle gerçekleştirilir.

"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"

Örnek İstek Başlığı:

POST /payment/bin/check HTTP/1.1
Host: sandbox-api.iyzipay.com
Authorization: IYZWSv2 YXBpS2V5OnNhbmRib3gtbDlNZDFHajNJWWNtdTROZGFXeGFTVW9Db1g3REM1UkEmcmFuZG9tS2V5OjEyMzQ1Njc4OSZzaWduYXR1cmU6MDc5ZGY0YjI0MjZmYzdmNDIwOGQ4ZjIyZmJjMDM0OTc5NDAxOWY4Y2UyYjA3MTFkZTc4MDhiNDg3NGY0ZTc5Ng==
Content-Type: application/json
x-iyzi-rnd: 123456789 //x-iyzi-rnd SHA1 Authentication sisteminden kalan bir random key'dir.

Genel Bakış

İşte gerekli bileşenlerin ayrıntılı bir açıklaması:

• apiKey : Hesabınıza atanmış benzersiz API anahtarı

• secretKey : Hesabınızla ilişkili gizli anahtarınız.

• x-iyz-rnd: Her API çağrısı için istek başlığına eklenen, müşterilerimiz tarafından rastgele oluşturulmuş bir sayı.(x-iyzi-rnd SHA1 Authentication sisteminden kalan bir random key'dir.)

• encryptedData: istek verisi içerisinde yer alan parametrelerin HMACSHA256 ile şifrelenmiş versiyonu.

Kimlik doğrulama tek bir adımda basitçe yapılır. Ancak bir Yetkilendirme Dizisi oluşturmak için üç adım vardır.

1. encryptedData

2. base64Encoded

3. Kimlik Doğrulama

1. encryptedData

encryptedData istek yükünün şifrelenmiş bir versiyonunu ifade eder. Sürecin sonunda HMACSHA256 şifrelemesini kullanarak bir hash oluşturulur.

Kimlik doğrulamada kullanılacak imza, nispeten aşağıdaki formül kullanılarak oluşturulur;

HMACSHA256(randomKey + uri.path + request.body, secretKey)

randomKey;

• olarak eski SHA1 Authentication sisteminden kalan x-iyzi-rnd de kullanabilirsiniz.

• Ya da random bir randomKey yaratabilirsiniz.

Aşağıdaki örnekte, Bin Sorgulama işlemine ait bir istek yapısı bulunmaktadır;

curl 
--location --request POST 'https://api.iyzipay.com/payment/bin/check' \
--header 'Authorization: IYZWSv2 ***' \
--header 'x-iyzi-rnd: 123456789' \
--header 'Content-Type: application/json' \
--data-raw '{
    "locale":"tr",
    "binNumber":"535805",
    "conversationId": "docsTest-v1"
}'

Yukarıdaki istek için encryptedData aşağıdaki gibidir;

079df4b2426fc7f4208d8f22fbc0349794019f8ce2b0711de7808b4874f4e796

2. base64Encoded

encryptedData 'nın doğru bir şekilde oluşturulduğunu varsayarsak, şimdi Base64 şifrelemesine geçebiliriz.

Kimlik doğrulamada kullanılacak imza, nispeten aşağıdaki formül kullanılarak oluşturulur;

base64("apiKey:"+apiKey+"&randomKey:"+randomKey+"&signature:"+encryptedData)

Sonuç olarak istek başlığında kullanılacak base64EncodedAuthorization değişkenini elde ederiz.

3. Authorization

Bütün bu işlemlerden sonra, son ve en kolay adım olarak istek başlığına IYZWSv2 base64EncodedAuthorization eklemeliyiz.

...
"Authorization": "IYZWSv2"+" "+"base64EncodedAuthorization"
...

IYZWSv2 ve base64EncodedAuthorization arasında bir adet boşluk bulunmaktadır.

Kimlik Doğrulama İçin Örnek Pre-Request Kodu

Örnek olarak test ortamında gerçekleşen Bin Sorgulama talebini ele alırsak yetkilendirme süreci şu şekilde olacaktır;

var apiKey = environment.apiKey;
var secretKey = environment.secretKey;
 
//Generate authorization string
function generateAuthorizationString() {

    // Benzersiz bir randomKey ortaya çıkaralım
    // Örnek randomKey : 1722246017090123456789
    var randomKey = new Date().getTime() + "123456789";
    
    // İstek için uri_path değişkenini yerleştirelim.
    // Örnek uri_path : /payment/bin/check
    var uri_path = "/payment/bin/check";
    
    // payload'u alalım ve uri path ile randomKey'i birleştirelim.
    // Örnek payload : payload: 1722246017090123456789/payment/bin/check{"binNumber":"589004"}
    var payload = _.isEmpty(request.data) ? randomKey + uri_path : randomKey + uri_path + request.data;
    
    // HMACSHA256 kullanarak payload'u şifreleyelim.
    // Örnek encryptedData : 91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9
    var encryptedData = CryptoJS.HmacSHA256(payload, secretKey);
 
    // encryptedData değişkenini kullanarak authorizationString oluşturalım.
    /* Örnek authorizationString : apiKey:sandbox-3uHv0LccjcWDyFHTvJpiACKPcJwbczmZ&
                                        randomKey:1722246017090123456789&
                                        signature:91e491486d3aa951b4f387cc93d67fc754c4729af95344b694435f56447819e9 */
    var authorizationString = "apiKey:" + apiKey
                        + "&randomKey:" + randomKey
                        + "&signature:" + encryptedData;
    
 
    // base64 kullanarak authorizationString'i şifreleyelim.
    // Örnek base64EncodedAuthorization : YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    var base64EncodedAuthorization = CryptoJS.enc.Base64.stringify(CryptoJS.enc.Utf8.parse(authorizationString));
 
    // authorizationStrin'i  'IYZWSv2 ' string'ine ekleyelim.
    // Örnek return value : IYZWSv2 YXBpS2V5OnNhbmRib3gtM3VIdjBMY2NqY1dEeUZIVHZKcGlBQ0tQY0p3YmN6bVomcmFuZG9tS2V5OjE3MjIyNDYwMTcwOTAxMjM0NTY3ODkmc2lnbmF0dXJlOjkxZTQ5MTQ4NmQzYWE5NTFiNGYzODdjYzkzZDY3ZmM3NTRjNDcyOWFmOTUzNDRiNjk0NDM1ZjU2NDQ3ODE5ZTk=
    return "IYZWSv2 " + base64EncodedAuthorization;
}
var authorization = generateAuthorizationString();
postman.setEnvironmentVariable("authorization", authorization);