Das API-Gateway ist die mittlere Schicht zwischen externen Systemen und der Evolve Anwendung. Es verwaltet die Sicherheit verfügbar gemachter APIs, auf die von Drittanbietersystemen zugegriffen werden soll. Beispielsweise kann ein Drittanbietersystem einen Formularprozess starten, indem es die Prozesserweiterungs-API aufruft. Damit die Durchführung dieses Aufrufs erfolgreich ist, muss das Drittanbietersystem die Sicherheitsanforderungen des API-Gateways erfüllen.
Details zur Sicherheit des API-Gateways
Das API-Gateway bietet Optionen für die Registrierung eines Drittanbieter-Clients in der Anwendung. Auf der Administrationssite kann ein neuer Client registriert werden, indem Sie zu „Einstellungen“ → „Authentifizierung“ → „Drittanbieter-Clients“ → „Client registrieren“ navigieren. Das API-Gateway unterstützt drei Sicherheitsoptionen: „Geheimer Clientschlüssel“, „Sicherheitstoken“ und „Zertifikat“.
Winshuttle empfiehlt die Sicherheitsoption Sicherheitstoken als bevorzugte Option für die Verwendung durch Drittanbietersysteme.
Geheimer Clientschlüssel
Dies ist die Sicherheitsoption des HTTP-Headers. Zur Registrierung eines neuen Clients muss der Benutzer auf Client registrieren klicken, einen Clientnamen angeben und aus der Dropdownliste „Sicherheitstyp“ die Option Geheimer Clientschlüssel auswählen. Bei der Registrierung eines neuen Clients generiert die Anwendung eine Client-ID und einen Geheimcode. Wählen Sie zum Kopieren des Geheimcodes einen beliebigen Client aus, und klicken Sie dann auf „Ansicht“ → „Geheimcode zeigen“. Drittanbieteranwendungen müssen die registrierte Client-ID und den Geheimcode im HTTP-Anforderungsheader wie folgt senden:
-
Name des Anforderungsheaders: „c1“ sollte eine gültige registrierte Client-ID aufweisen.
-
Name des Anforderungsheaders: „ck“ sollte einen Geheimcode aufweisen.
Sicherheitstoken
Dies ist die Sicherheitsoption des JWT-Tokens. Zur Registrierung eines neuen Clients muss der Benutzer auf Client registrieren klicken, einen Clientnamen angeben und aus der Dropdownliste „Sicherheitstyp“ die Option Sicherheitstoken auswählen. Bei der Registrierung eines neuen Clients generiert die Anwendung eine Client-ID und einen Geheimcode. Wählen Sie zum Kopieren des Geheimcodes einen Client aus, und klicken Sie dann auf „Ansicht“ → „Geheimcode zeigen“. Der Client eines Drittanbieters sollte ein JWT-Token erstellen und es auch mit dem Geheimcode signieren. Dieses signierte JWT-Token muss in einer API-Anforderung gesendet werden. Die API muss die folgenden Anforderungsheader aufweisen:
-
Name des Anforderungsheaders: „c1“ sollte eine gültige registrierte Client-ID aufweisen.
-
Name des Anforderungsheaders: „ck“ sollte ein JWT-Token aufweisen.
Das JWT-Token sollte folgende Details enthalten:
-
Das Token muss eine Anspruchs-ClientID aufweisen und sollte eine Client-ID registriert haben (die Client-ID, die bei der Registrierung des Clients angezeigt wird). Es sollte mit dem Wert im Anforderungsheader „c1“ identisch sein.
-
Das Token muss einen Anspruchs-ClientName aufweisen und sollte einen Clientnamen registriert haben (den Clientnamen, der bei der Registrierung des Clients angezeigt wird).
-
Die standardmäßige Ablaufzeit des Tokens sollte nicht mehr als 5 Minuten ab der Ausgabe des Tokens betragen. Wenn der Benutzer diese Zeit verlängern möchte, kann ein Schlüssel zu „System“ → „Infrastruktur“ → „Erweiterte Einstellungen“ mit Kategorie: System, Konfigurationsschlüssel:ExtAPITokenExpiryMinutes hinzugefügt werden. Der Wert sollte die Zeit in Minuten angeben.
Zertifikat
Dies ist die zertifikatbasierte Sicherheit, bei der sowohl die Drittanbieteranwendung als auch der Evolve Server ein Zertifikat gemeinsam nutzen. Dieses Zertifikat wird zur Authentifizierung des Aufrufs verwendet. Dies wird auch als gegenseitige Zertifikatsauthentifizierung bezeichnet und wird nur unterstützt, wenn Evolve in HTTPS eingerichtet ist. Zur Registrierung eines neuen Clients muss der Benutzer auf Client registrieren klicken, einen Clientnamen angeben und aus der Dropdownliste „Sicherheitstyp“ die Option Zertifikat auswählen. Bei der Registrierung eines neuen Clients generiert die Anwendung eine Client-ID. Die generierte Client-ID wird zusammen mit dem Client-Zertifikat verwendet, um den API-Aufruf zu tätigen. Die Evolve Anwendung sollte so konfiguriert werden, dass die zertifikatbasierte Authentifizierung gemäß den folgenden Details aktiviert wird:
-
Ein Stammzertifizierungsstellenzertifikat und Client-Zertifikate sind erforderlich. Die Client-Zertifikate sollten vom Stammzertifizierungsstellenzertifikat ausgestellt werden.
-
Installieren Sie das Stammzertifikat am Speicherort der vertrauenswürdigen Stammzertifizierungsstellen auf dem lokalen Rechner des Evolve Servers.
-
Installieren Sie das Clientzertifikat auf dem Client-Computer, und senden Sie dieses Clientzertifikat, während Sie die Prozesserweiterungs-API aufrufen.
Der Benutzer kann die Option Namen des Client-Computers validieren aktivieren/deaktivieren. Ist sie aktiviert, müsste der Name des Clientzertifikats mit dem des Client-Computers identisch sein.
So beheben Sie einen Fehler vom Typ „RequestEntityTooLarge“ mit externer API beim Starten mit Zertifikatauthentifizierung:
-
Wählen Sie unter „Standardwebsite“ die Website aus.
-
Wählen Sie den Konfigurationseditor aus.
-
Wählen Sie in der Dropdownliste „Abschnitt“ „system.webServer/serverRuntime“ aus.
-
Geben Sie einen höheren Wert für „uploadReadAheadSize“ ein, z. B. 1048576 Byte. Der Standardwert sind 49152 Byte.