Zum Hauptinhalt springen

Installation

2 Installation des iCL-Portals (einzelner Server)​

Die folgenden Abschnitte beschreiben den Installationsprozess für alle erforderlichen Komponenten des iCL-Systems. Es wird empfohlen, die Komponenten in der Reihenfolge dieses Handbuchs zu installieren.

2.1 Installation des Back-Ends​

  • Installieren Sie alle erforderliche Software wie in 1.4 aufgeführt

  • Erstellen Sie eine neue Datenbank für das iCL Portal in SQL Management Studio

  • Führen Sie das folgende Skript aus, um sicherzustellen, dass die Snapshot-Isolation für die Datenbank aktiviert ist 

       DECLARE @databaseName sysname;
       SET @databaseName = (SELECT db_name());
       DECLARE @SQL varchar(1000);
       SET @SQL = 'IF EXISTS (SELECT NAME FROM sys.databases where NAME = N'''+@databaseName+''' AND [snapshot_isolation_state] = 0)
       BEGIN
           ALTER DATABASE ['+@databaseName+'] SET ALLOW_SNAPSHOT_ISOLATION ON
           ALTER DATABASE ['+@databaseName+'] SET READ_COMMITTED_SNAPSHOT ON WITH ROLLBACK IMMEDIATE
       END'
       Exec (@SQL)

  • Notieren Sie sich den Verbindungsstring zur Datenbank.

2.2 Installation des Web-Frontends​

  • Installieren Sie die gesamte erforderliche Software, wie in 1.4 aufgeführt.

  • Erstellen Sie eine neue IIS Web-Site

  • Stellen Sie sicher, dass der Anwendungspool, der für diese Website erstellt wurde, mit .NET 4.0 läuft

  • Kopieren Sie alle Dateien aus dem Ordner web-frontend in den Stammordner Ihrer Website. In diesem Beispiel wäre dies: c:\inetpub\icl_portal.

    In diesem Screenshot sehen Sie die beiden wichtigen Konfigurationsdateien für die Anpassung des iCL Portal Web-Frontends: die NLog.config und die Web.config Datei.

  • Stellen Sie sicher, dass der Benutzer, der den Anwendungspool ausführt, vollen Zugriff auf den Ordner App_Data hat, da dies der Standardspeicherort für alle Dateien und Protokolle ist.

    Dazu müssen Sie den Namen des Anwendungspools herausfinden, auf dem iCL Portal läuft. In diesem Beispiel iClPortalAppPool. Öffnen Sie dann die Sicherheitseinstellungen des Ordners App_Data und fügen Sie den Benutzer des Anwendungspools mit Vollzugriff hinzu. Als Benutzernamen, verwenden Sie IIS AppPool\apppoolname, sprich IIS AppPool\iClPortalAppPool in diesem Beispiel. Klicken Sie nicht auf "Suchen" oder "Namen überprüfen", da diese den speziellen Benutzer nicht finden werden!

  • Halten Sie die Website an, damit Sie das Portal für den ersten Start konfigurieren können:

  • Konfigurieren Sie die Bindungen des Web-Frontends und stellen Sie sicher, dass es eine HTTPS-Bindung gibt, die mit einem vertrauenswürdigen Zertifikat gesichert ist.

    Hinweis

    In Produktionsumgebungen werden nur HTTPS-Verbindungen unterstützt, da das System sonst kompromittiert werden könnte!

    Hinweis

    Wenn Sie eine separate Datenbank für die Speicherung der Hintergrundjobs erstellt haben, stellen Sie sicher, dass auf dem Server, auf dem das iCL Portal Web-Frontend läuft, der Dienst Distributed Transaction Coordinator läuft und den Starttyp Automatic hat:

    Hinweis

    Die standardmäßige web.config von iCL Portal enthält einen standardmäßigen machineKey, der zur Verschlüsselung von Token für die E-Mail-Verifizierung und die Passwortwiederherstellung verwendet wird. Dieser machineKey muss auf allen Web-Frontends derselbe sein! Wir empfehlen Ihnen dringend, Ihre eigenen machineKeys zu erstellen. Eine Anleitung dazu finden Sie hier.

2.3 Web-Frontend konfigurieren​

Die grundlegende Konfiguration des iCL Portal Web-Frontends erfolgt über die Bearbeitung der Web.config.

Hinweis

Für eine frische Installation, erstellen Sie eine Web.config mit diesen Inhalten im den Root-Ordner des iCL Portals.

Öffnen Sie Web.config in Ihrem bevorzugten Texteditor und navigieren Sie zum Element <appSettings>. Dieser Knoten enthält alle relevanten Konfigurationsoptionen.

2.3.1 Konfigurieren Sie Ihren icl-Portalschlüssel​

Suchen Sie nach dem Element mit dem Schlüssel License.Key und geben Sie dort den Lizenzschlüssel an, den Sie beim Kauf von iCL Portal erhalten haben: ``xml

<add key="License.Key" value="" />

#### 2.3.2 Konfigurieren Sie die Verbindung zur Sql Server Datenbank: 
iCL Portal verfügt über zwei logisch getrennte Datenbanken, deren Verbindungen im Element `<connectionStrings>` angegeben werden können: 
```xml
<connectionStrings>
    <add name="Default" connectionString="Data Source=SERVERNAME\INSTANCENAME;Initial Catalog=DATABASENAME;Integrated Security=True" providerName="System.Data.SqlClient" />
  </connectionStrings>`

Die Standard-Verbindung ist diejenige, die alle relationalen Daten des iCL-Systems speichert.

Hinweis

Bei Einzelserver-Installationen müssen Sie sicherstellen, dass Sie ein Login für den Benutzer des Anwendungspools erstellen. Fügen Sie ein Login für den Benutzer IIS AppPool\apppoolname hinzu - in unserem Beispiel: IIS AppPool\iClPortalAppPool.

Klicken Sie nicht auf Suchen, da dies einen ungültigen Benutzer auflöst!

Hinweis

iCL Portal verwaltet das Schema der Datenbank und die Migrationen selbst. Beim ersten Start wird es versuchen, alle erforderlichen Tabellen, Ansichten, gespeicherten Prozeduren usw. zu erstellen. Daher benötigt es db_owner Berechtigungen für beide Datenbanken!

Um Datenbanken für neue Tenants zu erstellen, benötigt es zusätzlich die Rolle `db_creator`.

Das Attribut connectionString erfordert eine ADO.NET-Verbindungszeichenfolge. Das folgende Beispiel zeigt die Konfiguration mit einer Datenbank Portal auf einer benannten MSSQL-Instanz SQLSERVER auf einer Maschine namens SQL unter Verwendung der integrierten Sicherheit. ``xml

``` Das folgende Beispiel verwendet die SQL-Server-Sicherheit mit USERNAME und PASSWORD. ```xml```

Das folgende Beispiel zeigt, wie man einen Benutzernamen und ein Passwort angibt, eine standardmäßige Absenderadresse festlegt und die SSL-Verschlüsselung aktiviert:

<system.net>
    <mailSettings>
      <smtp deliveryMethod="Network" from="noreply@mycorp.com">
        <network defaultCredentials="false" host="smtp.mycorp.com" port="587" userName="mailuser@mycorp.com" password="somepassword" enableSsl=`true`/>
      </smtp>
    </mailSettings>
  </system.net>

Die Syntax des Netzwerkelements wie hier dokumentiert 

<network  
  clientDomain="string"
  defaultCredentials="true|false"  
  enableSsl="true|false"  
  host="zeichenkette"
  passwort="zeichenkette"  
  port="ganze Zahl"
  targetName="Zeichenfolge"  
  userName="string"  
/>

2.3.5 Ferndiagnose​

Im iCL Portal ist die Ferndiagnose standardmäßig aktiviert. Diese senden nicht vertrauliche Informationen wie aufgetretene Ausnahmen und Stack Traces an einen zentralen Dienst, der von Opti-Q gehostet wird.

Konfigurieren Sie daher die Firewall des iCL Portal Web-Frontends so, dass ausgehende Verbindungen auf Port 443 erlaubt sind. Andernfalls werden wir keine Diagnoseinformationen erhalten.

Die Einstellung mit dem Schlüssel iKey im Element <appSettings> enthält den Api-Schlüssel, der für den Zugriff auf diesen Dienst erforderlich ist. :::Gefahr Ändern Sie den iKey nur auf Anraten eines Opti-Q-Mitarbeiters, da wir sonst keinen vollständigen Support leisten können. ::: Außerdem gibt es ein zusätzliches Element <applicationinsights.tags>, das zusätzliche Metadaten enthält, die an unseren Dienst übermittelt werden, um unseren Kunden und die Umgebung (Dev/Taging/Production) identifizieren zu können

 <applicationinsights.tags>
    <add key="Kunde" value="IhrFirmenname" />
    <add key="umgebung" value="produktion" />
    </applicationinsights.tags>

2.3.6 Konfigurieren Sie die Protokollierung durch Bearbeiten der Datei nlog.config​

iCL Portal verwendet NLog, um Diagnoseinformationen im lokalen Dateisystem zu protokollieren. Dieser Logging-Mechanismus ist gepuffert, um eine minimale Auswirkung auf die Leistung zu gewährleisten, erwarten Sie also nicht, dass die Log-Meldungen sofort erscheinen. Standardmäßig werden die Protokolldateien in den APP_DATA-Ordner des Web-Frontends geschrieben.

Hinweis

Wenn Sie noch keine Datei NLog.config in Ihrem Web-Frontend haben, erstellen Sie eine NLog.config Datei mit diesen Inhalten im Stammordner des iCL Portals.

Zum Ändern der Protokollierung, NLog.config in Ihrem bevorzugten Texteditor

  • Standardmäßig erstellt Nlog seine Protokolldateien im lokalen App_Data-Ordner. Um dies zu ändern, editieren Sie die Pfade, die mit ${basedir}\App_Data beginnen, um auf den gewünschten Speicherort zu verweisen. Beachten Sie, dass auch absolute Pfade unterstützt werden.
    Hinweis

    Änderungen an der NLog.config sollten fast sofort wirksam werden. Recyceln Sie den Anwendungspool nicht und starten Sie den IIS nicht neu!

  • Standardmäßig ist NLog so konfiguriert, dass nur Meldungen der Stufe WARN protokolliert werden. Wenn Sie eine ausführlichere Protokollierung konfigurieren möchten, öffnen Sie die NLog.config und ändern Sie die folgende Zeile
<logger name="*" minlevel="Warn" writeTo="Trace" />

zu

<logger name="*" minlevel="Debug" writeTo="Trace" />

2.3.7 Konfigurieren von zusätzlichen Plugins​

iCL Portal ermöglicht die Erstellung von Plugins zur Integration mit Ihren Unternehmenssystemen. Falls wir ein Plugin für Sie entwickelt haben, erhalten Sie ein separates Paket mit Installationsanweisungen. Diese bestehen meist nur aus dem Kopieren einiger zusätzlicher dlls in das bin-Verzeichnis Ihres iCL Portal Web-Frontends und dem Hinzufügen eines weiteren appSettings Elements zu Ihrer Web.config.

2.3.8 Starten Sie die iCL Portal Website​

Sobald die Konfiguration abgeschlossen ist, starten Sie die iCL Portal-Website und führen Sie die letzten Konfigurationsschritte mit Ihrem bevorzugten Browser aus.

2.3.9 Sytem/Host - Konfiguration​

iCL Portal unterstützt mehrere Mandanten. Um Tenants zu verwalten, müssen Sie sich als Host-Admin anmelden. Während des Setups wird ein einzelner Host-Admin - der zu keinem Tenant gehört - mit einem Standardpasswort angelegt. Um Ihr System zu sichern, ist es unbedingt erforderlich, sich mit diesem Benutzer anzumelden und sein Passwort zu ändern.

Loggen Sie sich dazu ein, indem Sie das Textfeld Mandant leer lassen und den Benutzernamen admin mit dem Standardpasswort 123qwe verwenden

Um es zu ändern, navigieren Sie zu Einstellungen/Benutzer und klicken Sie auf die Schaltfläche des Systemadministrators

Wenn Sie als Host-Administrator angemeldet sind, müssen Sie den Lizenzschlüssel für das iCL Portal konfigurieren. Navigieren Sie dazu zu den Einstellungen und in der Kategorie "Allgemein" finden Sie das Textfeld "Lizenz-ID":

Geben Sie den Lizenzschlüssel (z.B.: 327d75a8-64b5-49ac-bf90-2544229dbeca) ein, den Sie von Opti-Q erhalten haben, und klicken Sie auf Speichern.

2.3.10 Mandant erstellen​

iCL Portal unterstützt mehrere Mandanten, jeder mit einer vollständig isolierten Umgebung. Um das Portal zu betreiben, ist ein Standard-Mandant erforderlich.

  • Navigieren Sie dazu zu Einstellungen/Mandanten und klicken Sie auf ERSTELLEN, um einen neuen zu erstellen. Vergewissern Sie sich, dass der Tenant-Name nur aus Buchstaben besteht, und klicken Sie dann erneut auf CREATE

    Anschließend wird ein neuer Mandant mit einem Standardadministrator für diesen Mandanten erstellt. Dies kann ein oder zwei Minuten dauern.

2.3.11 Konfigurieren des neuen Mandanten​

  • Um sich in diesen Tenant einzuloggen, melden Sie sich zunächst als Host-Admin in der oberen rechten Ecke ab

    und navigieren Sie zurück zum Anmeldebildschirm

  • Auf dem Anmeldebildschirm melden Sie sich mit dem Tenancy-Namen an, den Sie gerade erstellt haben (in diesem Beispiel contoso) dem Benutzernamen admin und dem Standardkennwort 123qwe

  • Sobald Sie angemeldet sind, ändern Sie dieses Passwort über das Menü in der oberen linken Ecke sofort in ein sicheres Passwort:

  • Danach kann man unter Einstellungen/Benutzer beliebig viele Benutzer für diesen Tenant anlegen.

  • Abschließend laden Sie Ihre Lizenzdateien in SETTINGS/LICENSES hoch, indem Sie die Dateien per Drag & Drop einzeln in die Liste ziehen

2.3.12 [optional] Konfigurieren Sie die ws-Verbundauthentifizierung (Azure Entra ID)​

Während iCL Portal die Authentifizierung selbst mit OAuth 2.0 Bearer Token Authentifizierung handhaben kann, können Sie zusätzliche Authentifizierungsanbieter hinzufügen. Der erste offiziell unterstützte Anbieter ist WS Federation. Dies ermöglicht Ihren Benutzern, sich mit einem Klick anzumelden, anstatt ihre Passwörter einzutippen.

Sobald Sie die Azure Entra ID-Integration korrekt konfiguriert haben, wird sie bei den Benutzern als "Externer Anmeldeanbieter" aufgeführt:

Hinweis

Externe Login-Provider werden zwar prinzipiell unterstützt, können aber nur für einen einzigen Mandanten konfiguriert werden. Dies ist derzeit eine Rahmenbeschränkung, die wir in kommenden Versionen von iCL Portal überwinden wollen.

Hinweis

Unter der Haube wird iCL Portal den Benutzer nur über Azure Entra ID authentifizieren. Sobald Azure Entra ID den Benutzer zurück zu iCL Portal umleitet, wird ein neuer Benutzer in der Datenbank erstellt und erhält die von Ihnen definierte Standardrolle. Für den iCL-Portal-Administrator, der Benutzer zu Rollen und Teams zuweist, sehen Benutzer, die von Azure Entra ID kommen, identisch aus wie Benutzer, die von iCL Portal kommen, und sie werden auch auf dieselbe Weise behandelt.

2.3.12.1 Erstellen einer App-Registrierung im Azure Portal​

Um Azure Entra ID als externen Authentifizierungsanbieter einzurichten, müssen wir Azure Entra ID zunächst mitteilen, dass unsere iCL Portal-Anwendung existiert und Azure Entra ID zur Authentifizierung von Benutzern verwenden darf. Gehen Sie dazu auf https://portal.azure.com/#blade/Microsoft_AAD_IAM/ActiveDirectoryMenuBlade/RegisteredApps und erstellen Sie eine neue App-Registrierung. Als Beispiel konfigurieren wir eine App-Registrierung mit dem FQDN unseres Testsystems: https://testportal.opti-q.com (Ersetzen Sie diesen durch den FQDN Ihrer iCL Portal-Installation)

Sobald dies geschehen ist, öffnen Sie Einstellungen/Eigenschaften und kopieren Sie die App ID Uri.

Wir werden es als ADFS_Wtrealm verwenden.

Gehen Sie nun zurück zur Übersicht App-Registrierungen und öffnen Sie Endpunkte

Kopieren Sie dort die Federation Metadata Document url.

Wir werden es als ADFS_MetadataAddress verwenden.

Als Nächstes gehen Sie zurück zu Ihrer iCL Portal Web.config, um die Azure Entra ID-Authentifizierung auf der iCL Portal-Seite einzurichten.

2.3.12.2 Registrierung von Azure Entra ID als externer Authentifizierungsanbieter in iCL Portal​

Wir haben Azure Entra ID mitgeteilt, dass es unserer iCL Portal-Installation vertrauen kann, nun müssen wir iCL Portal mitteilen, dass Azure Entra ID ebenfalls verwendet werden kann. Um dies zu tun, öffnen Sie die Web.config und fügen Sie die folgenden xml-Elemente zum <appSettings> Knoten hinzu:

<appSettings>
    <!-- . . . -->


    <!-- windows Azure Entra ID -->
    <add key="ADFS_Caption" value="Azure Entra ID"/>
    <add key="ADFS_MetadataAddress" value="https://login.microsoftonline.com/0585ddbb-4b3c-407a-a707-b0bf65fa11cd/federationmetadata/2007-06/federationmetadata.xml"/>
    <add key="ADFS_Wtrealm" value="https://icltestportal.onmicrosoft.com/e7053192-ae66-4dc5-94c7-a03dad1444ff"/>
    <add key="ADFS_ImplicitlyRegister" value="true" />
    <add key="ADFS_TenancyName" value="Demo" />
    <add key="ADFS_DefaultRoles" value="User" />
    <!-- <add key="ADFS_UserIdClaimName" value="http://schemas.microsoft.com/identity/claims/objectidentifier" /> -->
    <!-- <add key="ADFS_UserNameClaimType" value="http://some-claim-id" /> -->
    <!-- <add key="ADFS_UpdateLocalUserProperties" value="true" />-->

    <!-- . . . -->

  </appSettings>

ADFS_Caption ist einfach der Text, der den Benutzern auf dem Anmeldebildschirm angezeigt wird, sodass Sie hier konfigurieren können, was Sie wollen.

Für ADFS_MetadataAddress geben Sie die URL ein, die Sie im vorherigen Schritt kopiert haben (Federation Metadata Document)

Für ADFS_Wtrealm geben Sie die Url ein, die Sie im vorherigen Schritt kopiert haben (App ID Uri)

ADFS_ImplicitlyRegister weist iCL Portal einfach an, automatisch ein neues Benutzerprofil zu erstellen, wenn sich jemand zum ersten Mal mit Azure Entra ID anmeldet. (Hinweis: dies ist die einzige unterstützte Option im Moment!)

ADFS_TenancyName teilt iCL Portal mit, welchem Tenant die von Azure Entra ID kommenden Logins zugeordnet werden sollen. (Beachten Sie, dass derzeit nur ein einziger Tenant unterstützt wird!) In diesem Beispiel werden die Benutzer im Tenant Demo erstellt. Bitte ändern Sie diesen in einen gültigen Tenant-Namen.

ADFS_DefaultRoles legt fest, welche Rolle die neu erstellten Benutzerprofile erhalten sollen. Dies kann Benutzer, Koordinator oder Admin sein. In den meisten Fällen ist es am besten, die Rolle Benutzer beizubehalten, da sie die am wenigsten privilegierte ist.

ADFS_UserIdClaimName ist eine optionale Einstellung. (Um sie zu verwenden, müssen Sie sie zuerst auskommentieren!) Sie kann verwendet werden, um einen bestehenden AD-Anspruch auf die ExternalId/Reference eines Benutzers abzubilden. In den meisten Fällen wird der Standardwert (http://schemas.microsoft.com/identity/claims/objectidentifier) die beste Wahl sein. Er ordnet die Objekt-ID des Active Directory-Benutzers dem Feld Referenz des iCL-Portal-Benutzers zu:

Wenn diese Option aktiviert ist, ist der definierte Claim verpflichtend

Wenn diese Option aktiviert ist, muss _jedes Benutzer-Token diesen Claim enthalten. Andernfalls schlägt die Authentifizierung fehl.

ADFS_UserNameClaimType ist eine weitere optionale Einstellung. (Um sie zu verwenden, müssen Sie sie zuerst auskommentieren!) Standardmäßig wird der Benutzername für jeden Benutzer, der aus Azure Entra ID kommt, von der E-Mail-Adresse des Benutzers abgeleitet. Der Grund dafür ist, dass dieser Claim immer vorhanden und eindeutig ist. Wenn Sie den Wert eines anderen Claims als Benutzernamen verwenden möchten, können Sie diesen mit der Einstellung ADFS_UserNameClaimType definieren.

Der Claim ist optional

Im Gegensatz zu ADFS_UserIdClaimName ist das Vorhandensein des definierten Claims optional, auch wenn diese Option aktiviert ist. Wenn sich ein Benutzer authentifiziert und das entsprechende Token keinen passenden Claim enthält, greift das System auf die E-Mail-Adresse des Benutzers zurück, um einen eindeutigen Benutzernamen zu erstellen.

Stellen Sie die NLog- Log-Stufe auf Info ein, um die Claims zu sehen

Ein Anmeldeversuch wird mit allen vorhandenen Claims protokolliert

2024-05-16 13:54:07.0207|log:iCL.Portal.Controllers.AccountApiController|thr:54|DEBUG|usr:|ten:|External login with claims from https://sts.windows.net/0585ddbb-4b3c-407a-a707-b0bf65fa71eb/:
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/nameidentifier:3nzHVNNP4Dx84nZ6Bttx1vtYLhVPQxG5NxdRjtLQbek
http://schemas.microsoft.com/identity/claims/tenantid:0585ddbb-4b3c-407a-a707-b0bf65fa71eb
http://schemas.microsoft.com/identity/claims/objectidentifier:85416830-f49e-43bf-87a8-204284ef5df3
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/name:gadget@icltestportal.onmicrosoft.com
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname:Gadgetto
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname:Antoine Gerald
http://schemas.microsoft.com/identity/claims/displayname:inspecteur gadget
http://schemas.microsoft.com/identity/claims/extn.METAID:48049BA322B3526D6XXX
http://schemas.microsoft.com/identity/claims/identityprovider:https://sts.windows.net/0585ddbb-4b3c-407a-a707-b0bf65fa71eb/
http://schemas.microsoft.com/claims/authnmethodsreferences:http://schemas.microsoft.com/ws/2008/06/identity/authenticationmethod/password
http://schemas.microsoft.com/claims/authnmethodsreferences:http://schemas.microsoft.com/claims/multipleauthn
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationmethod:urn:oasis:names:tc:SAML:2.0:ac:classes:Password
http://schemas.microsoft.com/ws/2008/06/identity/claims/authenticationinstant:2024-05-16T13:52:44.984Z
http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress:gadget@icltestportal.onmicrosoft.com

Unmittelbar danach sehen Sie, ob der definierte ADFS_UserNameClaimType gefunden wurde.

  1. Keine passender Claim gefunden:
2024-05-16 13:54:07.0207|log:iCL.Portal.Controllers.AccountApiController|thr:54|INFO|usr:|ten:|Custom 'UserNameClaimType' http://some.random.non-existent.claim.type was provided, but was not present in the token. Falling back to e-mail.
  1. Geeigneter Claim gefunden, aber keine Aktualisierung des bestehenden Benutzernamens
2024-05-16 13:54:07.0207|log:iCL.Portal.Controllers.AccountApiController|thr:108|INFO|usr:|ten:|[ADFS_ImplicitlyRegister] Custom 'UserNameClaimType' http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname was provided and found in token: 'mmuller' will be used as username
  1. Passender Claim gefunden und ADFS_UpdateLocalUserProperties aktiviert -> Der Benutzername wird aktualisiert
2024-05-16 13:54:07.0207|log:iCL.Portal.Controllers.AccountApiController|thr:108|INFO|usr:|ten:|[ADFS_ImplicitlyRegister] Custom 'UserNameClaimType' http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname was provided and found in token: 'mmuller' will be used as username
2024-05-16 13:54:08.9106|log:iCL.Portal.Controllers.AccountApiController|thr:108|INFO|usr:|ten:1|[ADFS_UpdateLocalUserProperties] Custom 'UserNameClaimType' http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname was provided and found in token: 'mmuller' will be used as username
Hinweis

Sie können dies verwenden, um Benutzer in iCL Portal im Voraus zu erstellen und sie Teams zuzuweisen oder ihnen globale Rollen zu geben. Sobald sich der Benutzer mit seinem Azure Entra ID-Konto anmeldet, übernimmt er den iCL Portal-Benutzer.

Bitte beachten Sie jedoch, dass die Eigenschaften des AD-Benutzers (Vorname, Nachname, ...) nicht automatisch auf den iCL-Portal-Benutzer übertragen werden. Um dieses Verhalten zu aktivieren, müssen Sie die Einstellung ADFS_UpdateLocalUserProperties auf true setzen. Damit werden jedes Mal, wenn sich ein AD-Benutzer anmeldet, seine AD-Eigenschaften (E-Mail, Vorname und Nachname) erneut auf den iCL-Portal-Benutzer angewandt.

2.3.12.3 Erforderliche Ansprüche​

Wie bereits erwähnt, erstellt iCL Portal bei der Anmeldung der Benutzer über einen externen Authentifizierungsanbieter implizit ein lokales Benutzerprofil für sie, das dann von lokalen iCL Portal-Administratoren verwendet werden kann, um ihnen Rollen zuzuweisen oder sie zu Mitgliedern eines Teams zu machen. Um Benutzer zu erstellen, muss der Authentifizierungsanbieter einen minimalen Satz von Ansprüchen zur Verfügung stellen. Diese drei Ansprüche sind:

  1. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/emailaddress, der sowohl als Benutzername als auch als E-Mail Adresse verwendet wird.
  2. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/givenname, der als Vorname des Benutzers festgelegt wird
  3. http://schemas.xmlsoap.org/ws/2005/05/identity/claims/surname, der als Nachname des Benutzers festgelegt wird
Hinweis

Wenn diese Angaben nicht vorhanden sind, kann sich der Benutzer nicht anmelden.

Wie bei Azure Entra ID sind dies die Eigenschaften eines Benutzers, die festgelegt werden müssen:

3 Installation von iCL Portal (Multi-Server)​

Für ein Multi-Server-Szenario müssen Sie eine weitere virtuelle Maschine erstellen und den Anweisungen ab 2 folgen. Beachten Sie, dass Sie jederzeit weitere Frontends hinzufügen können, sofern der Load Balancer dies unterstützt. Tipp: Wenn es um die web.config geht, sollten Sie in der Lage sein, diese einfach vom ersten Web-Frontend zu kopieren und auf dem zweiten Rechner zu verwenden. Es sind mehrere zusätzliche Schritte erforderlich: Einrichten des Load Balancer und Einrichten von redis.

3.1 Einrichten des Load Balancers​

In diesem Szenario kann jeder beliebige Load Balancer eines Drittanbieters verwendet werden, daher ist die Einrichtung nicht Gegenstand dieses Handbuchs. Beachten Sie jedoch, dass kein spezielles Routing - wie Sticky Routing - erforderlich ist, da die iCL Portal Web-Frontends ihren Status im verteilten Cache speichern.

3.2 Einrichten des verteilten Cache​

Der verteilte Cache ist der Kurzzeitspeicher der Web-Frontends und muss sich daher im selben Subnetz befinden und über eine schnelle Ethernet-Verbindung verfügen. Es wird außerdem dringend empfohlen, den redis-Cache auf einem separaten Rechner zu betreiben. Beachten Sie, dass die Hersteller von redis dringend empfehlen, redis unter Linux (wie Ubuntu) zu betreiben. Eine ausführliche Anleitung finden Sie hier . Microsoft unterhält jedoch auch eine Windows-Portierung von Redis, die hier zu finden ist. Da sie einfacher einzurichten ist, wird in dieser Dokumentation gezeigt, wie man die Windows-Version von Redis betreibt.

3.2.1 Einrichten von Redis unter Windows​

Laden Sie zunächst die neueste Version von Redis von https://github.com/MicrosoftArchive/redis/releases herunter (jede Version ab 3.0 wird unterstützt). Zum Zeitpunkt der Erstellung dieses Artikels ist dies die Version 3.0.504. Laden Sie das Paket Redis-x64-x.x.xxx.msi herunter.

Starten Sie anschließend das Installationsprogramm und folgen Sie den Installationsanweisungen. Im Grunde können Sie alle Standardeinstellungen beibehalten. Redis wird in C:\Programmdateien\redis installiert
Als Nächstes konfigurieren Sie ein Passwort in redis.windows.conf, indem Sie die Datei mit Notepad öffnen. Scrollen Sie nach unten zum Abschnitt security und kommentieren Sie die Zeile requirepass aus:
Wählen Sie ein sehr langes Passwort (mindestens 100 Zeichen) und behalten Sie nicht das Standardpasswort (foobared).

Stellen Sie schließlich sicher, dass Sie eine eingehende Firewall-Regel für den Port 6379 konfigurieren. Beachten Sie, dass Sie die Sicherheit von redis zusätzlich verstärken können, indem Sie nur eingehende Verbindungen von den IP-Adressen der iCL Portal Web-Frontends zulassen!

3.2.2 iCL Portal für die Verwendung von Redis konfigurieren​

Um das iCL-Portal anzuweisen, Redis tatsächlich zu verwenden, öffnen Sie die Datei Web.config (beachten Sie, dass Sie dies für jedes Web-Frontend tun müssen)

Fügen Sie den folgenden Schlüssel Abp.Redis.Cache zu dem Knoten <connectionStrings> hinzu

  <connectionStrings>
    <!-- Verbindungsstring für mssql -->
       <add name="Default" connectionString="..." />

       <!-- Verbindungsstring für redis -->
       <add name="Abp.Redis.Cache" connectionString="192.168.178.101:6379,password=foobared,abortConnect=False"/>
  
  </connectionStrings>
Hinweis

Beachten Sie, dass Sie die IP-Adresse der virtuellen Maschine eingeben müssen, auf der Redis läuft - 192.168.178.101 ist nur ein Beispielwert!

Stellen Sie außerdem sicher, dass Sie das Passwort, das Sie im vorherigen Schritt konfiguriert haben, anstelle von foobared verwenden

Fügen Sie den folgenden <sessionState>-Knoten am Anfang des <system.web>-Knotens hinzu

<system.web>
    <!-- für die Verwendung von REDIS in einem Scale-Out-Szenario ist dies ein Befehl -->
    <sessionState mode="Custom" customProvider="iCL.Portal.SessionState.Redis">
      <provider>
        <add name="iCL.Portal.SessionState.Redis" type="Microsoft.Web.Redis.RedisSessionStateProvider"
             connectionString="Abp.Redis.Cache"
             applicationName="iCL.Portal.Session" />
      </providers>
    </sessionState>
...
</system.web>

Und schließlich ändern Sie den Knoten <modules> in <system.webServer> so, dass er die folgenden zwei hervorgehobenen Elemente enthält:

<system.webServer>
    <modules runAllManagedModulesForAllRequests="true">
        
      <!-- .Net462+ erfordert, dass wir zu einem neuen Session-State-Modul wechseln (siehe https://github.com/Azure/aspnet-redis-providers/issues/104) -->
      <remove name="Session" />
      <add name="Session"
           type="Microsoft.AspNet.SessionState.SessionStateModuleAsync, Microsoft.AspNet.SessionState.SessionStateModule, Version=1.1.0.0, Culture=neutral, PublicKeyToken=31bf3856ad364e35"
           preCondition="integratedMode" />
    
      <remove name="ApplicationInsightsWebTracking"/>
      <add name="ApplicationInsightsWebTracking" type="Microsoft.ApplicationInsights.Web.ApplicationInsightsHttpModule, Microsoft.AI.Web" preCondition="managedHandler"/>
    </modules>
    ...

Wenn Sie mit der Konfiguration fertig sind, speichern Sie die Web.config. Dies führt zu einem Neustart von iCL Portal. Um sicherzustellen, dass die Verbindung zu Redis funktioniert, öffnen Sie die letzte error.log-Datei von iCL Portal. (Wenn Sie die NLog.config-Datei nicht geändert haben, sollte sich diese in <webroot>\App_Data\Logs befinden)

Wenn der Start von iCL Portal sehr lange dauert und das error.log mit Meldungen wie StackExchange.Redis.RedisConnectionException: No connection is available to service this operation, dann müssen Sie Ihre Redis-Konfiguration noch einmal durchgehen!

4 Konfigurieren des Microsoft Distributed Transactions Coordinator Service​

Falls Ihr Fehlerprotokoll oder eine Anfrage an iCL Portal diese Ausnahme zeigt:

System.Data.Entity.Core.Entityexception: The Underlying Provider Failed On Open. ---> System.Transactions.Transactionmanagercommunicationexception: Der Netzwerkzugriff für den verteilten Transaktionsmanager (Msdtc) wurde deaktiviert. Bitte aktivieren Sie Dtc für den Netzwerkzugriff in der Sicherheitskonfiguration für Msdtc mit dem Component Services Administrative Tool. ---> System.Runtime.Interopservices.Comexception: Der Transaktionsmanager hat seine Unterstützung für Remote-/Netzwerktransaktionen deaktiviert. (Ausnahme von Hresult: 0x8004d024)

Um dieses Problem zu beheben, müssen Sie den DTC-Zugriff auf allen Rechnern konfigurieren, die an der Koordinierung verteilter Transaktionen teilnehmen. Für iCL Portal ist dies

  • Jeder Rechner, auf dem die Webanwendung läuft
  • Der Datenbankserver

4.1.1 Lösung Teil 1​

  • Aktivieren Sie den Netzwerkzugang.
  • Öffnen Sie den Server, auf dem das Web-Frontend läuft (iCL Portal Website)
  • Öffnen Sie den Server Manager => Werkzeuge => Komponentendienste
  • Alternativ können Sie auch die Windows-Taste drücken und nach "dcomcnfg" suchen
  • Erweitern Sie Komponentendienste => Computer => Arbeitsplatz => Verteilter Transaktionskoordinator und öffnen Sie dann dessen Eigenschaften über das Kontextmenü
  • Aktivieren Sie auf der Registerkarte Sicherheit den Netzwerk-DTC-Zugriff

4.1.2 Lösung Teil 2​

Aktivieren von Firewall-Ausnahmen für MS DTC

Wenn die Windows-Firewall verwendet wird, müssen Sie auf jedem Computer, der an der Koordinierung verteilter Transaktionen beteiligt ist, eine Firewall-Ausnahme für den Microsoft Distributed Transaction Coordinator (MS DTC) hinzufügen. Um diese Änderung zu konfigurieren, verwenden Sie die Windows-Firewall in der Systemsteuerung, um eine Firewall-Ausnahme auf jedem Computer im Netzwerk zu aktivieren, auf dem DTCs ausgeführt werden, die eine Netzwerkverbindung erfordern.

Die Mitgliedschaft in der Gruppe der Administratoren oder einer gleichwertigen Gruppe ist die Mindestvoraussetzung für die Durchführung dieses Verfahrens. Weitere Informationen zur Verwendung der entsprechenden Konten und Gruppenmitgliedschaften finden Sie unter Lokale und Domänen-Standardgruppen.

    1. öffnen Sie die Windows-Firewall. Um die Windows-Firewall zu öffnen, klicken Sie im Menü Start auf Systemsteuerung. Führen Sie in der Systemsteuerung einen der folgenden Schritte aus:

    • a. Unter Sicherheit,

      Klicken Sie auf "Ein Programm durch die Windows-Firewall zulassen".

    • b. Wenn die Systemsteuerung in der klassischen Ansicht ist, klicken Sie auf Windows Firewall.

  • 2 Aktivieren Sie auf der Registerkarte Ausnahmen das Kontrollkästchen Distributed Transaction Coordinator.

    1. klicken Sie auf OK.