Schnittstellen: Security Levels und Authentifizierung

Hinweis: Dieser Artikel ist "work in progress", die beschriebenen Sicherheitsfeatures für das DataGatewayServer sind auf unserer Entwicklungs-roadmap für Ende Q1/2024 und demnach noch nicht umgesetzt.

Grundsätzlich kann das HVS32 ohne Bedenken in Cloud-Umgebungen betrieben werden, sofern die Verbindung vom Vorsystem (ERP bzw. WMS, nachfolgend der Einfachheit halber nur ERP genannt) zum HVS32 in einem gemeinsamen, gesicherten, internen Netzwerk ist.
Wenn das Versandsystem HVS32 allerdings öffentlich erreichbar sein muss - also sich das Vorsystem (ERP/WMS) und das Versandsystem HVS32 nicht im gleichen Netzwerk (LAN, vLAN, vNET, private cloud) befinden - muss die Kommunikations-Verbindung der beiden Systeme abgesichert werden.
Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.

Security Levels (Infrastruktur)

Zur Absicherung der Netzwerk-Brücke gibt es keine zu 100% perfekte oder sichere Lösung. Meist muss man sich für einen Kompromiss je nach Fall entscheiden. In der Infrastruktur können jedoch bereits diverse Security Levels implementiert werden, um die Sicherheit maßgeblich zu erhöhen.

LAN / vLAN / vNET / private cloud / VPN

Befinden sich die beiden Server in einem gemeinsamen Netzwerk, bzw. liegt eine gesicherte Netzwerk-Brücke via VPN zu Grunde, bietet dies grundlegend die beste Basis für eine sichere Datenkommunikation zwischen dem Vorsystem und dem Versandsystem HVS32.

S2S (Server-to-Server)

Bei einer ungesicherten Netzwerk-Brücke ist unbedingt darauf zu achten, dass die Kommunikation ausschließlich verschlüsselt und authentifiziert stattfindet.

Dead-End-Server

Da alle Verbindungen zum DGS (DataGatewayServer - Kommunikations-/Schnittstellen-Software) eingehend sind, kann als zusätzliche Sicherheitsmaßnahme der DGS auf einem separaten Server installiert werden, bei welchem alle ausgehenden Verbindungen via Firewall blockiert werden.

Authentifizierung

Authentifizierungs-Mechanismen können nur als "sicher" bezeichnet werden, wenn diese in Kombination mit anderen Sicherheits-Mechanismen wie HTTPS/SSL genutzt werden. Die Verschlüsselung ist mittels HTTPS unter Verwendung von TLSv1.2 oder TLSv1.3 (sofern vom Client unterstützt) möglich.

Die folgenden Authentifizierungs-Optionen beziehen sich ausschließlich auf die RESTv2 Schnittstelle

Basic Authentication

Die Basisauthentifizierung ist ein einfaches Authentifizierungsschema, welches in das HTTP-Protokoll integriert ist. Der Client sendet in jeder HTTP-Anfrage den Authentifizierungsheader, welcher Benutzername und Passwort enthält.

Der Authentifizierungsheader lautet Authorization und beinhaltet den Benutzer und das Passwort Base64 codiert im Format - Basic <Benutzer>:<Passwort>.

Die Benutzerverwaltung erfolgt im DataGatewayServer. Dort können neue Benutzer angelegt und gelöscht werden.

Hinweis: Mit zunehmender Anzahl von gültigen Benutzern steigt auch die Wahrscheinlichkeit, dass sich durch eine "Brute-Force-Attacke" unerlaubter Zugriff gewährt wird.

Beispielheader für eine Anfrage

In diesem Beispiel wird der Benutzer heidler mit dem Passwort Wolfschlugen verwendet.

POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache

Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized

Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit der Fehlermeldung "Unauthorized acces" im Body quittiert.

HTTP/1.1 401 Unauthorized
Www-authenticate: Basic realm="Restricted Area"
Date: Mon, 26 Feb 2024 09:00:44 GMT
Content-type: application/json
Content-length: 19
 
Unauthorized access

Digest Access Authentication

HTTP Digest Access Authentication ist ein Authentifizierungsmechanismus, der in das HTTP-Protokoll integriert ist und dazu dient, die Sicherheit von Webanwendungen zu erhöhen. Im Gegensatz zur einfachen Basisauthentifizierung überträgt Digest Access Authentication keine Benutzernamen und Passwörter im Klartext, sondern verwendet kryptografisch sichere Methoden.

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server, der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Der Client kombiniert diese Nonce mit Benutzername, Passwort, Anfrage-Methode und URI und erstellt einen "Digest" (Prüfzusammenstellung). Dieser Digest wird dann an den Server gesendet.
Der Server kann den Digest überprüfen, indem er denselben Algorithmus auf der Serverseite anwendet und die berechneten Werte vergleicht. Da der Digest mit Hilfe der Nonce und kryptografisch sicheren Techniken erstellt wird, schützt die Digest-Authentifizierung effektiv vor Angriffen wie Passwortdiebstahl und Mann-in-the-Middle-Angriffen (MitM).

