Skip to main content

Authentication

Diyalog API'yi kullanabilmek için uygulamanızın doğrulanması gerekmektedir. Bunun için Diyalog AccessKeyId ve AccessKeySecret çifti kullanmaktadır. Öncelikle uygulamanız için bu erişim key id ve secret bilgilerini Diyalog adminininden talep etmeniz gerekmektedir.

API isteklerini yapabilmeniz için gerekli olan kimlik bilgileri :#
  • AccessKeyId : Uygulamanıza özel oluşturulmuş olan erişim anahtarı id bilgisidir.
  • AccessKeySecret : Uygulamanıza özel oluşturulan şifreleme anahtarıdır. Bu anahtar kullanılara isteklerinizi imzalama işlemi yapılır.

Diyalog API'lerine çağrı yapmak için, her isteği doğrulamanız gerekir. Diyalog Platformu doğrulama için HMAC Authentication mekanizması kullanmaktadır.

  • HMAC Authentication

Güvenlik#

Kimlik doğrulama için Transport Layer Security(TLS) gereklidir. Yapılan API isteklerinin SSL ile şifrelenmiş olması gerekmektedir.

HMAC Authentication#

Diyalog API HTTP isteklerinin doğrulanması için HMAC Authentication algoritması ve makanizması kullanılmaktadır. Bu mekanizma ile yapılan isteklerin bütünlüğü ve yetkili bir uygulama tarafından yapıldığı doğrulanmaktadır.

Diyalog admin kullanıcısı uygulamanız için AccessKeyId ve AccessKeySecret çiftini oluşturduktan sonra bu bilgiler kullanılarak yapılan her api isteğinin MAC(Message Authentication Code) değeri HMAC SHA256 algoritması kullanılarak oluşturulmalı ve isteğinizin header bölümünde iletilmelidir. Ayrıca yine istek zamanı ve isteği yapan kişinin sicil numarası header'a eklenmelidir. Bu bilgiler kullanılarak isteğimiz Diyalog Platformu tarafından doğrulanacak ve API'den cevap alabileceksiniz.

Güvenlik için, HTTPS/TLS kullanmanız gerekir.

HMAC kimlik doğrulama için yapılan her API isteğinin header bölümüne eklemeniz gereken alanlar şu şekildedir :#
  • x-dlg-date

    İsteğin yapıldığı zaman bilgisidir. Zaman bilgisi "EEE, dd MMM yyyy HH:mm:ss Z" formatında oluşturulmalıdır.

    x-dlg-date : "EEE, dd MMM yyyy HH:mm:ss Z"

    Örneğin: Date : Tue, 09 Mar 2021 13:28:32 GMT

    • Yerel makinenizin yerel zaman damgasını kullanmalısınız.
    • Zaman damganızın Diyalog sunucusu tarafından kullanılan zamandan +/- 15 dakikadan fazla kaymadığından emin olmalısınız, aksi takdirde talebiniz başarısız olur.
    • Zaman damganızın yerel saat dilimini içerdiğinden emin olmalısınız. Eksikse, Diyalog platformu saat diliminizin GMT olduğunu varsayar ve bunu zaman damgasıyla karşılaştırır.
  • x-dlg-requester-userid

    İsteği yapan kullanıcın sicili veya sisteminizdeki tekil id bilgisidir. Bu bilgi audit logları için kullanılmaktadır.

    x-dlg-requester-userid : “userId of requester”

    Örneğin: X-Requester-UserId : 45186

  • x-dlg-authorization

    API isteğiniz bu alanda oluşturduğunuz isteğinizin imzası ile onaylanacaktır.x-dlg-authorization header'ı aşağıdaki bilgilerin birleştirilmesi ile oluşturulur.

    x-dlg-authorization : "DLGA " + AccessKeyId + ":" + Signature

    Örneğin : x-dlg-authorization : “DLGA 1234567-8ABC-DEF0-5432-56712ABCDEF5:4J2OtxTeMpyfMad4y26RaKA/rrk=

x-dlg-authorization headerının oluşturulması#

Pseudo-code

stringToSign = HTTP-method + "\n"
+ Content-Type + "\n"
+ Date + "\n"
+ CanonicalizedPOSTVariables
+ CanonicalizedResource
Signature = base64(hmac-sha256(AccessKeySecret, stringToSign))
x-dlg-authorization = "DLGA " + AccessKeyId + ":" + Signature

Yukarıda pseudo-code'u verilmiş olan hmac hesaplamasında gösterilmiştir.

  1. Öncelikle imzalanacak string oluşturulur. Yukarıdaki kodda gösterildiği üzere bu string HTTP-method, Content-Type, Date, CanonicalizedPOSTVariables ve CanonicalizedResource değerlerinin her biri arasına newline eklenerek birleştirilmiş halidir.
  2. İmzalamaya girdi olacak olan stringToSign HMAC-SHA256 şifreleme algoritması ve uygulamanız için oluşturulan AccessKeySecret kullanılarak imzalanır ve MAC oluşturulur.
  3. Oluşturulan imza Base64 encode edilir.
  4. Base64 encode edilen imzanın değeri "DLGA ", AccessKeyId ile "DLGA " + AccessKeyId + ":" + Signature formülü kullanılarak x-dlg-authorization header oluşturulur.

