Instalace webového rozhraní

O aplikaci

Informační systém enTeam zajišťuje řízení a správu firemních dokumentů, komunikaci uvnitř pracovního týmu a flexibilní automatizaci firemních procesů.
Pro zprovoznění webového rozhraní informačního systému enTeam je třeba provést tyto kroky:

• instalaci a nastavení webového API (aplikační rozhraní),
• instalaci a nastavení webového GUI (grafické uživatelské rozhraní),
• přesměrování komunikace z protokolu http na HTTPS a
• zpřístupnění webového API na protokolu HTTPS.

Popis provedení každého z těchto kroků je uveden v dalších kapitolách.
Instalační soubory webového rozhraní jsou součástí instalačního ZIP archivu. V návodu jsou uvedeny relativní cesty k souborům a adresářům (vždy začínají adresářem enTeam.WebApi nebo enTeam.WebGui, tj. jedním z adresářů umístěných na první úrovni vnoření v uvedeném archivu).
Pro přehlednost jsou názvy souborů a adresářů v celém postupu instalace označeny technickým písmem. Názvy adresářů a souborů obsažené v uvedeném ZIP archivu jsou navíc zvýrazněny červenou barvou.
V tomto dokumentu jsou uvedeny příklady částí souborů. Takové texty jsou označeny modrou barvou.

Předpoklady instalace webového rozhraní

Webové rozhraní informačního systému enTeam využívá k připojení do databáze dvou způsobů. Prvním z nich je přímé připojení do databáze pomocí databázového klienta. Druhým způsobem je připojení pomocí OLE rozhraní, které je součástí standardního desktopového klienta aplikace enTeam.
Server, kde bude webové rozhraní provozováno, proto musí mít:

• Funkční enTeam verze 6.0.0.3 nebo novější – serverovou (hlavní) nebo klientskou instalaci
• Funkční webový server Internet Information Services (IIS) verze 10 nebo novější nainstalovaný na serveru, kde je zprovozněn IS enTeam

Instalace webového API

