Przejdź do treści

Authentication

Autentykacja requestów odbywa się przez HTTP Authorization header z wykorzystaniem API key, który jest konfigurowany w panelu merchanta. W tym headerze podpis HMAC jest zakodowany według następujacego schematu: 

Authorization: hmac <version>$<api-key>$<method>$<URL-path>$<timestamp>$<nonce>
x-app-signature: <signature>

Przykład: 

authorization: hmac v1$b23a9fa61406440d868271d19d634906$GET$/MERCHANT/ORDER/STATUS$1678206688075$AB1CSA86767CVSJKLN878AS
x-app-signature: UTgPOhKP2Uqgt8K3gNwnLZvJVcN8Pxxui4z3g3pft+A=

Info

Mimo, że nagłówki HTTP są niewrażliwe na wielkość liter zgodnie ze standardem HTTP, nagłówki są wrażliwe na wielkość liter i powinny używać małych liter (lowercase header name).

Wyliczenie HMAC dla requestów

Integralność każdej wiadomości jest chroniona przez dodanie HMAC do każdego requestu i odpowiedzi. Sposób wyliczenia HMAC dla requestu jest następujący:

  1. Zbuduj wartość wejściową dla generacji HMAC przez konkatenację poniższych elementów przy użyciu $ jako ogranicznika:

    1. api-key: twój klucz API dostarczony przez OpenApp
    2. method: metoda requestu wielkimi literami (GET, POST, PUT, PATCH, DELETE)
    3. path information: muszą być wielkimi literami (na przykład /MERCHANT/ORDER/STATUS)
    4. timestamp: Unix timestamp (epoch) w milisekundach (requesty są ważne do 60 sekund od timestampu)
    5. nonce: randomowy unikalny string dla requestu, na przykład UUID v4, który może być wykorzystany do replay protection. Maksymalna długość to 64 znaki.
    6. content: Base64 encoded SHA256 hash treści requestu, lub nic jeśli request nie ma treści

  2. Wynikiem jest string podobny do poniższego dla requestu GET bez treści: 

    b23a9fa61406440d868271d19d634906$GET$/MERCHANT/ORDER/STATUS$1678206688075$yYy123
    Lub w przypadku requestu POST z treścią: 
    b23a9fa61406440d868271d19d634906$POST$/MERCHANT/ORDER/STATUS$1678206688075$xxx123$b23a9fa61406440d868271d19d634906

  3. Użyj API key i API Secret dostarczony przez OpenApp.

  4. Oblicz HMAC stringu z kroku 2, korzystając z klucza API Secret udostępnionego przez OpenApp i algorytmu SHA-256 z kodowaniem utf-8.

  5. Base64 koduje wynik funkcji HMAC.

Dane wejściowe (z wyjątkiem SHA256 treści, ponieważ treść znajduje się w innym miejscu requestu) są umieszczane w nagłówku authorization, a podpis jest umieszczany w nagłówku x-app-signature: 

authorization: hmac v1$<API key>$<request method>$<path uppercase>$<timestamp>$<nonce>
x-app-signature: <calculated signature>

Jest wysoce zalecane, aby wdrożyć walidację request signatures w requestach przychodzących, aby zweryfikować, że pochodzą one rzeczywiście od OpenApp.

Kalkulacja HMAC dla odpowiedzi

Odpowiedź string-to-sign jest skonkatonowanym stringiem generowanym z nastąpujących elementów:

  1. nonce który był wysłany w Authorization header requestu;
  2. timestamp który był wysłany w Authorization header requestu;
  3. Zhaszowany SHA256 z wykorzystaniem Base64 treści wiadomości, lub nic jeśli request nie ma treści

  4. To tworzy string podobny do poniższego w przypadku odpowiedzi bez treści: 

    yYy123$1678206688075

  5. Ten string do podpisu jest podpisywany z wykorzystaniem HMAC-SHA256 i secret key, a wynikowy podpis jest umieszczany w x-server-authorization header: 

    x-server-authorization: hmac v1$<timestamp>$<nonce>$<signature>

API OpenApp API weryfikuje ten podpis, więc jest on obowiązkowy.

Przykłady

Zakładając, że API Key to a6ae5908051a4b599202154b5b3541e3 a secret to 5814d9bd75ea42349483ac74266d24bc834656d743244653ba2dcc8519eed695

GET request

Ten przykład pokazuje kalkulację requestu GET dla endpointu {{baseUrl}}/merchant/order/status z JSON response.

Podpis requestu

  1. Parametry wsadowe dla stringu do podpisu są następujące:
    1. HTTP method GET
    2. Ścieżka endpointu wielkimi literami /MERCHANT/ORDER/STATUS
    3. Timestamp to 1678206688075
    4. Randomowy nonce to AB1CSA86767CVSJKLN878AS.
    5. Ponieważ request nie ma treści, nie ma hasza treści dla podpisu.
  2. String do podpisu to:
    v1$a6ae5908051a4b599202154b5b3541e3$GET$/MERCHANT/ORDER/STATUS$1678206688075$AB1CSA86767CVSJKLN878AS
  3. Wyliczony podpis w Base64 to: K/WpW/u2PRDdVPp21i1tzhs1Dmf7dUooCIkJwfCjjOw=
  4. Header autoryzacyjny ma wartość: 
    1
