Obsługa wielu tenantów w nAxiom

(Wersja nAxiom 1.14.0.11)

Przeczytasz w 21 min.

Spis treści

Wprowadzenie
1. Kompatybilność wsteczna
2. Licencjonowanie
Zmiany w architekturze nAxiom
Instalacja
Wdrożenie z obrazów Docker
Zarządzanie tenantami
Repozytoria plików
Baza danych administratora tenantów
Dodatek: Opis ustawień konfiguracyjnych

Wprowadzenie

Od wersji 1.11 nAxiom obsługuje tryb multitenancy. Oznacza to, że z jednej witryny nAxiom może korzystać kilku tenantów (osobnych organizacji). Każdy z tenantów korzysta z własnej instancji bazy danych, co zapewnia separację i bezpieczeństwo. Tenantami zarządza administrator tenantów (domyślny login: tenantsadmin, domyślne hasło: !Q2w3e4r%T), używając nowej aplikacji frontonowej TenantAdminSPA dostępnej pod adresem https://<bazowy-adres-naxiom>/tenantsadmin. Podstawowe dane tenantów są zapisywane w osobnej instancji bazy danych, do której ma dostęp tylko administrator tenantów.

Tenanci łączą się z witryną nAxiom, używając adresu URL https://<przedrostek-tenanta>.<bazowy-adres-naxiom>, gdzie przedrostek-tenanta to definiowany indywidualnie dla każdego tenanta ciąg znaków. Dla pierwszego tenanta ten przedrostek jest domyślnie pusty.

Kompatybilność wsteczna

Obecne wdrożenia produkcyjne nAxiom po aktualizacji do wersji 1.11 mogą działać bez zasadniczych zmian w konfiguracji z jednym tenantem (tryb single tenant).

Z uwagi na specyfikę implementacji funkcjonalności OCR jest ona dostępna tylko dla pierwszego tenanta. Trwają prace nad znalezieniem rozwiązania, które zapewni dostęp do tej funkcjonalności wszystkim tenantom.

Licencjonowanie

Każdy tenant korzysta z nAxiom w oparciu o własną licencję. Licencję musi zaimportować konsultant każdego tenanta po zalogowaniu się do aplikacji AdminSPA. Do weryfikacji licencji służy ciąg znaków podawanych jako wartość parametru Nazwa klienta. Dla pierwszego tenanta określa się go podczas instalacji, a dla kolejnych w aplikacji TenantAdminSPA.

Zmiany w architekturze nAxiom

W związku z obsługą wielu tenantów w architekturze platformy nAxiom pojawiło się kilka nowych komponentów:

tenantsadmin: serwis angularowy udostępniający GUI dla administratora tenantów
tenantsapi: serwis dotnetowy obsługujący połączenie z bazą danych administratora tenantów.
baza danych administratora tenantów: zawiera podstawowe dane poszczególnych tenantów, takie jak kod, nazwa, nazwa klienta (klucz licencji), przedrostek adresu URL do witryny nAxiom, parametry połączenia z bazą danych i inne; (domyślny format nazwy proponowany podczas instalacji to <nazwa_witryny>_tenantsAdmin)
instancje baz danych kolejnych tenantów

Instalacja

Podczas instalacji nowej witryny nAxiom tworzony jest login i baza danych administratora tenantów oraz login i baza danych pierwszego tenanta. W przypadku aktualizacji witryny z wersji nAxiom wcześniejszej niż 1.11, pierwszy tenant jest tworzony na podstawie dotychczasowej konfiguracji (pliki appsettings.json poszczególnych serwisów). Szczegóły instalacji opisano w Przewodniku instalacji.

W związku z wprowadzonymi zmianami nie jest już możliwa konfiguracja witryny, w której poszczególne serwisy nAxiom korzystały z różnych baz danych. Podczas aktualizacji parametry połączenia z bazą danych dla pierwszego tenanta są pobierane z pliku appsettings.json serwisu api.

Najważniejsze kwestie, o których należy pamiętać, to:

Aby umożliwić połączenia https dla wielu tenantów wymagany jest certyfikat SSL typu wildcard na poziomie bazowego adresu URL witryny nAxiom. Ten adres jest określany w polu Host w kroku konfiguracji serwera IIS podczas instalacji i zapisywany w pliku appsettings.json serwisu api. Przykładowo:

Adres bazowy	Certyfikat dla
domena.com	domena.com, *.domena.com
sub.domena.com	sub.domena.com, *.sub.domena.com
test.sub.domena.com	test.sub.domena.com, *.test.sub.domena.com

