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 probability of unauthorized access being granted through a "brute-force attack."

Example header for request

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

Feedback on failed authentication - 401 Unauthorized

If authentication fails due to invalid user data, the HTTP status code 401 Unauthorized will be returned with the error message Unauthorized access in the body.

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

The Digest Access Authentication is an authentication mechanism using 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 probability of unauthorized access being granted through a "brute-force attack."

Request for a nonce to create the digest

In the initial request, no authentication is provided in the header because the client first needs to request the nonce. In the response from the DataGatewayServer, the nonce along with further information needed to create a digest is included in the HTTP header Www-authenticate.

This request is acknowledged with the HTTP status code 401 Unauthorized and the error message Authentication required! in the body.

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!

Request after receiving nonce

After the client has extracted the nonce, realm, qop, and opaque from the initial request and generated the digest with them, it can be transmitted for authentication via the HTTP header Authorization.

The format is as follows:
Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"

The parameter nc = "Nonce count" and cnonce = "Client nonce" are both generated by the client and must be used for creating the digest.

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

Response on failed authentication

In case of invalid authentication (using the HTTP header Authorization), the HTTP status code 401 Unauthorized is returned with the error message client credentials invalid! in the body.

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 probability of unauthorized access being granted through a "brute-force attack."

Example header for a request

In this example, the API key apikey_heidler is used.

Note: For demonstration purposes, a simple API key is used in this example. The keys generated within the DataGatewayServer follow a more complex algorithm.

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

Response on failed authentication

In case of an incorrect API key, the HTTP status code 401 Unauthorized is returned with the error message api key invalid! in the body.

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 by using the refresh token. A refresh token can only used once.

In case of multiple uses of a refresh token, all refresh tokens and access tokens are automatically disabled.

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 probability of unauthorized access being granted through a "brute-force attack."

Example of token request (generating access and refresh tokens with client ID + client secret)

For the token request, the client ID and client secret must be transmitted in the HTTP header Authorization, base64 encoded in the format - Basic <ClientID>:<ClientSecret>. Additionally, the grant_type with the value client_credentials is necessary for this function.

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

Response of the token request

In the response of the token request, the access token (access_token), refresh token (refresh_token), token type (token_type), and expiration of the access token in seconds (expires_in) are returned in the body.

The access token can now be used for authentication in subsequent requests.

For security reasons, the access token has a expiration time. After expiration, the access token is no longer usable, and a HTTP status code 401 Unauthorized is returned. In this case, a new access token must be generated either through the refresh request with a valid refresh token (recommended), or through the token request with the client ID + client secret (not recommended).

Note: Using the token request regularly to generate an access tokens is not recommended, as it involves transmitting the client ID + client secret. This increases vulnerability to Man-in-the-Middle (MitM) attacks. The client secret should be used as infrequently as possible.

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
}

Example header for using an access token

The access token obtained from the token request can now be transmitted to the DataGatewayServer in the HTTP header Authorization to authenticate. It must be transmitted in the format - Bearer <Access token>.

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

Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)

If an access token has expired and needs to be renewed, a new access token + refresh token can be requested by using the refresh request and a valid refresh token. In this request, the HTTP header refresh_token must be transmitted with the refresh token, and the header grant_type must be transmitted with the value refresh_token.

To enhance security against MitM attacks, it is recommended to regularly update the access token at short intervals.

Note: A refresh token can only be used once for the refresh request. Afterwards, the token is disabled. For security reasons, if an invalid refresh token is used for authentication with the DataGatewayServer all access and refresh tokens, which were created prior to that, will be disabled. Authentication via token request is required afterwards.

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

Response of the refresh request

In the response of the refresh request, the access token (access_token), refresh token (refresh_token), token type (token_type), and validity of the access token (expires_in) in seconds are returned in the body.

The access token can now be used for authentication in subsequent requests.

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
}

Feedback on failed authentication - 401 Unauthorized

If authentication fails, the HTTP status code 401 Unauthorized will be returned along with an appropriate error message in the body.

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

Authorization Code

This authentication method is exclusively available through the authentication system IRIS Cloudsystem.