2
    authorization: hmac v1$a6ae5908051a4b599202154b5b3541e3$GET$/MERCHANT/ORDER/STATUS$1678206688075$AB1CSA86767CVSJKLN878AS
x-app-signature: K/WpW/u2PRDdVPp21i1tzhs1Dmf7dUooCIkJwfCjjOw=

Podpis odpowiedzi

Odpowiedź z serwera zawiera treść z danymi. Dane te są zakodowane w JSON i konieczne jest wygenerowanie SHA 256 hadh po serializacji do JSON:

{
    "status": "CANCELLED"
}

{"status":"CANCELLED"}
  1. Input dla podpisu to:
    1. Nonce z request AB1CSA86767CVSJKLN878AS
    2. Timestamp z requestu 1678206688075
    3. SHA-256 hash body odpowiedzi zakodowany Base64 eekP9w+TMbSUd0BnePPiT3A/DIr151xP6219xGvxpZ8=
  2. String do podpisu dla odpowiedzi hmac to: 
    v1$1678206688075$AB1CSA86767CVSJKLN878AS$NzllOTBmZjcwZjkzMzFiNDk0Nzc0MDY3NzhmM2UyNGY3MDNmMGM4YWY1ZTc1YzRmZWI2ZDdkYzQ2YmYxYTU5Zg==
  3. Podpis wyliczony z kodowaniem Base64 to: saOtyZVgcsDph3++lHfj/EzMxQOfE8UYKXisr6DdESw=
  4. Header x-server-authorization odpowiedź serwera ma wartość 
    x-server-authorization: hmac v1$1678206688075$AB1CSA86767CVSJKLN878AS$rXlI5uBELBVJyxNg8/gluQzxt83e2OSxd1E3R3pbkwA=

Request POST

Poniższy przykład pokazuje kalkulację requestu POST dla endpointu {{baseUrl}}/v1/orders/fulfillment z pustą odpowiedzią.

Podpis requestu

  1. Parametry wsadowe do stringu do podpisu to:
    1. Metoda HTTP POST
    2. Scieżka enpointu wielkimi literami /V1/ORDERS/FULFULLMENT
    3. Timestamp to 1678206688075
    4. Randomowy nonce to K0LPP2AAM8XIY964W2.
    5. Treść wiadomości
    {
    "oaOrderId": "OA12345678901234",
    "shopOrderId": "WS1213ASDZXC231A",
    "status": "CANCELLED"
}

    {"oaOrderId":"OA12345678901234","shopOrderId":"WS1213ASDZXC231A","status":"CANCELLED"}

    Hasz SHA-256 z body requestu: 

    lexq/vv5iQNLIuV/n7+8JYg7aAkk55imrq6M4fuToqs=

  2. String do podpisu to:
    v1$a6ae5908051a4b599202154b5b3541e3$POST$/V1/ORDERS/FULFULLMENT$1678206688075$AB1CSA86767CVSJKLN878AS$lexq/vv5iQNLIuV/n7+8JYg7aAkk55imrq6M4fuToqs=
  3. Podpis wyliczony z Base64 to: L0ipqXrr9HpQoXPwzgDRSNnJKRnnZZ58oJ0FayN5ips=
  4. Header authorization ma wartość: 
    1
2
    authorization: hmac v1$a6ae5908051a4b599202154b5b3541e3$POST$/V1/ORDERS/FULFULLMENT$1678206688075$AB1CSA86767CVSJKLN878AS
x-app-signature: L0ipqXrr9HpQoXPwzgDRSNnJKRnnZZ58oJ0FayN5ips=

Podpis odpowiedzi

Odpowiedź z serwera nie zawiera treści.

  1. Wsadowe do podpisu są więc następujące:
    1. Nonce z requestu AB1CSA86767CVSJKLN878AS
    2. Timestamp z requestu 1678206688075
    3. Brak treści
  2. String do podpisu odpowiedzi hmac to: v1$1678206688075$AB1CSA86767CVSJKLN878AS
  3. Wyliczony podpis z kodowaniem Base64 to: EQ4RqNLDmtVO1xgJlyQSI1h0ZfYvOjozyhyGHjiMqrM=
  4. Header x-server-authorization odpowiedzi ma wartość 
    x-server-authorization: hmac v1$1678206688075$AB1CSA86767CVSJKLN878AS$EQ4RqNLDmtVO1xgJlyQSI1h0ZfYvOjozyhyGHjiMqrM=

Konfiguracja sieci

Jeśli konieczna jest konfiguracja sieci, aby pozwolić na dostęp z OpenApp, należy skonfigurować następujące adresy IP, z których OpenApp będzie łączyć się z Twoją infrastrukturą:

  1. 3.125.75.87
  2. 3.70.34.35
  3. 3.72.153.100
  4. 3.72.163.248

Testowanie autentykacji

Po zakończeniu implementacji wyliczania swojego HMAC, koniecznie ją przetestuj.

OpenApp udostępnia 2 testowe endpointy, które możesz wykorzystać do weryfikacji poprawności podpisów HMAC. Wymagają one odpowiednich requestów autoryzacyjnych i zwracają headery x-server-authorization.

Request GET

Wyślij swój request na GET {{OpenAppUrl}}merchant/v1/test

Request POST

Wyślij swój request na POST {{OpenAppUrl}}merchant/v1/test Możesz dołączyć dowolną treść, na przykład: 

{
    "message": "dowolny string, jaki możesz sobie wymyśleć"
}