Instalacja serwisów tenantsapi i tenantsadmin musi być włączona (ustawienie domyślne).
Jeśli baza danych administratora tenantów nie istnieje, wymagane jest podanie poświadczeń administratora bazy danych (sysadmin albo co najmniej dbcreator i securityadmin).
Minimalny wymagany zestaw ról dla loginu do bazy administratora tenantów to dbcreator, securityadmin i public.

Wdrożenie z obrazów Docker

W przypadku wdrażania platformy nAxiom jako zestawu kontenerów, konieczne jest powołanie pierwszego tenanta. Można to zrobić na dwa sposoby, które szczegółowo opisano w artykule Wdrożenie nAxiom z obrazów Docker. Poniżej wypunktowano najważniejsze informacje.

Parametry połączenia z serwerem bazy danych dla bazy administratora tenantów podaje się w pliku appsettings-custom.json dla serwisu tenant-api.
W celu utworzenia pierwszego tenanta w aplikacji TenantAdminSPA należy uruchomić tylko kontenery serwisów tenant-admin i tenant-api, następnie należy zalogować się jako administrator tenantów (login: tenantsadmin, hasło:!Q2w3e4r%T) do aplikacji TenantAdminSPA pod adresem https://<bazowy_URL_nAxiom>/tenantsadmin i tam zdefiniować pierwszego tenanta zgodnie z opisem w dalszej części tego artykułu.
Alternatywnie, można przygotować pliki konfiguracyjne appsettings.json serwisów dotnetowych, dodać do ich nazw nazwy serwisów jako przedrostek (np. api_appsettings.json) i skopiować do folderu o nazwie toMigrate. Jeśli podczas uruchamiania pełnego zestawu kontenerów nAxiom taki folder zostanie wykryty w katalogu głównym wdrożenia, na podstawie plików konfiguracyjnych zostanie utworzony pierwszy tenant.

Zarządzanie tenantami

Do zarządzania tenantami służy odrębna aplikacja TenantAdminSPA dostępna pod adresem https://<bazowy_URL_nAxiom>/tenantsadmin. Łączy się ona z dedykowaną bazą danych, w której są przechowywane parametry konfiguracyjne poszczególnych tenantów. Po wpisaniu adresu w przeglądarce zostanie wyświetlone okno logowania.

Standardowe dane logowania to login tenantsadmin i hasło !Q2w3e4r%T. Po zalogowaniu zostanie wyświetlona strona aplikacji z menu po lewej stronie i listą tenantów w części głównej. Poszczególne pozycje menu opisano w kolejnych sekcjach. Aplikacja jest dostępna w wersji angielskojęzycznej.

Tenants list

Pozycja Tenants list wyświetla listę tenantów. Ustawienia każdego tenanta można edytować, klikając ikonę edycji w wierszu tenanta. Tenantów nie można usuwać, nieużywane definicje tenantów można dezaktywować. Do dodawania tenantów służy przycisk Add new tenant.

Dodawanie tenanta

Kliknij przycisk Add new tenanti postępuj zgodnie z poleceniami w kreatorze.

Code: kod tenanta; tylko znaki alfanumeryczne (a-z, A-Z, 0-9) i łączniki (-); kodu tenanta określonego w tym kroku nie można zmienić.
Database:
- New database: dla tworzonego tenanta zostanie utworzona nowa baza danych o podanych parametrach.
- Existing database: tenant zostanie powiązany z istniejącą bazą danych o podanych parametrach.
Database connection definition:
- Parameters: (domyślnie) należy podać parametry połączenia z bazą danych w polach:
  - Server name: adres serwera SQL Server.
  - Login: login do bazy danych; jeśli nie istnieje zostanie utworzony, zaleca się podanie loginu utworzonego z mocnym hasłem specjalnie dla administratora tenantów.
  - Password: Hasło do bazy danych (dostępny jest przycisk generowania mocnego hasła).
  - Database: Nazwa bazy danych pierwszego tenanta
- Connection string: należy podać ciąg połączenia w polu tekstowym Database connection string.
Dodawanie tenanta, krok 2.

Kliknij przycisk Create, aby utworzyć pierwszego tenanta w środowisku nAxiom. Wymagane jest podwójne potwierdzenie. Po utworzeniu wyświetlana jest strona edycji ustawień tenanta.

Po utworzeniu tenanta wymagany jest restart witryny nAxiom na serwerze IIS.

Edycja tenanta

Strona Edit tenant ma trzy karty z polami ustawień tenanta. Poniżej opisano ustawienia na poszczególnych kartach.

Karta Main

