API-Gateway einrichten

Im folgenden wird beschrieben wie das API-Gateway Schleupen.CS.PI.SB.GTW_Gateway eingerichtet wird. Die folgenden Schritte zur Einrichtung sind sorgfältig durchzuführen.

Hosting

Das API-Gateway wird als Executable oder Docker-Container ausgeliefert. Wird dieses als Executable genutzt, so bietet es sich an, dieses als Windows-Dienst zu betreiben.

Per Powershell kann dieser beispielsweise wie folgt eingerichtet werden:

New-Service -Name "APIGatewayService" `
            -DisplayName "Schleupen API Gateway" `
            -BinaryPathName "C:\Pfad\zu\Schleupen.CS.PI.SB.Gateway.Services.exe" `
            -StartupType Automatic
Start-Service "APIGatewayService"

Serviceimplementierungsgruppe (SIG) zuordnen

Für das Element-Mapping wird die die folgende Serviceimplementierungsgruppe benötigt. Diese ist per Standard eingerichtet.

Systemintegration (Schleupen.CS.gpi.sig.Systemkatalog_1.0)

Diese kann bzw. ist in der Regel auf Systemebene registriert.

Einrichtung des Systemstrukturelement-Mappings

Mithilfe des Mappings von Systemstrukturelementen wird der Zugriff auf ein Schleupen.CS-System vereinfacht. Dabei kann pro Systemstruktur-Element anstelle eines SessionTokens einfacher ein konfigurierter, sprechender Name (z.B. Mandantennamen) verwendet werden.

Das folgende Skript zeigt, wie dieses Mapping für einen Knoten konfiguriert wird.

$elementName = "MANDANTENBEZEICHNUNG"
$identification = "Schleupen.CS.PI.SB.Gateway.Mapping"
$externalIdentifier = "MANDANTENBEZEICHNUNG"

$ErrorActionPreference = "Stop"
$elementId = (Select-SystemStructureElement -Name $elementName).Id
$systemUsageId = (Select-SystemUsage -Name "Produktiv").Id

$externalMappings = Select-ExternalElementMappings
$newMapping = New-ExternalElementMapping -Identification $identification -ElementId $elementId -SystemUsageId $systemUsageId -ExternalIdentifier $externalIdentifier
Add-ExternalElementMapping -externalMapping $externalMappings -Mapping $newMapping
Save-ExternalElementMappings -XmlDoc $externalMappings

Aus Gründen der Übersichtlichkeit wird empfohlen, bei $elementName und $externalIdentifier denselben Wert (Mandantenbezeichnung, z.B. LieferantMoersHuelsdonk1) einzutragen. $identification darf nicht geändert werden.

Anbindung des Schleupen.CS-Systems

Mithilfe der Konfiguration von YARP wird der Host konfiguriert, gegen den das Gateway das Scheupen.CS-System initial kontaktiert. Hier ermittelt sich das Gateway alle CS-Hosts, die dann für das Load Balancing verwendet werden.

{
	...
	"ReverseProxy": {
		"Routes": {
			"route1": {
				"ClusterId": "cluster1",
				"Match": {
					"Path": "/schleupen/{**catch-all}"
				}
			}
		},
		"Clusters": {
			"cluster1": {				
				"HttpRequest": {
					"Version": "1.1",
					"VersionPolicy": "RequestVersionExact"
				},
				"Destinations": {
					"destination1": {
						"Address": "https://<CS-Hook-Host>:443" // destination entry point of Schleupen.CS, then one of the clustered hosts will be used
					}
				}
			}
		}
	}
}

YARP bietet Strategien für das Load-Balancing, diese können statisch über die appsettings.json definiert werden. Gewünscht ist allerdings ein dynamischers Verhalten und kein manuelles Verfahren, daher werden die CS-Hosts ausgelesen. Diese CS-Hosts werden intern verwendet, wobei derzeit die Strategie 'Random' verwendet wird.

Authentifizierung und Autorisierung

Da das Gateway auf ASP.NET Core MVC und YARP basiert, siehe hierzu unbedingt https://learn.microsoft.com/en-us/aspnet/core/fundamentals/servers/yarp/authn-authz!

Über die Konfigurationsparameter 'CSOptions.AuthenticationOptions.AuthenticationMode' und 'CSOptions.AuthenticationOptions.DestinationAuthenticationMode' kann festgelegt werden, welche Absicherung für die Strecke von Client zu API-Gateway und/oder für die Strecke von API-Gateway zu Schleupen.CS-System verwendet wird.

Folgende Modi werden angeboten:

ActiveDirectory
Anmerkung: Windows Authentifizierung wird nicht durchgeroutet, d.h. der Aufrufer wird am API-Gateway authentifiziert (per Negotiation) und der Benutzer, der das Gateway ausführt, wird an Schleupen.CS authentifiziert.
Details siehe https://github.com/dotnet/yarp/issues/166
[in Planung] Open ID Connect
Hiebei wird BearerToken als JWT wird durchgereicht und Eingangsseitig das Token validiert. Ein separates Token wird für den Zugriff auf Schleupen.CS verwendet.
Passthru
In diesem Modus werden die Authentifizierungs-/Autorisierungsinformationen weitergeleitet. Dies ist in der Regel ein BearerToken als JWT.
Wichtig: Dies ist dafür gedacht, um in einigen Szenarien das BearerToken zum Schleupen.CS-System durchzureichen.

In appsettings.json kann dies wie folgt konfiguriert werden:

{
	...
	"CSOptions": {
		...
		"AuthenticationOptions": {
			"AuthenticationMode": "Passthru", // ActiveDirectory
			"DestinationAuthenticationMode": "ActiveDirectory" // Passthru
		}
	},
	...
}

Transport Layer Security

Um HTTPS zur Transportsicherheit zu aktivieren, können die Standard-Konfigurationen verwendet werden.

{
	"Kestrel": {
		"Endpoints": {
			"HttpsFromPfx": {
				"Url": "https://0.0.0.0:55044",
				"Certificate": {
					"Path": "D:\\temp\\https_test\\localhost.pfx",
					"Password": "Passw0rd!"
				}
			}
			"HttpsFromStore": {
				"Url": "https://0.0.0.0:443",
				"Certificate": {
					"Subject": "CN=localhost",
					"Store": "My",
					"Location": "CurrentUser",
					"AllowInvalid": false
				}
			}
		}
	},
	...
}

Logging

Es kann ein auf NLog basierendes Logging oder auch die Diagnoseprotokollierung von Schleupen.CS auf CS-Hosts verwendet werden. Dies über den Konfigurationsschalter 'CSOptions.LoggingMode' festgelegt werden. Eine Default-Konfiguration für NLog wird mitgeliefert.

{
	...
	"CSOptions": {
		"LoggingMode": "NLog", // CSLogging
		...
	},
	"Logging": {
		"LogLevel": {
			"Default": "Information",
			"Microsoft": "Warning",
			"Yarp": "Information",
			"Microsoft.Hosting.Lifetime": "Information"
		}
	},
	...
}

Routen- und Host-Filterung

Über ASP.NET Core können die Host angegeben werden, die das Gateway aufrufen dürfen. Siehe hierzu https://learn.microsoft.com/de-de/aspnet/core/fundamentals/servers/kestrel/host-filtering. ''ReverseProxy.Routes.<myroute>.Match.Path' gibt an, unter welchem URL-Pfad YARP Anfragen entgegennimmt.

{
	...
	"AllowedHosts": "auth.meinefirma.de",
	"ReverseProxy": {
		"Routes": {
			"route1": {
				"ClusterId": "cluster1",
				"Match": {
					"Path": "/schleupen/{**catch-all}"
				}
			}
		},
		...
	}
}

Beispiel

Die Einstellungen können und sollten teilweise per Umgebungsvariablen oder Programmargumenten gelöst werden. Siehe hierzu: https://learn.microsoft.com/en-us/aspnet/core/fundamentals/configuration

{
	"Kestrel": {
		"Endpoints": {
			"HttpsFromPfx": {
				"Url": "https://0.0.0.0:55044",
				"Certificate": {
					"Path": "D:\\temp\\https_test\\localhost.pfx",
					"Password": "Passw0rd!"
				}
			}
		}
	},
	"CSOptions": {
		"LoggingMode": "NLog", // CSLogging
		"AuthenticationOptions": {
			"AuthenticationMode": "Passthru", // ActiveDirectory
			"DestinationAuthenticationMode": "ActiveDirectory" // Passthru
		}
	},
	"Logging": {
		"LogLevel": {
			"Default": "Information",
			"Microsoft": "Warning",
			"Yarp": "Information",
			"Microsoft.Hosting.Lifetime": "Information"
		}
	},
	"AllowedHosts": "auth.meinefirma.de",
	"ReverseProxy": {
		"Routes": {
			"route1": {
				"ClusterId": "cluster1",
				"Match": {
					"Path": "/schleupen/{**catch-all}"
				}
			}
		},
		"Clusters": {
			"cluster1": {
				"LoadBalancingPolicy": "Random",
				//"HttpClient": {
				//	"WebProxy": { // Optional proxy configuration for outgoing requests
				//		"Address": "http://ProxyInFrontOfDestination",
				//		"BypassOnLocal": false,
				//		"UseDefaultCredentials": true
				//	}
				//},
				"HttpRequest": {
					"Version": "1.1",
					"VersionPolicy": "RequestVersionExact"
				},
				"Destinations": {
					"destination1": {
						"Address": "https://<CS-Hook-Host>:443" // destination entry point of Schleupen.CS, then one of the clustered host will be used
					}
				}
			}
		}
	}
}