Popis a využití eWay-CRM® Gate

eWay-CRM® Gate je webová IIS aplikace, která dovoluje zpřístupnit data eWay-CRM® ve formě HTML uživatelům mimo eWay-CRM® (např. faktura zákazníkovi). Ve výchozí instalaci serverové komponenty eWay-CRM® je funkce eWay-CRM® Gate z bezpečnostních důvodů úplně vypnuta.

Instalace a konfigurace

Samotná IIS aplikace eWay-CRM® Gate se nachází v podadresáři Gate v kořenové složce serverové komponenty eWay-CRM®. Takové umístění je důležité, protože aplikace eWay-CRM® Gate načítá připojovací řetězec (Connection String) k databázi ze souboru Web.config (konfigurační soubor webové služby eWay-CRM®), který je o složku výše. Nicméně, v rámci IIS může být aplikace bežící v této složce nastavena v jiné WebSite na jiné URL než webová služba eWay-CRM®.

Po spuštění IIS aplikace eWay-CRM® Gate je potřeba provést její konfiguraci. Ta spočívá v definici toho, jak se budou jednotlivé procedury v SQL volat - tzv. mapování. Konfigurace se provádí ve vlastním konfiguračním souboru (Gate\Web.config). Jeho výchozí forma je běžně dodávána s novou instalací serverové komponenty eWay-CRM®.

Nastavení mapování se provádí ve vlastní konfigurační sekci mappedContent. Každé mapování musí obsahovat název a název SQL procedury. Volitelně potom může obsahovat přejmenování parametrů, aby se název parametru v URL nemusel shodovat s názvem parametru SQL procedury. Ne všechny parametry SQL procedury se musí uvést v seznamu přejmenovaných parametrů. U takových, které jsou vynechány, se předpokládá, že mají stejný název v URL jako v SQL (bez zavináče).

Příklad mapování vypadá takto:

  <mappedContent>
    <mappings>
      <mapping name="username" procedureName="eWaySP_UnitTests_GetHtmlUsername">
        <renamedParameters>
          <renamedParameter name="id" procedureParameterName="UserItemGUID" />
        </renamedParameters>
      </mapping>
    </mappings>
  </mappedContent>

Jde o mapování procedury eWaySP_UnitTests_GetHtmlUsername, která má 2 parametry (@UserItemGUID a @Color). Přes aplikaci eWay-CRM® Gate se bude volat pod názvem username s parametry id a Color.

Volání

Princip je následující: jedno HTTP volání znamená jedno volání dané SQL procedury. Má to ale jistá omezení a specifika. Volání se provádí v tomto tvaru:

https://{adresa aplikace Gate}/{název mapování}/{parametry v base64}

Parametry HTTP volání se předávají jako base64 zakódovaný řetězec. Přesněji jde o řetězec standardních URI parametrů (tzv. Query String zakódovaný procentovou notací - viz https://en.wikipedia.org/wiki/Query_string), jehož UTF8 bytová reprezentace je zakódovaná do base64 řetězce.

Pro zakódování parametrů do base64 je možné použít SQL funkci eWay-CRM® dbo.EncodeToBase64.

Každé volání musí povinně obsahovat parametr s názvem id. Hodnota tohoto parametru musí mít nutně tvar GUID/UUID (128 bitové číslo v hexadecimálním zápisu se 4 pomlčkami). Nulový GUID je u parametru id zakázán.

Příklad volání, podle výše popsaného, vypadá takto:

http://server/eWay/Gate/username/aWQ9NzE0RUVCQkMtQkI3MC00MTJELTgzOEMtRTlFOTg2QzYxMEE0JmNvbG9yPXB1cnBsZQ==

Jedná se o volání se zakódovanými parametry:

id=714EEBBC-BB70-412D-838C-E9E986C610A4&color=purple

Parametr Color nemusí mít velké C, protože dosazování do SQL ignoruje velikost písmen.

Namapovaná SQL procedura poté musí vždy vrátit alespoň jeden řádek výsledků s alespoň jedním sloupcem. Textová hodnota prvního sloupce prvního řádku (indexy 0 a 0) je vrácena jako HTML obsah odpovědi volání. Zbytek vrácených dat je ignorován.

Vytváření odkazu na dokument na serveru

Podmínkou pro možnost vytváření funkčních odkazů, je aktivní ukládání dokumentů do serverové databáze a ne na disk, viz ukládání dokumentů.

Následně je pak možné použít na serverové databázi požít následující příkaz:

SELECT 'https://adresa_webove_sluzby/Gate/doc/' + dbo.EncodeToBase64('id=0C803C29-3F12-11E9-BB42-001C4232EF18&revision=1')

Kde je potřeba nahradit text "adresa_webove_sluzby" skutečnou adresou webové služby a hodnotu za id= je třeba přepsat GUID dokumentu, na který se má odkazovat. Parametr revision pak určuje, o jakou verzi daného dokumentu se jedná. Výsledkem takového volání je pak adresa:

https://adresa_webove_sluzby/Gate/doc/aWQ9MEM4MDNDMjktM0YxMi0xMUU5LUJCNDItMDAxQzQyMzJFRjE4JnJldmlzaW9uPTE=

Chybné pokusy

Pokud volání neobsahuje všechny potřebné náležitosti, v SQL se vyskytne chyba nebo jen používá neexistující mapování, aplikace vrátí chybovou stránku s kódem 404. Pro diagnostiku pravé příčiny chyby volání je potřeba uskutečnit tyto HTTP požadavky skrze localhost. Přesněji tak, aby procházeli přes loopback IP adresu. Toto se může hodit pro ladění nastavení mapování a SQL procedury.

V případě opakovaného chybného volání je IP adresa volajícího dočasně zablokována. Po tuto dobu dostává pouze chybovou stránku s kódem 503. Seznam blokovaných IP adres je možno vyprázdnit restartováním IIS aplikace eWay-CRM® Gate.

Varování o bezpečnosti

Aplikace eWay-CRM® Gate je přínosný nástroj a v kombinaci s uživatelskými SQL procedurami může pokrýt nespočet požadavků na veřejné výstupy ze systému. K jeho použití je ale potřeba přistupovat s uvědoměním si rizik, které přináší. Nastavením mapování v eWay-CRM® Gate se serverová databáze (jádro celého systému) otevírá k volání dané procedury prakticky kýmkoli, kdykoli a v jakémkoli počtu. Toto je velmi nutno mít stále na paměti! Z toho důvodu velmi nedoporučujeme v aplikaci eWay-CRM® Gate zpřístupnit volání, která:

vracejí informace o více než jedné položce v systému (např. seznamy, reporty, sumarizace),
vracejí data polí nebo položek, které jsou určitým uživatelům v rámci eWay-CRM® omezeny právy,
vracejí osobní či jiná citlivá data, především data spadající pod GDPR,
cokoliv v databázi mění či dokonce mažou,
používají transakce,
odesílají e-maily.

Důležité: Firma eWay System s.r.o. nemá a nemůže nést žádnou zodpovědnost za jakékoliv škody, ztráty nebo úniky dat způsobené nesprávným používáním nebo nastavením aplikace eWay-CRM® Gate. Veškerou zodpovědnost nese uživatel/zákazník dané instalace eWay-CRM®.