Die Benutzerverwaltung erfolgt im DataGatewayServer. Dort können neue Benutzer angelegt und gelöscht werden.

Hinweis: Mit zunehmender Anzahl von gültigen Benutzern steigt auch die Wahrscheinlichkeit, dass sich durch eine "Brute-Force-Attacke" unerlaubter Zugriff gewährt wird.

Anfrage einer nonce für die Erstellung des "Digest"

In der initialen Anfrage wird im Header keine Authentifizierung geliefert, da vom Server zuerst die nonce abgefragt werden muss. In der Rückmeldung vom DataGatewayServer befindet sich dann die nonce zusammen mit weiteren Informationen im HTTP-Header Www-authenticate.

Diese Anfrage wird mit dem HTTP-Code 401 Unauthorized und der Fehlermeldung "Authentication required!" im Body quittiert.

HTTP/1.1 401 Unauthorized
Www-authenticate: Digest realm="Restricted Area",qop="auth",nonce="079ae550-11c1-40bf-9ee9-7cce5f1dd70e",opaque="opaque"
Date: Mon, 26 Feb 2024 10:21:41 GMT
Content-type: application/json
Content-length: 24
 
Authentication required!

Anfrage nach erhaltener nonce

Nachdem die nonce aus der initialen Anfrage extrahiert und der "Digest" erstellt worden ist, erfolgt die Anfrage für die Verarbeitung mit dem HTTP-Header Authorization.

POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Cache-Control: no-cache
Authorization: Digest username="<BENUTZER>", realm="Restricted Area", nonce="079ae550-11c1-40bf-9ee9-7cce5f1dd70e", uri="<ENDPOINT>", algorithm="MD5", qop=auth, nc=00000001, cnonce="PoYGQC6K", response="ce3fb921e353290142e34ac886694a4c", opaque="opaque"

Rückmeldung bei fehlgeschlagener Authentifizierung

Bei einer ungültigen Authentifizierung (Verwendung vom HTTP-Header Authorization) wird der HTTP-Code 401 Unauthorized mit der Fehlermeldung "client credentials invalid!" im Body zurück gemeldet.

HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27
 
client credentials invalid!

API Keys

Die API-Key-Authentifizierung ist eine einfache Methode zur Sicherung von API-Zugriffen. Bei dieser Authentifizierungsmethode erhält der Benutzer / Client einmalig einen eindeutigen API-Schlüssel (API-Key). Dieser Schlüssel muss dann bei jeder API-Anfrage im Header mit gesendet werden.
Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.

Der API-Key muss sicher aufbewahrt werden, um unbefugten Zugriff zu verhindern. Außerdem ist es wichtig, diesen regelmäßig zu zu aktualisieren, um die Sicherheit zu gewährleisten.

Der API-Key wird im DataGatewayServer verwaltet. Dort kann ein neuer Key generiert werden. Es können mehrere API-Keys generiert werden.

Hinweis: Mit zunehmender Anzahl von gültigen API-Keys steigt auch die Wahrscheinlichkeit, dass sich durch eine "Brute-Force-Attacke" unerlaubter Zugriff gewährt wird.

Beispielheader für eine Anfrage

In diesem Beispiel wird der API-Key apikey_heidler verwendet.

Hinweis: Aus demonstrationszwecken wird in dem Beispiel ein einfacher API-Key verwendet. Der DataGatewayServer erzeugt einen entsprechend langen und komplexen Key.

POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache

Rückmeldung bei fehlgeschlagener Authentifizierung

Bei einem falschen API-Key wird der HTTP-Code 401 Unauthorized mit der Fehlermeldung "api key invalid!" im Body zurück gemeldet.

HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16
 
api key invalid!

OAuth 2.0

Client Credentials

OAuth 2.0 Client Credentials ist eine Authentifizierungs-Methode im OAuth 2.0-Protokoll, die es einer Anwendung ermöglicht, sich beim Authorization Server (Authentifizierungsserver) zu authentifizieren. Dies ist besonders nützlich für den Zugriff von Anwendungen auf APIs ohne Benutzerbeteiligung und eignet sich gut für server-seitige Kommunikation zwischen Diensten.

Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.
Inital wird dann von dem ERP eine HTTP-POST-Anfrage an den Authorization Server gesendet, welche die Client-Anmeldeinformationen (Client-ID und Client-Secret) beinhaltet. Im Response wird ein Access-Token und ein Refresh-Token zurück gemeldet.
Das ERP sendet nun für die Authentifizierung bei jeder Anfrage das Access-Token im Authorization Header der HTTP-Anfragen mit. Wenn das Access-Token abgelaufen ist, kann mit dem Refresh-Token ein neuer Access-Token angefragt werden. Im Falle einer mehrfachen Nutzung eines Refresh-Tokens werden automatisch alle Refresh-Tokens und Access-Tokens gesperrt.
Das Client-Secret muss sicher aufbewahrt werden, um unbefugten Zugriff zu verhindern. Außerdem ist es wichtig, das Client Secret regelmäßig zu zu aktualisieren, um die Sicherheit weiter zu erhöhen.