İmzalanacak string içinde kullanılan alanların anlamları aşağıdaki gibidir.

HTTP-method : API isteğini yaptığınız HTTP istek tipidir. (GET, POST, PUT, DELETE)

Content-Type : HTTP isteğin content tipidir. Örneğin ("application/json")

Date : İstek zamanıdır. Buradaki istek zamanına x-dlg-date header alanına verilen date bilgisi verilmelidir.

CanonicalizedPOSTVariables : POST isteklerinizde geçerli olacak istek body'sinin string halidir. Burada istek body'sinin tam olarak nasıl görünüyorsa o şekilde eklenmesi gerekmektedir. Örneğin uygulanız bir json body'sini newline ve tablar ile oluşturup Diyalog'a gönderiyorsa imzalamak için birebir aynı görünümlü body'nin string hali bu alana konulmalıdır.

CanonicalizedResource : Bu bilgi istek URI'nızdan alınır. Istek URI'nın sunucu adresinden sonraki bilgilerdir.

Örneğin : HTTP iseğinizin URI'ı https://api.diyalog.im/v1/reporting/getonlinehelplist olsun. Bu istek URI'nın CanonicalizedResource'u /v1/reporting/getonlinehelplist olacaktır.

İmzalanacak string örneği :

stringToSign = "POST" + "\n"
+ "application/json" + "\n"
+ "Tue, 09 Mar 2021 13:28:32 GMT" + "\n"
+ "{ + "\n"
" \"customerId\" : \"2337368\"," + "\n" +
" \"agentUserId\" : \"45186\"," + "\n" +
" \"startDate\" : 1," + "\n" +
" \"endDate\" : 2" + "\n" +
"}" + "\n"
+ "/v1/reporting/getonlinehelplist"

Özet - Diyalog HMAC Authentication Doğrulama için yapılması gerekenler#

  1. Uygulamanız için Diyalog admininden AccessKeyId ve AccessKeySecret bilgileri alınmalıdır.

  2. HTTP isteği API'ye göre oluşturulmalı.

  3. API isteğini yaptığınız zaman bilgisi "EEE, dd MMM yyyy HH:mm:ss Z" formatında oluşturulamalı ve x-dlg-date isim ile HTTP isteğin header'ına eklenmelidir.

  4. İsteği hangi kullanıcı için yaptığınız bilgisini yani isteği yapan gerçek kullanıcının sicil veya tekil kullanıcı numarasını x-dlg-requester-userid ismi ile HTTP isteğin header'ına eklenmekidir.

  5. HTTP Api istek body'si oluşturulmalıdır.

  6. HMAC doğrulama yapılabilmesi için aşağıdaki alanları içeren imzalanacak string oluşturulmaldır.

    HTTP-method Content-Type Date CanonicalizedPOSTVariables CanonicalizedResource

  7. AccesKeySecret kulllanılarak imzalanacak string'in HMAC-SHA256 ile hash'i oluşturulmalı ve base64 encode edilmelidir.

  8. Oluşturulan signature (imza) kullanılarak doğrulama verisi "DLGA " + AccessKeyId + ":" + Signature formulü ile authorizasyon datası oluşturulmalı ve HTTP isteğin header'ına x-dlg-authorization ismi ile eklenmelidir.

  9. Yukarıda belirtilen şekilde istek hazırlandıktan sonra HDiyalog API sunucuların istek gönderilebilir.

Örnek curl HTTP API POST isteği :

curl --location --request POST 'http://api.diyalog.im/v1/reporting/getonlinehelplist' \
--header 'x-dlg-date: Tue, 09 Mar 2021 13:28:32 GMT' \
--header 'x-dlg-authorization: DLGA 1234567-8ABC-DEF0-5432-56712ABCDEF5:4J2OtxTeMpyfMad4y26RaKA/rrk=' \
--header 'x-dlg-requester-userid: 45186' \
--header 'Content-Type: application/json' \
--data-raw '{
"customerId" : "2337368",
"agentUserId" : "45186",
"startDate" : 1,
"endDate" : 2
}'

HMAC Authentication Hata Durumları#

API isteği yapıldığında Diyalog API sunucuları yukarıdaki header alanları üzerinden istek yapılan API'ye ilgili uygulamanın yetkisi olup olmadığını kontrol eder. Eğer yetki sorunu veya doğrulanamayan bir istek olduğunda aşağıdaki hatalar sunuculardan dönecektir.

Http Status CodeMesajAçıklama
400Required headers not foundDate, X-Requester-UserId veya X-Authorization header alanlarından biri veya birkaçı eksik.
400Authorization failed due to data format not validX-Authorization header alanındaki bilgiler doğru formatta değil. Alanın "DLGA " ile başlayıp accesKeyId ve imza değerleri arasına : olduğunu kontrol edin.
400Authorization failed due to date not validX-DLG-DATE tarih formatı "EEE, dd MMM yyyy HH:mm:ss Z" formatında değil. Kontrol edin..
401Authorization failedİstek doğrulanamadı. İmza değeri doğru değil.
403Request time may not be correct.İstek header'ında gelen x-dlg-date ve sunucu zamanı arasında +/- 15 dakikadan fazla fark var.