Przejdź do głównej zawartości

Autentykacja

Autentykacja żądań odbywa się przez nagłówek HTTP Authorization z wykorzystaniem klucza API skonfigurowanego w panelu merchanta. W nagłówku podpis HMAC jest zakodowany według następującego 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=
informacja

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

Wyliczenie HMAC dla żądań​

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

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

    1. api-key: klucz API dostarczony przez OpenApp
    2. method: metoda żądania wielkimi literami (GET, POST, PUT, PATCH, DELETE)
    3. path: ścieżka musi być wielkimi literami (na przykład /MERCHANT/ORDER/STATUS)
    4. timestamp: Unix timestamp (epoch) w milisekundach (żądania są ważne do 60 sekund od tego timestamp)
    5. nonce: losowy unikalny string dla żądania, np. UUID v4, który może być użyty do replay protection. Maksymalna długość to 64 znaki.
    6. content: hash SHA256 treści żądania zakodowany Base64, lub nic jeśli żądanie nie ma treści

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

b23a9fa61406440d868271d19d634906$GET$/MERCHANT/ORDER/STATUS$1678206688075$yYy123

Lub w przypadku żądania POST z treścią:

b23a9fa61406440d868271d19d634906$POST$/MERCHANT/ORDER/STATUS$1678206688075$xxx123$b23a9fa61406440d868271d19d634906

  1. Pobierz API Secret dostarczony przez OpenApp.

  2. Oblicz HMAC stringu z kroku 2 używając API Secret dostarczonego przez OpenApp i algorytmu SHA-256 z kodowaniem UTF-8.

  3. Zakoduj wynik funkcji HMAC w Base64.

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

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

Zdecydowanie zaleca się wdrożenie walidacji podpisów żądań przychodzących w celu weryfikacji, że rzeczywiście pochodzą one od OpenApp.

Wyliczenie HMAC dla odpowiedzi​

String-to-sign odpowiedzi jest skonkatenowanym stringiem wygenerowanym z następujących elementów:

  1. nonce który był wysłany w nagłówku Authorization żądania;
  2. timestamp który był wysłany w nagłówku Authorization żądania;
  3. hash SHA256 treści żądania zakodowany Base64, lub nic jeśli żądanie nie ma treści
  4. Wynikiem jest string podobny do poniższego w przypadku odpowiedzi bez treści:
yYy123$1678206688075
  1. Ten string-to-sign jest podpisywany przy użyciu HMAC-SHA256 i secret key, a wynikowy podpis jest umieszczany w nagłówku x-server-authorization:
x-server-authorization: hmac v1$<timestamp>$<nonce>$<signature>

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

Przykłady​

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

Żądanie GET​

Ten przykład pokazuje kalkulację żądania GET dla endpointu {{baseUrl}}/merchant/order/status z odpowiedzią JSON.

Podpis żądania​

  1. Parametry wejściowe dla stringu do podpisu:
    1. Metoda HTTP GET
    2. Ścieżka endpointu wielkimi literami /MERCHANT/ORDER/STATUS
    3. Timestamp to 1678206688075
    4. Losowy nonce to AB1CSA86767CVSJKLN878AS.
    5. Ponieważ żądanie nie ma treści, nie ma hasza treści dla podpisu.
  2. String do podpisu to:
v1$a6ae5908051a4b599202154b5b3541e3$GET$/MERCHANT/ORDER/STATUS$1678206688075$AB1CSA86767CVSJKLN878AS
  1. Wyliczony podpis w Base64 to: K/WpW/u2PRDdVPp21i1tzhs1Dmf7dUooCIkJwfCjjOw=
  2. Nagłówki mają wartość:
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 są zakodowane w JSON i konieczne jest wygenerowanie hasza SHA-256 po serializacji do JSON:

{
  "status": "CANCELLED"
}
  1. Dane wejściowe dla podpisu:
    1. Nonce z żądania AB1CSA86767CVSJKLN878AS
    2. Timestamp z żądania 1678206688075
    3. Hash SHA-256 treści odpowiedzi zakodowany Base64 eekP9w+TMbSUd0BnePPiT3A/DIr151xP6219xGvxpZ8=
  2. String do podpisu odpowiedzi HMAC to:
