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.