Identifier: identyfikator GUID tenanta; tylko do odczytu.
Code: kod definiowany podczas tworzenia tenanta; domyślnie używany jako przedrostek adresu URL dla tego tenanta; tylko do odczytu.
Name: nazwa tenanta.
Customer Name: ciąg znaków, na podstawie którego jest identyfikowana licencja danego tenanta (podczas pierwszego logowania konsultant tego tenanta musi zaimportować plik licencji zgodny z wartością w tym polu).
Description: opis tenanta.
Is active: przełącznik do aktywacji/dezaktywacji tenanta.

Nowy tenant jest zasze tworzony jako nieaktywny.

Karta Configuration

URL prefix: przedrostek w adresie URL witryny nAxiom; tylko znaki alfanumeryczne (a-z, A-Z, 0-9) i łączniki (-); użytkownicy końcowi z organizacji każdego tenanta logują się do witryny nAxiom, używając adresów różniących się przedrostkiem; przedrostek jest domyślnie taki sam, jak kod tenanta, ale można to zmienić; dla pierwszego tenanta powoływanego przez instalator przedrostek jest domyślnie pusty.
Tenant administrator e-mail: adres e-mail do użytkownika z rolą administratora u danego tenanta.
Settings: tekst w formacie JSON z ustawieniami konfiguracyjnymi, które można teraz ustawiać indywidualnie dla każdego tenanta, na przykład rozszerzenia nazw plików indeksowanych do wyszukiwania pełnotekstowego (o ile zostało skonfigurowane), ustawienia synchronizacji użytkowników i jednostek organizacyjnych z serwerem LDAP itp. Te ustawienia opisano w dodatku na końcu tego artykułu.
Logo: umożliwia ustawienie niestandardowego logo używanego w oknach logowania i wylogowania dla bieżącego tenanta; w celu ustawienia logo należy wybrać obraz, odpowiednio powiększyć go lub pomniejszyć i ustawić prostokątną ramkę na wybranym fragmencie obrazu; dostępne kontrolki:
- Select image: otwiera okno wyboru pliku;
- Clear logo: przywraca standardowe logo (ustawione w sekcji Global settings);
- Zoom-in/out: pomniejsza/powiększa obraz;
- Reset image: przywraca oryginalny rozmiar obrazu.
Edycja tenanta, karta Configuration, ustawienia Logo

Karta Database

Database connection definition:
- Parameters: (domyślnie) należy podać parametry połączenia z bazą danych w polach:
  - Server name: adres serwera SQL Server.
  - Login: Login do bazy danych.
  - Password: Hasło do bazy danych.
  - Database: Nazwa bazy danych pierwszego tenanta
- Connection string: należy podać ciąg połączenia w polu tekstowym Database connection string.

Global settings

Directory location...: katalog główny repozytoriów plikowych wszystkich tenantów; domyślnie <katalog_instalacyjny_nAxiom>\SystemRepositories; w tym katalogu każdy tenant ma własny podkatalog o nazwie takiej jak GUID tenanta, a w nim podkatalogi repozytoriów różnych zasobów (wiadomości e-mail, załączniki itp.).
Error logging level: poziom logowania komunikatów dla serwisów api i publicapi; taki sam dla wszystkich tenantów; dostępne wartości (poziomy są wymienione w kolejności od najniższej istotności, każdy poziom obejmuje także informacje z poziomów o wyższej istotności):
- Trace: szczegółowe informacje przydatne przy śledzeniu miejsca wystąpienia błędu na stronie;
- Debug: szczegóły na temat akcji podjętych przez system, odzwierciedlające jego aktualny stan;
- Info: wiadomości informacyjne odnoszące się do sposobu działania systemu;
- Warn: ostrzeżenia przed potencjalnym zagrożeniem w działaniu systemu przy wykonywaniu dalszej części kodu;
- Error: (wartość domyślna) błędy występujące podczas żądania wysyłanego przez użytkownika, umożliwiające dalszą pracę systemu;
- Fatal: błędy, które uniemożliwiają dalsze działanie systemu i powodują jego zawieszenie.
Logo: patrz opis powyżej .

User list

Wyświetla listę użytkowników z uprawnieniami do administrowania tenantami. Aby dodać użytkownika, kliknij przycisk Add new user i na wyświetlonej stronie podaj nazwę użytkownika, adres e-mail i hasło.

Każdy administrator tenantów może dodawać nowych administratorów oraz edytować istniejących. W celu zmiany hasła kliknij ikonę edycji dla danego administratora i podaj nowe hasło.

Repozytoria plików

