Interfaces: Security Levels and Authentication
Note: This article is a work in progress. The security features described for the DataGatewayServer are on our development roadmap for the end of Q1/2024 and therefore not yet implemented.
The HVS32 can be operated in cloud environments without concerns, assuming that the connection from the host system (ERP or WMS, hereinafter referred to as ERP for simplicity) to HVS32 is within a shared, secure, internal network.
However, if the shipping software HVS32 needs to be publicly accessible — meaning that the host system (ERP/WMS) and the shipping software HVS32 are not located in the same network (LAN, vLAN, vNET, private cloud) — the communication between the two systems must be secured.
This implies that both the connection must be encrypted, and each incoming connection must be authenticated and authorized.
Security Levels (Infrastructure)
To secure the network bridge, there is no 100% perfect or foolproof solution. Typically, one has to opt for a compromise depending on the specific case. However, in the infrastructure, various security levels can already be implemented to significantly enhance security.
LAN / vLAN / vNET / private cloud / VPN
If the two servers are within the same network or there is a secured network bridge via VPN in place, this provides the best foundation for secure data communication between the host system and the shipping software HVS32.
S2S (Server-to-Server)
In the case of an unsecured network bridge, it is crucial to ensure that communication takes place exclusively through encryption and authentication.
Dead-End-Server
Since all connections to the DGS (DataGatewayServer - Communication-/Interface-Software) are incoming, as an additional security measure, the DGS can be installed on a separate server where all outgoing connections are blocked via firewall.
Authentication
Authentication mechanisms can only be considered "secure" when used in combination with other security mechanisms such as HTTPS/SSL. Encryption is achieved through HTTPS using TLSv1.2 or TLSv1.3 (if supported by the client).
The following authentication options are specific to the RESTv2 interface.
Basic Authentication
The Basic authentication is a simple authentication scheme integrated into the HTTP protocol. The client sends the authentication header in every HTTP request, which contains the username and password.
The authentication header is named Authorization and includes the username and password base64 encoded in the format - Basic <Username>:<Password>.
User management is handled within the DataGatewayServer. New users can be created and deleted there.
Note: As the number of valid users increases, so does the likelihood of unauthorized access being granted through a "brute-force attack."
In this example user heidler and password Wolfschlugen is used.
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
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 accessDigest Access Authentication
The Digest Access Authentication is an authentication mechanism integrated into the HTTP protocol designed to enhance the security of web applications. Unlike basic authentication, which transmits usernames and passwords in plaintext, Digest Access Authentication uses cryptographically secure methods.
In Digest authentication, the client sends a request to the server (without authentication in the header), which then returns a "nonce" (a unique random number). Alternatively, this nonce can be obtained via the endpoint v2/hsc/auth/digest.
The client combines this nonce with the username, password, request method, and URI to create a "digest" (checksum). This digest is then sent to the server. The server can verify the digest by applying the same algorithm on the server side and comparing the calculated values. Because the digest is created using the nonce and cryptographically secure techniques, Digest Authentication effectively protects against attacks such as password theft and man-in-the-middle (MitM) attacks.
Currently, only the MD5 algorithm is supported for digest creation. Additional algorithm procedures can be implemented upon consultation.
User management is handled within the DataGatewayServer. New users can be created and deleted there.
Note: As the number of valid users increases, so does the likelihood of unauthorized access being granted through a "brute-force attack."
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, welche für die Erstellung eines Digest benötigt werden, 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!
Nachdem der Client die nonce, realm, qop und die opaque aus der initialen Anfrage extrahiert und damit den Digest generiert hat, kann dieser für die Authentifizierung über den HTTP-Header Authorization übermittelt werden.
Das Format entspricht dabei:
Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"
Der Parameter nc = "Nonce count" und cnonce = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.
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"
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
API key authentication is a simple method for securing API access. With this authentication method, the user/client is provided with a unique API key. This key must be included in the header of each API request.
The server verifies the received API key to ensure that the request is coming from an authenticated user or application.
It's crucial to securely store the API key to prevent unauthorized access. Additionally, regular updates to the API key are important to maintain security.
The API key is managed within the DataGatewayServer. New keys can be generated or existing ones can be deleted. Multiple valid API keys can exist.
Note: As the number of valid API keys increases, so does the likelihood of unauthorized access being granted through a "brute-force attack."
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
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 is an authentication method within the OAuth 2.0 protocol that allows an application to authenticate with the authorization Server without user involvement. This is particularly useful for applications accessing APIs without user participation and is well-suited for server-to-server communication between services.
The ERP system is registered on the authorization server and receives a unique Client ID and Client Secret. Initially, the ERP sends an HTTP POST request to the Authorization Server, including the client credentials (Client ID and Client Secret). The response includes an Access Token and a Refresh Token. For authentication with each subsequent request, the ERP includes the Access Token in the Authorization Header of the HTTP requests. If the Access Token expires, a new Access Token can be requested using the Refresh Token. In case of multiple uses of a Refresh Token, all Refresh Tokens and Access Tokens are automatically invalidated. The Client Secret must be securely stored to prevent unauthorized access. Additionally, it's important to regularly update the Client Secret to enhance security further.
The Client ID and Client Secret are managed within the DataGatewayServer. New credentials can be created or existing ones can be deleted there.
Note: As the number of valid Client IDs increases, so does the likelihood of unauthorized access being granted through a "brute-force attack."
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
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 Token-Anfrage 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
}
Der aus der Token-Anfrage erhaltene Accesstoken kann nun im HTTP-Header Authorization an den DataGatewayServer übermittelt werden, um sich zu authentifizieren. Dieser muss im Format - Bearer <Accesstoken> übertragen werden.
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
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
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
}
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
This authentication method is exclusively available through the authentication system IRIS Cloudsystem.