Webové API je kolekce webových služeb poskytující přístup k datům modulů aplikace enTeam.
Aktuálně podporované DBMS jsou Firebird, Microsoft SQL Server a Oracle. Požadovanou strukturu databáze je nutné vytvořit dodanými SQL skripty (viz #Postup instalace). Strukturu lze vytvořit:

• Individuálně, tj. samostatná databáze koexistující vedle stávající databáze enTeam
• Přidat do aktuální databáze enTeam

Na vytvořenou strukturu databáze je pak potřeba nasměrovat aplikaci (viz #Soubor appsettings.json)

Předpoklady

• Funkční ASP.NET Core Runtime 2.1 (např. 2.1.19 nebo novější)
  • https://dotnet.microsoft.com/download/dotnet-core/2.1
  • Stáhnout a nainstalovat „Hosting Bundle“

• Existence databázového uživatele (typicky teambridge), pod kterým se bude webové API přihlašovat do databáze. V případě databázového serveru Firebird musí existovat uživatel s metodou autentizace SRP (viz #Pod uživatelem se nelze připojit z enTeam.WebApi do DB Firebird 3.0+. Spojení z ostatních aplikací enTeam pod stejným uživatelem funguje).

Postup instalace

Instalace sestává z následujících kroků:

1. Založit databázové struktury pro webovou část enTeam
   Poznámka: Uvedený postup popisuje vytvoření databázových struktur pro webovou část enTeam ve stávající databázi informačního systému enTeam. Struktury lze založit i v samostatné databázi vytvořené za tímto účelem.
   1. Otevřete aplikaci Příkazová řádka (cmd.exe)
   2. Spusťte SQL skripty
      • Máte-li databázový server Firebird:
        V Příkazové řádce vykonejte následující příkazy:
        <FirebirdAdresar>\isql -user teambridge -password <Heslo> <Databaze> -i <ZipAdresar>\enTeam.WebApi\sql\Firebird\waFirebird_001.sql
        <FirebirdAdresar>\isql -user teambridge -password <Heslo> <Databaze> -i <ZipAdresar>\enTeam.WebApi\sql\Firebird\waFirebird_002.sql
        V příkazu nahraďte:
        • <FirebirdAdresar> za cestu k adresáři s instalací Firebird (např. c:\Program Files (x86)\Firebird),
        • <Heslo> za heslo uživatele teambridge,
        • <Databaze> za cestu k databázi informačního systému enTeam,
        • <ZipAdresar> za cestu k adresáři s extrahovaným ZIP archivem s instalačními soubory webového rozhraní enTeam
      • Máte-li databázový server Microsoft SQL Server:
        V Příkazové řádce vykonejte následující příkazy:
        sqlcmd -U teambridge -d <Databaze> -i <ZipAdresar>\enTeam.WebApi\sql\SqlServer\waSqlServer_001.sql
        sqlcmd -U teambridge -d <Databaze> -i <ZipAdresar>\enTeam.WebApi\sql\SqlServer\waSqlServer_002.sql
        V příkazu nahraďte:
        • <Databaze> za název databáze informačního systému enTeam,
        • <ZipAdresar> za cestu k adresáři s extrahovaným ZIP archivem s instalačními soubory webového rozhraní enTeam
        Poznámka: Při vykonání příkazů pod databázovým uživatelem teambridge se může objevit následující varování.
        Cannot find the user 'teambridge', because it does not exist or you do not have permission.
        Varování se zobrazí v případě, že nedošlo k vykonání příkazů GRANT. To nastane v případě, že databázový uživatel teambridge již je vlastníkem vytvořených tabulek. Varování lze proto ignorovat.
      • Máte-li databázový server Oracle:
        V Příkazové řádce vykonejte následující příkaz: exit | sqlplus.exe teambridge/<Heslo>@//<Server>/<Databaze> @<ZipAdresar>\enTeam.WebApi\sql\Oracle\waOracle_002.sql
        V příkazu nahraďte
        • <Heslo> za heslo uživatele teambridge,
        • <Server> IP nebo hostname databázového serveru Oracle,
        • <Databaze> za název databáze informačního systému enTeam,
        • <ZipAdresar> za cestu k adresáři s extrahovaným ZIP archivem s instalačními soubory webového rozhraní enTeam
2. Vytvořit adresář enTeam.WebApi v kořenovém adresáři webového serveru (např. c:\inetpub\wwwroot)
3. Zkopírovat obsah adresáře enTeam.WebApi\bin do adresáře enTeam.WebApi, vytvořeného v předchozím kroku
4. V IIS Manageru přidat nový aplikační pool pro webové API (IIS Manager > Server > Application Pools > Add Application Pool…)
   
5. V rozšířených nastaveních aplikačního poolu musí být nastaveno
   • .NET CLR Version = No Managed Code
   • Enable 32-Bit Applications = true
   • Identity = Local System
   
6. V IIS Manageru vytvořit novou webovou stránku pro webové API (pojmenovanou např. enTeam.WebApi) a přiřadit jí vlastní port (např. 8088).
   
   
   Poznámka: Pokud je uvedený port na serveru již obsazen jinou aplikací, použijte libovolný jiný. Zvolený port je ale nutné reflektovat ve všech krocích tohoto postupu.

Nastavení webového API

Soubor appsettings.json

V aplikaci webového API nastavte soubor appsettings.json dle následujícího postupu.

1. Pokud v adresáři aplikace webového API dosud takový soubor nemáte, pak jej vytvořte zkopírováním souboru appsettings.Template.json
   Poznámka: Klíče (ve struktuře JSON souboru), které začínají znakem (nebo více znaky) #, jsou považovány za zakomentované a slouží pouze jako ilustrace možného nastavení. Po nastavení hodnot v souboru appsettings.json, je možné zakomentované řádky zcela odstranit (pozor ale na případné porušení syntaxe JSON, např. čárky mezi vlastnostmi)
2. Správně nastavte připojení k databázi webové části aplikace enTeam (viz #Postup instalace), tj. klíč WebApiDb a jeho vlastnosti Provider a ConnectionString. Ostatní vlastnosti klíče WebApiDb deaktivujte zakomentováním (nebo odstraňte) dle předchozí poznámky.
3. Dále nastavte přístup k původní databázi (popř. databázím) aplikace enTeam (tj. obdoba nastavení databáze ze sekcí [M/USER], [M/TeamBridge] atd., ve standardním INI produktu enTeam). Jde o klíče DataDictionaryDb, ScriptExDb, UserDb a WorkflowManagerDb a jejich vlastnosti Provider a ConnectionString

Poznámka: V případě databázového serveru Firebird obsahuje vlastnost ConnectionString plnou cestu k souboru databáze (např. C:\enTeam\Files\Data\enTeam.fdb). Aby byla aplikace webového API schopna vlastnost ConnectionString přečíst, je třeba zpětná lomítka v cestě k souboru „zdvojit“. Cesta k databázi pak bude v hodnotě vlastnosti ConnectionString např. tato:
"ConnectionString":"Database=SERVER:C:\\enTeam\\Files\\Data\\enTeam.fdb;…"

INI soubor webového API

Webové API pro svůj běh potřebuje pozměněné INI oproti desktopu. Vytvořte kopii souboru serie_m.ini, ke které bude přistupovat pouze webové API (např. <enTeamAdresar>\Ini\serie_m.WebApi.ini) a přidejte do něj následující obsah
[M/TeamBridge]
ServerEngine=True

Soubor web.config

Pro běh webového API je třeba nastavit proměnnou prostředí SERIEM tak, aby odkazovala na soubor serie_m.WebApi.ini (viz #INI soubor webového API). Toho lze docílit úpravou souboru web.config (uvnitř elementu aspNetCore) dle následujícího postupu:

1. Pokud v adresáři aplikace webového API dosud takový soubor nemáte, pak jej vytvořte zkopírováním souboru web.Template.config
2. Správně nastavte proměnnou SERIEM v souboru web.config

Příklad nastavení proměnné SERIEM:
<aspNetCore
  processPath="c:\Program Files (x86)\dotnet\dotnet.exe"
  arguments=".\Leviom.enTeam.WebApi.dll"
  stdoutLogEnabled="false"
  stdoutLogFile=".\logs\stdout">
    <environmentVariables>
        <environmentVariable
          name="SERIEM"
          value="<enTeamAdresar>\Ini\serie_m.WebApi.ini" />
    </environmentVariables>
</aspNetCore>

Používáte-li 64bitový OS, zajistěte, aby se používala x86 varianta programu dotnet.exe. Nejjednodušší je upravit soubor web.config tak, že nastavíte plnou cestu k programu v atributu processPath elementu aspNetCore (viz ukázka výše).

Ověření funkčnosti

Nyní je možné ověřit, zda je aplikace webového API správně nakonfigurovaná a běží (tj. zda odpovídá na požadavky).
Na serveru, kde má aplikace webového API běžet, vložte do internetového prohlížeče následující URL (pokud bylo v bodě 6 kapitoly #Postup instalace aplikaci přiřazeno jiné číslo portu, je třeba URL patřičně upravit).
http://localhost:8088/
Pokud aplikace webového API běží, pak by měla vždy být zobrazena odpověď v následujícím formátu.
Leviom.enTeam.WebApi, Version=2.0.0.0, Culture=neutral, PublicKeyToken=null
Pokud není ověření funkčnosti aplikace úspěšné, pokračujte zjištěním příčiny chyby dle #Ověření funkčnosti webového API končí chybou 500 nebo 502 a po vyřešení problému znovu ověřte funkčnost aplikace z internetového prohlížeče.
Poznámka: Některé webové prohlížeče uvedenou odpověď nezobrazí, ale nebídnou ke stažení jako soubor. V takovém případě ověřte obsah staženého souboru.

Způsob provozování webového API

Vzhledem k tomu, že webové API představuje rozhraní aplikace enTeam, je třeba věnovat zvýšenou pozornost jeho zabezpečení a učinit rozhodnutí, jak bude webové API provozováno. Obecně nelze doporučit zpřístupnění portu webového API nešifrovaným způsobem. Nabízejí se tyto možnosti provozování webového API:

• Pod zabezpečeným připojením (VPN)
• Na protokolu HTTPS (viz #URL Rewrite – Přesměrování na https)

Instalace webového GUI

Webové GUI (grafické uživatelské rozhraní) informačního systému enTeam je webová aplikace běžící ve webovém prohlížeči uživatele. Webové GUI komunikuje s informačním systémem enTeam prostřednictvím webového API (viz #Instalace webového API).

Předpoklady

Webové GUI nemá žádné speciální technologické předpoklady instalace. Aplikaci lze provozovat jako samostatnou webovou stránku v některém z běžných webových serverů, popř. jako podstránku jiné webové stránky. Vzhledem k charakteru aplikace se doporučuje zpřístupnit aplikaci výhradně na protokolu HTTPS.
Níže jsou uvedeny dva způsoby instalace webového GUI ve webovém serveru IIS. Vyberte si jeden z nich a proveďte instalaci.

• #Postup instalace v IIS – webová stránka
• #Postup instalace v IIS – podstránka jiné webové stránky

Postup instalace v IIS – webová stránka

V případě instalace webového GUI jako samostatné webové stránky ve webovém serveru IIS bude aplikace dostupná na adrese např.
https://enteam.leviom.cz

Instalace sestává z následujících kroků:

1. Zkopírovat adresář enTeam.WebGui do kořenového adresáře webového serveru (např. c:\inetpub\wwwroot)
2. V aplikaci IIS Manager vytvořit novou webovou stránku (site) pro webové GUI a stránce přiřadit platný SSL certifikát
   
3. Přidat Binding na portu 80 (IIS Manager > Server > Sites > enTeam.WebGui > Bindings…)

Binding na portu 80 je vhodné přidat pro případ, kdy uživatel zadá do prohlížeče adresu bez uvedení protokolu. V takovém případě prohlížeč volá server na portu 80 (http). Doporučuje se, aby webový server v takovém případě provedl přesměrování uživatele na port 443 (https) – viz #URL Rewrite – Přesměrování na https.

Postup instalace v IIS – podstránka jiné webové stránky

V případě instalace webového GUI jako podstránky jiné, již existující webové stránky ve webovém serveru IIS bude aplikace dostupná na adrese např.
https://www.leviom.cz/enteam

Instalaci lze provést dvěma způsoby:

1. Obsah adresáře enTeam.WebGui zkopírujte do podadresáře aplikace se zvoleným názvem (např. podadresář enteam vytvořený v adresáři webové stránky provozované na adrese www.leviom.cz) nebo
2. Adresář enTeam.WebGui zkopírujte do kořenového adresáře webového serveru (např. c:\inetpub\wwwroot) a ve zvolené webové stránce vytvořte virtuální složku (IIS Manager > Server > Sites > ZvolenáWebováStránka > View Virtual Directories > Add Virtual Directory…)
   

Nastavení webového GUI

Pro správné fungování webového GUI je třeba nastavit napojení na webové API. Toto nastavení je uloženo v souboru enTeam.WebGui/assets/config/enteam-api-config.json. Soubor vytvořte zkopírováním souboru enTeam.WebGui/assets/config/enteam-api-config.template.json a upravte dle zvoleného způsobu provozování webového API.
Příklad nastavení:
{
    "language": "cze",
    "apiProtocol": "https",
    "apiServer": "enteam.leviom.cz",
    "apiPort": "443"
}

Ověření funkčnosti

Pro ověření dostupnosti webového GUI vložte do webového prohlížeče adresu, na které má být GUI dostupné, tedy např.
https://enteam.doména.cz
nebo
https://www.doména.cz/enteam
Pokud se v prohlížeči zobrazí přihlašovací stránka webového rozhraní informačního systému enTeam, je webové GUI nainstalováno správně.

Samotné přihlášení do aplikace není zatím funkční. Abyste se mohli přihlásit, je třeba zpřístupnit webové API na portu uvedeném v souboru enTeam.WebGui/assets/config/enteam-api-config.template.json (viz kapitola #URL Rewrite – Zpřístupnění webového API).

URL Rewrite – Přesměrování na https

Pro zvýšení bezpečnosti aplikace je třeba zajistit bezpodmínečné přesměrování uživatele na šifrovaný protokol https v případě, že zasílá požadavek přes nešifrovaný protokol http. Webový server IIS umožňuje zajištění této potřeby pomocí modulu URL Rewrite.
V případě provozování webového GUI na jiném webovém serveru lze použít obdobná rozšíření určená pro zvolenou platformu.

Předpoklady

Pokud není nainstalovaný modul URL Rewrite, je potřeba přidat jej přes Web Platform Installer (https://www.iis.net/downloads/microsoft/url-rewrite)
Poznámka: Po přidání rozšíření přes Web Platform Installer je nutné zavřít a znovu otevřít IIS Manager, aby bylo zobrazeno nové rozšíření

Postup

Bezpodmínečné přesměrování uživatele na šifrovaný protokol https lze zajistit přidáním a nastavením pravidla modulu URL Rewrite. Pro názornost uvádíme nastavení pro webové GUI, tj. webovou stránku enTeam.WebGui.

1. V nastavení modulu URL Rewrite webové stránky enTeam.WebGui (IIS Manager > Server > Sites > enTeam.WebGui > URL Rewrite) zvolte akci Add Rule(s)…
2. Ve zobrazeném dialogu zvolte Blank rule
   
3. Pravidlo nastavte následujícím způsobem
   

URL Rewrite – Zpřístupnění webového API

Dalším opatřením pro zvýšení bezpečnosti aplikace je zpřístupnění webového API na jediném, šifrovaném portu. To lze zajistit opět pomocí modulu URL Rewrite na základě prefixu cesty zasílaných požadavků.

Předpoklady

1. Pokud není nainstalovaný modul URL Rewrite, přidat jej přes Web Platform Installer (https://www.iis.net/downloads/microsoft/url-rewrite)
   Poznámka: Po přidání rozšíření přes Web Platform Installer je nutné zavřít a znovu otevřít IIS Manager, aby bylo zobrazeno nové rozšíření
2. V nastavení modulu URL Rewrite webové stránky enTeam.WebGui povolte použití následujících proměnných serveru (IIS Manager > Server > Sites > enTeam.WebGui > URL Rewrite > View Server Variables…)
   • HTTP_X_FORWARDED_HOST
   • HTTP_X_FORWARDED_PROTO
   • HTTP_X_FORWARDED_SCHEMA
3. Pokud není nainstalovaný modul Application Request Routing, přidat jej přes Web Platform Installer (https://www.iis.net/downloads/microsoft/application-request-routing)
   Poznámka:. Po přidání rozšíření přes Web Platform Installer je nutné zavřít a znovu otevřít IIS Manager, aby bylo zobrazeno nové rozšíření
4. V nastavení modulu Application Request Routing povolit Cache (IIS Manager > Server > Application Request Routing Cache > Server Proxy Settings… > Enable Proxy – zaškrtnout a potvrdit tlačítkem Apply v sekci Actions v pravém sloupci aplikace IIS Manager)
5. Webové GUI (nebo jiná aplikace) provozované jako webová stránka v IIS na portu 443 (https). V případě použití jiné aplikace je třeba ověřit, že její cesty nejsou v konfliktu s cestami webového API (/api/v1/* resp. /oauth/v1/*)

Postup

Zpřístupnění webového API na portu 443 lze zajistit přidáním a nastavením pravidla modulu URL Rewrite pro webové GUI, tj. webovou stránku enTeam.WebGui.

1. V nastavení modulu URL Rewrite webové stránky enTeam.WebGui (IIS Manager > Server > Sites > enTeam.WebGui > URL Rewrite) zvolte akci Add Rule(s)…
2. Ve zobrazeném dialogu zvolte Blank rule
   
3. Pravidlo nastavte následujícím způsobem
   
   Poznámka: Není-li webová stránka na serveru, kde je provozována, dostupná pod svým veřejným jménem, lze v poli Rewrite URL nahradit proměnnou {HTTP_HOST} za localhost.
   Poznámka: Provozujete-li webové rozhraní enTeam na portu 80 (tj. pod VPN), je třeba v proměnných HTTP_X_FORWARDED_PROTO a HTTP_X_FORWARDED_SCHEMA uvést hodnotu „http“.

Ověření funkčnosti

Pokud je vše nastaveno správně, je možné se do webového GUI informačního systému enTeam přihlásit a používat jej.

Často kladené otázky (FAQ)

Pod uživatelem se nelze připojit z enTeam.WebApi do DB Firebird 3.0+. Spojení z ostatních aplikací enTeam pod stejným uživatelem funguje

Firebird verze 3.0 představil novou metodu autentizace uživatelů – Secure Remore Password (SRP). Zatímco ostatní aplikace enTeam používají stávající metody autentizace, webové API se připojuje pomocí technologie využívající nejmodernější metodu SRP.

Každý databázový uživatel musí být založen právě tolikrát, kolika metodami se pod ním snažíme k DB připojit. Výpis všech uživatelů a jejich autentizačních metod lze získat SQL příkazem

SELECT U.SEC$USER_NAME, U.SEC$PLUGIN FROM SEC$USERS U;

Pokud ve Vaší DB chybí záznam uživatele s metodou autentizace SRP, lze jej přidat SQL příkazem

CREATE USER <uživatel> PASSWORD '<heslo>' USING PLUGIN Srp;

Typicky se tato situace objevuje u uživatele teambridge, pod jehož identitou se webové API připojuje do DB. Situace může nastat ale i u jiných uživatelů.

Ověření funkčnosti webového API končí chybou 500 nebo 502

Pokud ověření funkčnosti webového API dle kapitoly #Ověření funkčnosti končí chybou 500 Internal Server Error, příp. 502 Bad Gateway, lze příčinu chyby zjistit dle následujícího postupu:

1. Otevřete aplikaci Příkazová řádka (cmd.exe)
2. V Příkazové řádce přejděte do adresáře aplikace, ve které dochází k chybě, příkazem: cd <AplikaceAdresar>
   V příkazu nahraďte
   <AplikaceAdresar> za plnou cestu k adresáři s instalací aplikace, která vykazuje uvedenou chybu (např. c:\inetpub\wwwroot\enTeam.WebApi)
3. V Příkazové řádce spusťte požadovanou aplikaci
   <DotnetAdresar>\dotnet.exe Leviom.enTeam.WebApi.dll
   V příkazu nahraďte
   <DotnetAdresar> za plnou cestu k adresáři s instalací x86 varianty programu dotnet.exe (např. c:\Program Files (x86)\dotnet)

V příkazové řádce se zobrazí výpis, z něhož by mělo být možné důvod nefunkčnosti aplikace zjistit. Pokud výpisu aplikace nerozumíte, kontaktujte, prosím, technickou podporu společnosti Leviom.

Pokud aplikace vypíše do příkazové řádky tento text:
Hosting environment: Production
Content root path: c:\inetpub\wwwroot\enTeam.WebApi (může se lišit)
Now listening on: http://localhost:5000
Application started. Press Ctrl+C to shut down.,
byly odstraněny všechny chyby a aplikace je plně funkční. V takovém případě ji lze v Příkazové řádce ukončit stiskem Ctrl+C a znovu ověřit její funkčnost z webového prohlížeče dle kapitoly #URL Rewrite – Zpřístupnění webového API.Ověření funkčnosti.