W trybie obsługi wielu tenantów obowiązują nowe zasady dotyczące repozytoriów plikowych. I tak w nowych środowiskach repozytoria dyskowe wszystkich tenantów znajdują się w ścieżce określonej przez wartość parametru Directory location for relative paths of file repositories (TenantAdminSPA > Global settings).

Podkatalog dla każdego tenanta jest określony przez wartość klucza SubDirName w sekcji FileStorageConfiguration w ustawieniach konfiguracyjnych tenanta (TenantAdminSPA > Edit tenant > Configuration > Settings). Domyślnie ta wartość jest równa identyfikatorowi GUID tenanta.

Dodatkowo, drugi parametr w sekcji FileStorageConfiguration, AllowUseRepoFullDir, określa, czy konsultanci danego tenanta mogą definiować repozytoria, używając ścieżek względnych, czy bezwzględnych.

Dla nowych tenantów wartość domyślna to false — konsultanci mogą definiować repozytoria używając wyłącznie ścieżek względnych odnoszących się do podkatalogu tenanta w katalogu głównym repozytoriów.

W przypadku aktualizacji nAxiom z wersji sprzed obsługi wielu tenantów parametr ten ma wartość true. W takim przypadku konsultanci tego tenanta będą mogli określać repozytoria dyskowe, używając tylko ścieżek bezwzględnych.

W związku z tymi zmianami zmieniono także strukturę tabeli core.AttachmentRepositories. Usunięto z niej kolumnę Location i dodano trzy nowe:

TableName: nazwa tabeli w przypadku repozytorium bazodanowego.
AbsoluteDirectory: ścieżka bezwzględna do repozytorium dyskowego.
RelativeDirectory: ścieżka względna do repozytorium dyskowego.

Instalator ustawia wartość parametru AllowUseRepoFullDir na podstawie danych z kolumny AbsoluteDirectory w bazie danego tenanta. Jeśli ta kolumna jest pusta, parametr ma wartość false.

Aby dla konkretnego tenanta przejść ze ścieżek bezwzględnych na ścieżki względne, należy wykonać następujące kroki:

Utwórz katalog główny repozytoriów dyskowych (jeśli nie istnieje) zgodnie z wartością parametru Directory location for relative paths... na stronie Global settings w aplikacji TenantAdminSPA.
W katalogu głównym utwórz podkatalog o nazwie określonej przez klucz SubDirName w sekcji FileStorageConfiguration w ustawieniach konfiguracyjnych tenanta.
Skopiuj do tego podkatalogu katalogi repozytoriów wraz z zawartością.
Usuń dane z kolumny AbsoluteDirectory w tabeli core.AttachmentRepositories w bazie danych tenanta.
Zmień wartość klucza AllowUseRepoFullDir z true na false.
Uruchom ponownie witrynę.
Poleć konsultantom tenanta utworzenie repozytoriów o nazwach odpowiadających przenoszonym repozytoriom.

Przykład:

W wyniku aktualizacji witryny nAxiom z repozytoriami dyskowymi tworzony jest pierwszy tenant o identyfikatorze GUID 82229a18-dbd5-44b7-8266-c892a369676a, dla którego klucz AllowUseRepoFullDir ma wartość true. Strukturę katalogów repozytoriów przedstawiono poniżej.

Struktura repozytoriów, ścieżki bezwzględne

Aby przełączyć tego tenanta na korzystanie ze ścieżek względnych, należy skopiować katalogi repozytoriów z zawartością do katalogu jak na ilustracji poniżej oraz wykonać pozostałe kroki powyższej procedury.

Struktura repozytoriów, ścieżki względne

Ścieżka C:\inetpub\n155_1100nax\SystemRepositories\ to wartość parametru Directory location for relative paths....

Baza danych administratora tenantów

Baza danych administratora tenantów zawiera kilka tabel z ustawieniami tenantów oraz administratorów tenantów. Dane tenantów są zapisywane w tabeli ta.Tenants, która ma następujące kolumny:

Id (uniqueidentifier): generowany automatycznie GUID tenanta.
Name (nvarchar(500)): nazwa tenanta.
Code (nvarchar(50)): kod tenanta.
UrlPrefix (nvarchar(50)): przedrostek adresu URL do witryny nAxiom; domyślnie wartość taka jak Code.
IsActive (bit): flaga aktywności tenanta.
ConnectionString (nvarchar(2000)): parametry połączenia z bazą danych tenanta.
Settings (nvarchar(MAX)): konfiguracja tenanta w formacie JSON.
Description (nvarchar(500)): opis tenanta.
AdminEmail (nvarchar(254)): adres e-mail administratora tenanta.