v1$1678206688075$AB1CSA86767CVSJKLN878AS$NzllOTBmZjcwZjkzMzFiNDk0Nzc0MDY3NzhmM2UyNGY3MDNmMGM4YWY1ZTc1YzRmZWI2ZDdkYzQ2YmYxYTU5Zg==
  1. Wyliczony podpis zakodowany Base64 to: saOtyZVgcsDph3++lHfj/EzMxQOfE8UYKXisr6DdESw=
  2. Nagłówek x-server-authorization odpowiedzi serwera ma wartość:
x-server-authorization: hmac v1$1678206688075$AB1CSA86767CVSJKLN878AS$saOtyZVgcsDph3++lHfj/EzMxQOfE8UYKXisr6DdESw=

Żądanie POST​

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

Podpis żądania​

  1. Parametry wejściowe dla stringu do podpisu:
    1. Metoda HTTP POST
    2. Ścieżka endpointu wielkimi literami /V1/ORDERS/FULFULLMENT
    3. Timestamp to 1678206688075
    4. Losowy nonce to AB1CSA86767CVSJKLN878AS.
    5. Treść żądania:
{
  "oaOrderId": "OA12345678901234",
  "shopOrderId": "WS1213ASDZXC231A",
  "status": "CANCELLED"
}

Hasz SHA-256 z treści żądania:

lexq/vv5iQNLIuV/n7+8JYg7aAkk55imrq6M4fuToqs=
  1. String do podpisu to:
v1$a6ae5908051a4b599202154b5b3541e3$POST$/V1/ORDERS/FULFULLMENT$1678206688075$AB1CSA86767CVSJKLN878AS$lexq/vv5iQNLIuV/n7+8JYg7aAkk55imrq6M4fuToqs=
  1. Wyliczony podpis zakodowany Base64 to: L0ipqXrr9HpQoXPwzgDRSNnJKRnnZZ58oJ0FayN5ips=
  2. Nagłówki authorization mają wartość:
authorization: hmac v1$a6ae5908051a4b599202154b5b3541e3$POST$/V1/ORDERS/FULFULLMENT$1678206688075$AB1CSA86767CVSJKLN878AS
x-app-signature: L0ipqXrr9HpQoXPwzgDRSNnJKRnnZZ58oJ0FayN5ips=

Podpis odpowiedzi​

Odpowiedź z serwera nie zawiera treści.

  1. Dane wejściowe dla podpisu:
    1. Nonce z żądania AB1CSA86767CVSJKLN878AS
    2. Timestamp z żądania 1678206688075
    3. Brak treści
  2. String do podpisu odpowiedzi HMAC to: v1$1678206688075$AB1CSA86767CVSJKLN878AS
  3. Wyliczony podpis zakodowany Base64 to: EQ4RqNLDmtVO1xgJlyQSI1h0ZfYvOjozyhyGHjiMqrM=
  4. Nagłówek x-server-authorization odpowiedzi serwera ma wartość:
x-server-authorization: hmac v1$1678206688075$AB1CSA86767CVSJKLN878AS$EQ4RqNLDmtVO1xgJlyQSI1h0ZfYvOjozyhyGHjiMqrM=

Konfiguracja sieci​

Jeśli konieczna jest konfiguracja sieci, aby zezwolić 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 HMAC warto przetestować jej poprawność.

OpenApp udostępnia 2 testowe endpointy, których możesz użyć do weryfikacji poprawności obliczanych podpisów HMAC. Wymagają one poprawnego nagłówka HMAC i zwracają nagłówki x-server-authorization.

Żądania GET​

Wyślij żądanie na GET {{OpenAppUrl}}merchant/v1/test

Żądania POST​

Wyślij żądanie na POST {{OpenAppUrl}}merchant/v1/test

Możesz dołączyć dowolną treść, na przykład:

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