Armongate Entegrasyon Servisi

Bu doküman, Armongate tarafından sunulan REST API destekli entegrasyon servisinin kullanımında nasıl kimlik doğrulama yapılacağını ve gerekli verilerin nasıl oluşturulacağını açıklamaktadır. Bu servisi kullanarak, 3. parti uygulamalar ile Armongate sistemi arasında güvenli bir veri iletişimi sağlanabilir.

Kimlik Doğrulama

Entegrasyon servisi, istemcilerin Armongate tarafından sağlanan client_id ve client_secret değerlerini kullanarak güvenli bir şekilde API istekleri yapmalarına izin verir. Her istekte, istemci tarafından üretilen bir timestamp değeri ile birlikte client_id ve client_secret kullanılarak bir signature oluşturulur. Bu değerler, istek başlıklarında gönderilerek hem kimlik doğrulama yapılması hem de tekrarlayan isteklere dayalı saldırıların önüne geçmeyi sağlar.

İstek Başlıkları

API isteklerinde aşağıdaki başlıklar kullanılmalıdır:

X_Armon_Client_Id: İstemci kimliği (client_id)
X_Armon_Timestamp: İstek zaman damgası (timestamp)
X_Armon_Signature: İmza değeri (signature)

Açıklamalar

client_id - client_secret

Armongate tarafından 3. parti uygulamalara iletişim için sağlanan değerlerdir ve istemci tarafından güvenli bir şekilde saklanmalıdır. Kimlik doğrulamada anahtar değer olarak kullanılacağı için bu değerlerin açığa çıkmaması 3. parti uygulamaların sorumluluğundadır. Uygulama içerisinde gömülü olmaması ve erişiminin tercih edilen kimlik doğrulama yöntemlerine dayalı olması önerilir.

timestamp

Her istekte dinamik olarak üretilen zaman damgasıdır ve servise gelen her isteğin güncel olduğu kontrol edilir. OnPremise kurulumlarda sunucu saatinin güncel olması önem arz etmektedir. "ddMMyyyyHHmmss" formatında olması beklenir.
08 Kasım 2024 10:10:35 için örnek değer; "08112024101035"

signature

client_id ve timestamp değerlerinin birleştirilmesiyle oluşturulan ve client_secret kullanılarak HMAC SHA256 algoritması ile hashlenen değerdir.

Örnek Kullanım

Typescript ile örneklenen kullanım aşağıdaki gibidir;

const crypto = require("crypto");

// Given values
const clientId = "aaaaaaaa-bbbb-cccc-eeee-ffffffffffff";
const clientSecret = "vXaLxlqoyTo8nxAC3Ho9ZFF7X30IJ3WE";
const timestamp = "26112024162835"; // Provided timestamp for each request

// Concatenate clientId and timestamp
const dataToSign = clientId + timestamp;

// Generate the HMAC SHA256 signature using the client secret
const signature = crypto.createHmac("sha256", clientSecret).update(dataToSign).digest("hex");

// Generate headers
const headers = {
    X_Armon_Client_Id: clientId,
    X_Armon_Timestamp: timestamp,
    X_Armon_Signature: signature,
};

console.log("Generated Headers:", headers);

// API Request with custom headers
const axios = require("axios");

axios
    .get("https://api.armongate.com/endpoint", { headers })
    .then((response) => {
        console.log("Response:", response.data);
    })
    .catch((error) => {
        console.error("Error:", error);
    });