Die Client-ID und Client-Secret werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.

Hinweis: Mit zunehmender Anzahl von gültigen Client-IDs steigt auch die Wahrscheinlichkeit, dass sich durch eine "Brute-Force-Attacke" unerlaubter Zugriff gewährt wird.

Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)

Bei der Token-Anfrage muss die Client-ID und das Client-Secret im HTTP-Header Authorization Base64 codiert im Format - "Basic ClientID:ClientSecret" übermittelt werden. Zusätzlich ist für diese Funktion der grant_type mit dem Wert client_credentials notwendig.

POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID:ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache

Rückmeldung der Token-Anfrage

In der Rückmeldung der Token-Anfrage wird im Body der Accesstoken (access_token), der Refreshtoken (refresh_token), der Tokentyp (token_type) und Gültigkeit vom Accesstoken in Sekunden (expires_in) zurück gemeldet.

Der Accesstoken kann nun für die Authentifizierung in den restlichen Anfragen genutzt werden.

Der Accesstoken hat aus Sicherheitsgründen eine begrenzte Gültigkeit. Nach Ablauf ist der Accesstoken nicht mehr verwendbar und man erhält einen HTTP-Code 401 Unauthorized. In diesem Fall muss über die Refresh-Anfrage und einem gültigen Refreshtoken ein neuer Accesstoken generiert werden (empfohlen) oder über die Tokenanfrage und der Client-ID + Client-Secret ein neues Accesstoken angefragt werden (nicht empfohlen).

Hinweis: Die regelmäßige Generierung von Accesstoken über die Token-Anfrage wird nicht empfohlen, da hier die Client-ID + Client-Secret übertragen wird. Dadurch ist die Anfälligkeit gegen MitM-Angriffen höher. Das Client-Secret sollte so selten wie möglich eingesetzt werden.

HTTP/1.1 200 OK
Date: Mon, 26 Feb 2024 12:06:32 GMT
Content-type: application/json
Content-length: 711
Cache-control: no-cache
 
{
"access_token": "eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0",
"refresh_token": "eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA",
"token_type": "Bearer",
"expires_in": 600
}

Beispielheader für die Nutzung eines Accesstokens

Der aus der Token-Anfrage erhaltene Accesstoken kann nun im HTTP-Header Authorization an den DataGatewayServer übermittelt werden, um sich zu authentifizieren.

POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache

Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)

Falls ein Accesstoken abgelaufen ist und dieser erneut werden muss, kann über die Refresh-Anfrage und einem gültigen Refreshtoken ein neuer Accesstoken + Refreshtoken generiert werden. In dieser Anfrage muss der HTTP-Header refresh_token mit dem Refreshtoken und der Header grant_type mit dem Wert refresh_token übermittelt werden.

Um die Sicherheit vor MitM-Angriffen zu erhöhen, empfiehlt es sich den Accesstoken regelmäßig und im kurzen intervall zu aktualisieren.

Hinweis: Ein Refreshtoken kann nur einmalig für die Refreshanfrage genutzt werden. Anschließend verliert der Token seine Gültigkeit. Falls ein ungültiger Refreshtoken für die Authentifizierung beim DataGatewayServer genutzt wird, werden aus Sicherheitsgründen alle gültigen Access- und Refreshtoken deaktiviert. Die Authentifizierung muss in diesem Fall wieder über die Token-Anfrage stattfinden.

POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token

Rückmeldung der Refresh-Anfrage

In der Rückmeldung der Refresh-Anfrage wird im Body der Accesstoken (access_token), der Refreshtoken (refresh_token), der Tokentyp (token_type) und Gültigkeit vom Accesstoken (expires_in) in Sekunden zurück gemeldet.

Der Accesstoken kann nun für die Authentifizierung in den restlichen Anfragen genutzt werden.

HTTP/1.1 200 OK
Date: Mon, 26 Feb 2024 12:06:43 GMT
Content-type: application/json
Content-length: 711
 
{
"access_token": "eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk4MDMsImp0aSI6ImJmYjgyZWE0LTU2NmEtNDc3ZS04NDRjLWRkM2VhYWZmZjQ1ZSIsInV1SUQiOiI0ZmY5ZThhNC01YTY2LTQ0ZDQtYjY4Zi1jNjlmMzFiOTNiYjciLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkyMDN9.vMoedyTSnfWXYXbGPZTX-nfhfNUAvp2upQJ3pTU-u_k",
"refresh_token": "eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMyMDMsImp0aSI6IjI5MTc0NzBkLTNjYTUtNGZiMC1hZDliLThjNjkxYWVjNDYzOSIsInV1SUQiOiI0ZmY5ZThhNC01YTY2LTQ0ZDQtYjY4Zi1jNjlmMzFiOTNiYjciLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkyMDN9.DonI4KsNiTuG6pb705U3QIT7tNnU0pmDS7Tp6UZWHVk",
"token_type": "Bearer",
"expires_in": 600
}

Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized

Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.

HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>
 
<FEHLERMELDUNG>

Authorization Code

Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem IRIS Cloudsystem möglich.