Ponadto baza danych zawiera tabelę z ustawieniami globalnymi oraz zestaw tabel dotyczących administratorów tenantów.

Z wyjątkiem sytuacji opisanej powyżej (zmiana ścieżek do repozytoriów), administrator tenantów nie ma potrzeby bezpośredniej ingerencji w dane zapisane w tabelach.

Dodatek: Opis ustawień konfiguracyjnych

Podsumowanie: W aplikacji TenantsAdminSPA, w ustawieniach każdego tenanta na karcie Configuration są dostępne ustawienia konfiguracyjne z pliku appsettings.json serwisu api. Ustawienia te umożliwiają zaawansowaną konfigurację tenantów.

IndexableFileExtensions: określa rozszerzenia nazw plików indeksowanych przez usługę wyszukiwania pełnotekstowego.
CoreTablesModificationEnabled: pozwala włączyć dostęp do tabel systemowych core.SyncOUInstances i core.SyncUserProfiles w kreatorze modeli danych, których edycja jest wymagana w przypadku synchronizacji struktury organizacyjnej i listy użytkowników z systemem zewnętrznym. Ponadto w sekcji SchemaSettings można określić nazwy schematów tabel systemowych (domyślnie core) i tabel serwisu auth (domyślnie auth) oraz schematów tabel użytkownika (ustawienie domyślne * odpowiada dowolnym schematom).
OpenLDAPConf i StructureSynchronizationConfiguration: sekcje odpowiadające konfiguracji synchronizacji profili użytkowników i struktury organizacyjnej z serwerem usług katalogowych LDAP. Szczegółowy opis zawiera osobny artykuł Synchronizacja z usługami katalogowymi
PageTitles: LoginPage: pozwala określić niestandardowy tytuł strony logowania do nAxiom (wartość domyślna Logowanie).
EmailSenderConf: AddressFrom: adres e-mail administratora danego tenanta, obecnie nie używany.
Security: HideResetPasswordLogic: decyduje, czy w oknie logowania ma być widoczny link do resetowania hasła.
ExternalLogin: ta sekcja zawiera ustawiea konfiguracyjne logowania z wykorzystaniem zewnętrznego dostawcy usług uwierzytelniania. Ustawienia te zostały opisane w artykule Konfiguracja logowania zewnętrznego do nAxiom.
WindowsLogin: w tej sekcji można określić konfigurację logowania z wykorzystaniem kontrolera domeny Windows; zawiera ona następujące parametry:
- UseWindowsLogin: włącza uwierzytelnianie Windows,
- DisplayName: tytuł okna logowania (domyślnie Logowanie Windows),
- AutomaticAuthentication: określa, czy logowanie ma się odbywać automatycznie; jeśli nie będzie wyświetlane okno logowania,
- AutomaticRedirect: określa, czy podczas logowania do nAxiom ma następować przekierowanie do kontrolera domeny WIndows z wcelu zalogowania,
UseADAuthentication: pozwala włączyć uwierzytelnianie na serwerze usług LDAP,
DefaultCulture: określa domyślne ustawienia nardowoe dla indywidualnych tenantów (wartość domyślna pl-PL),
SimpleLoginPage: pozwala włączyć wyświetlanie strony uproszczonego logowania, przez którą użytkownik loguje się do nAxiom używając kodu numerycznego ustawianego w profilu użytkownika,
FileStorageConfiguration: w tej sekcji określa się konfigurację przechowywania plików statycznych (załączniki, wiadomości e-mail, rozpoznane pliki OCR i inne) dla danego tenanta; zawiera ustawienia:
- SubDirName: nazwa folderu w systemie plików hosta aplikacji, w którym będą znajdować się repozytoria plikowe tenanta; domyślnie jest to identyfikator GUID tenanta. Dla wdrożeń w środowisku Windows jest to podfolder folderu SystemRepositories w katalogu instalacyjnym nAxiom,
- AllowUseRepoFullDir: określa, czy użytkownicy tego tenanta mogą określać lokalizację swoich repozytoriów plikowych za pomocą ścieżek bezwzględnych; domyślnie parametr jest włączony dla pierwszego tenanta w przypadku aktualizacji witryny nAxiom, a wyłączony w innych przypadkach. Jeśli parametr jest wyłączony, użytkownicy tenanta mogą tworzyć repozytoria plikowe tylko w folderze określonym parametrem SubDirName.

Wszelkie zmiany tych parametrów konfiguracyjnych wymagają restartowania witryny nAxiom (w środowisku Windows należy ponownie uruchomić witrynę w Menedżerze IIS).