Wiki - Heidler Strichcode GmbH - Benutzerbeiträge [de]

Carrier API error codes

2026-03-24T15:12:54Z

Odelice:

[[de:Carrier_API_Fehlercodes]]

== General ==
Error codes in the Carrier API appear in the following form <code>AAA-SSS-GG-L[Code]</code>, where
* AAA = Application, in this case only CAP for CarrierAPI
* SSS = Sub group, in this case the plugin. A list of plugins can be found further down.
* GG = Error group, this divides the errors in categories, where the cause normally originates from
* L = Error-level, the severeness of the error: W = Warning, E = Error, C = Critical, F = Fatal
* [Code] = A numerical Code that clearly assigns the error in this group.

Example: <code>CAP-HEH-02-E00005</code>

Means there is an error in the Hermes HSI module in group 02 (content-related error) with code 5 (authentification failed).

To search for an error, search on this site <code>(Strg+F)</code> with the acutal code.

If you can not find the code directly, replace the sub group, e.g. "HEH" with <code>XXX</code>. From the top example: <code>CAP-XXX-02-E00005</code>. This code is available in group 02.

== Group 00 - Fundamental errors ==
These errors appear if the error cause is unknown (e.g. 00000 - undefined error) or when a fundamental problem lies within the functionalities of the Carrier API.

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-XXX-00-E00000 || Error in webservice request: [Error message] || Error cause unknown. Examine exact error message, if necessary check logs.
|-
| CAP-XXX-00-E00001 || Unable to create plugin || Problem when calling the webservice plugin. Please contact support
|-
| CAP-XXX-00-E00002 || The selected Carrier API plugin has been deprecated. Please contact Heidler Support || The selected Carrier API plugin is deprecated and the webservice is discontinued by the carrier. Please contact support
|}

== Group 01 - Technical errors in the request ==
These errors appear if the request was not successful due to a technical error. They can be temporary problems, e.g. the server is not accessible (00001 - connection error) or overloaded (00002 - Read timeout). Or fundamental problems which require interference (00004 - certificate error).

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-XXX-01-C00001 || [Connection error / Connection timeout] Unable to connect to webservice. Please check your internet connection, url, firewall, or proxy settings. || Connection error: No connection possible. Maybe the request was blocked.
Connect timeout: The Carrier API could not determine that the connection was blocked. Maybe the connection quality is insufficient.
|-
| CAP-XXX-01-E00002 || Read timeout: The webservice did not respond in a timely manner. || Normally, the server of the carrier is overloaded. You can try to increase the Read timeout in the general settings or for this specific endpoint.
|-
|-
| CAP-XXX-01-C00003 || DNS error: The url [URL] is unknown || Your DNS-Server blocks the request of the Carrier API or the URL set is not correct.
|-
|-
| CAP-XXX-01-C00004 || Unable to verify webservice certificate. Please check your firewall or url. || If your firewall contains a deep packet inspection, it provides a certificate in between, which is unknown to the Carrier API. The Carrier API interprets it as a [https://de.wikipedia.org/wiki/Man-in-the-Middle-Angriff Man-in-the-Middle-Angriff].
If you trust the certificate, you can save it X.509 coded under [CarrierAPI]\config\certs.
|-
|-
| CAP-XXX-01-F00005 || Deserialization error: The webservice returned an invalid document || Please contact support.
|-
|-
| CAP-XXX-01-E00006 || Label conversion error || Please contact support.
|}

== Group 02 - Content-related errors in the request ==
The communication with the webservice was successful, but the response does not math the expectation. Normally, the webservice has found an error in the request (shipment data set) and returns it.

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-XXX-02-E00001 || General response error || The Carrier API can not assign the error. Please check the exact error message to this error code.
|-
| CAP-XXX-02-E00002 || Webservice returned error: [Error message] || The webservice has responded with an exact error code and/or error message. Please check it and correct the data set if necessary.
|-
| CAP-XXX-02-E00003 || Webservice returned an invalid response: [Error detail] || The response from the webservice does not match the conventions known by the Carrier API. Possibly some mandatory fields are missing in the response (e.g. tracking number or label data). Please check the eroor details and contact the support if necessary.
|-
| CAP-XXX-02-E00004 || Webservice returned HTTP [HTTP-Code] || No detailed error details are known except for the webservice respoding with a "not OK".
In the logs of the Carrier API you can normally findthe whole response from the webservice wich may contain more details.
|-
| CAP-XXX-02-E00005 || Authentication with the webservice failed. Please check your login details. || Normally the access data set in the Carrier API is wrong or the carrier has not unlocked your account yet.
|-
| CAP-XXX-02-E00006 || The webservice did not change the shipment status within a reasonable amount of time (asynchronous webservice operation).
| With asynchronous webservices (e.g. Inpost24 or FedEx Stratus), the Carrier API waits until the webservice responds with a Completed or Error status. If this does not occur in time, the Carrier API throws this error.
|}

== Group 03 - Validation error ==
For some carriers, the Carrier API executes a limited validation and returns an error even before the request to the webservice, when it is predictable that the request is not accepted by the carrier.

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-XXX-03-E00001 || Validation error: [Error details] || Validation error which does not fit the following categories. Please check the error details.
|-
| CAP-XXX-03-E00002 || Invalid reference number || The webservice needs a clear reference number (e.g. delivery note number)
|-
|-
| CAP-XXX-03-E00003 || Receiver address is invalid || e.g. missing PLZ, street, house no. etc.
|-
|-
| CAP-XXX-03-E00004 || Street and house number needs to be separated
| Street and house no. need to be separated in the shipment. The separation was not configured in the HVS32 (contact support) or the separation was not successful (check data set: house no. at the end or start of the street?)
|-
|-
| CAP-XXX-03-E00005 || Unable to separate first and last name for: [Name] || For the separation of first and last name, you need two words.
|-
|-
| CAP-XXX-03-E00006 || Invalid incoterm id || A completely missing incoterm or the carrier ony accepts specific incoterms.
|-
|-
| CAP-XXX-03-E00007 || Target date is invalid || A service was selected that expects a target date. It is not filled or is in the past.
|-
|-
| CAP-XXX-03-E00008 || Customer / account number is invalid || The customer number in the HVS32 configurator or the user in the Carrier API configurator does not match the conditions of the carrier (e.g. numerical).
|-
|-
| CAP-XXX-03-E00009 || Shipment number is invalid || The HVS32 should create a shipment number (contact support) or expects it from the host system (check data set).
|-
|-
| CAP-XXX-03-E00010 || Tracking number is invalid || The HVS32 should create a tracking number (contact support) or expects it from the host system (check data set).
|-
|-
| CAP-XXX-03-E00011 || Service type id is invalid || The configured service is invalid for this carrier.
|-
|-
| CAP-XXX-03-E00012 || Invalid e-mail address || This shipment needs an email address with the selected service. It has not been delivered. Please check the data set.
|-
|-
| CAP-XXX-03-E00013 || Invalid phone number || This shipment needs a phone number with the selected service. It has not been delivered. Please check the data set.
|-
|-
| CAP-XXX-03-E00014 || Invalid value of goods || This shipment needs the value of goods with the selected service. It has not been delivered or it s an invalid number. Please check the data set.
|-
|-
| CAP-XXX-03-E00015 || Invalid insurance value || This shipment needs an insurance value with the selected service. It has not been delivered or it s an invalid number. Please check the data set.
|-
|-
| CAP-XXX-03-E00016 || Invalid id for parcel shop || A parcel shop shipment has been selected for this shiment. But the corresponding parcel shop id is missing or invalid (e.g. numerical).
|-
|-
| CAP-XXX-03-E00017 || The requested service requires additional data. || A specific service has been selected for this shipment. But additional information for this service is missing that is necessary.
|-
|-
| CAP-XXX-03-E00030 || Weight is invalid || The chosen package weight does not match the conditions of the carrier (e.g. 0kg or more than the carrier accepts). Please check the data set.
|-
|-
| CAP-XXX-03-E00031 || Package dimensions are invalid. || The carrier expects package dimensions that are missing in the data set. Please check the data set.
|-
|-
| CAP-XXX-03-E00032 || Package type id is invalid || The package type is completely missing or the carrier only accepts specifc package types.
|-
|-
| CAP-XXX-03-E00033 || Package contents are invalid || This shipment needs the package content with the selected service. It has not been delivered. Please check the data set.
|-
|-
| CAP-XXX-03-E00038 || No article data available in package || Shipments outside of the EU normally require additional article data to correctly transfer the customs information.
|-
|-
| CAP-XXX-03-E00039 || No hazardous goods data available in package || The selceted service is a dangerous goods service. But the dangerous goods data is missing in the data set.
|}

== Group 04 - Configuration error ==
Errors in group 04 mostly have their cause due to a not fully configurated module in the HVS32 or in the Carrier API. It is also possible that the data set is incorrect and refers to a false configuration (e.g. when an invalid dispatch type ID is sent).

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-000-04-C00001 || No dispatch type found for id: [Dispatch type ID] || The Carrier API can not find a configuration entry with the chosen dispatch type ID.The configuration is incomplete or the transferred dispatch type ID is wrong.
|-
| CAP-000-04-C00002 || No client found for id: [Client ID] || The Carrier API can not find a configuration entry with the chosen client ID.The configuration is incomplete or the transferred client ID is wrong.
|-
|-
| CAP-000-04-C00003 || Plugin [Plugin] is not licensed || The dispatch type or rather the endpoint refers to a carrier plugin has not been licensed yet or is not anymore. Please contact the support.
|-
|-
| CAP-XXX-04-C00004 || No endpoint defined for dispatch type: [Dispatch type ID] || The selected dispatch type has been found in the Carrier API but not the endpoint, which the dispatch type refers to. Please contact the support.
|-
|-
| CAP-XXX-04-C00005 || Endpoint url is invalid: [URL] || The configured URL in the endpoint is invalid. Please contact the support.
|-
|-
| CAP-XXX-04-C00006 || Invalid configuration for: [Configuration details] || A carrier specific configuration is incomplete. Please check the detailed error message for more details.
|}

== Carrier-specific errors ==
Some carriers have special error codes that can not be be generally assigned. In most cases, it is an extended validation error from group 03.

=== GLS Ship IT ===

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-GLS-03-E00050 || Invalid GLS contact id || Die im HVS32 konfigurierte Contact ID fehlt oder ist ungültig
|}

=== Hermes Shipping Interface (HSI) ===

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-HEH-03-E00050 || Invalid package type and dimensions. At least one is required. || Hermes hat Verpackungen im Format XS, S, M, L, XL
|-
|-
| CAP-HEH-03-E00051 || Invalid birthday for ident service || Für diese Sendung wurde ein Ident-Service gewählt. Das Geburtsdatum fehlt allerdings oder handelt sich nicht um ein gültiges Datum.
|}

=== Schenker AT ===

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Description
|-
| CAP-SHA-03-E00050 || Error in hazardous goods dataset. Invalid UN number. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die UN-Nummer
|-
|-
| CAP-SHA-03-E00051 || Error in hazardous goods dataset. Invalid DG class. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Klasse.
|-
|-
| CAP-SHA-03-E00052 || Error in hazardous goods dataset. Invalid dg weight. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie das GG-Gewicht.
|-
|-
| CAP-SHA-03-E00053 || Error in hazardous goods dataset. Invalid package type. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Verpackungsart.
|-
|-
| CAP-SHA-03-E00054 || Error in hazardous goods dataset. Invalid dg package group. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Verpackungsgruppe.
|-
|-
| CAP-SHA-03-E00055 || Error in hazardous goods dataset. Invalid shipping name. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Bezeichnung
|-
|-
| CAP-SHA-03-E00056 || Error in hazardous goods dataset. No net explosive mass defined for dg class 1. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die Netto-Explosivmasse. Außerdem: Wurde mit Schenker AT abgesprochen, dass Sie Torpedos verschicken?
|-
|-
| CAP-SHA-03-E00057 || Error in hazardous goods dataset. Invalid unit of measurement.
| Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie den Mengen-Typ (kg oder l)
|}

== Plugin codes ==
Each plugin has its own sub-group for an error code. All plugins are listed in the following.

{| class="wikitable sortable"
|-
! Code !! Plugin
|-
| 000 || Unbekannt - Plugin konnte noch nicht ermittelt werden
|-
| ACO || Arco
|-
| AGX || AGX
|-
| AMZ || Amazon Merchant Fulfillment
|-
| ANL || ANGEL
|-
| ASE || Asendia
|-
| ASM || Amazon Selling Partner API - Merchant Fulfillment
|-
| ASV || Amazon Selling Partner API - Vendor Direct
|-
| ATL || Atlas
|-
| CAL || Canis Lupus
|-
| CEN || Centiro
|-
| CHR || Chronopost
|-
| CIP || Citipost
|-
| COU || Coureon
|-
| DBB || DHL ES B2B
|-
| DCS || DCS
|-
| DEC || DHL eConnect
|-
| DEL || DHL Express Routing Live
|-
| DET || DHL Express Routing Test
|-
| DFR || DPD FR (Frankreich)
|-
| DHA || DHL ELP (Abholung)
|-
| DHE || DHL ES B2C
|-
| DHH || DHL Global Web Service (Ungarn)
|-
| DHN || DHL NL
|-
| DHP || DHL 24 PL
|-
| DHS || DHL SK (Slowakei)
|-
| DIM || Internetmarke (Deutsche Post)
|-
| DPA || DPD AT (Österreich)
|-
| DPL || DPD PL (Polen)
|-
| DPC || DPD HR (Kroatien)
|-
| DPH || DPD HU (Ungarn)
|-
| DPP || DPD DE Parcelshop Suche
|-
| DPR || DPD RO (Rumänien)
|-
| DNL || DPD NL (Niederlande)
|-
| DRI || DHL Retoure International
|-
| DRL || DHL Retoure International (Legacy - veraltet)
|-
| DSK || Danske
|-
| DVF || AM.Exchange (DV-Freimachung)
|-
| EPK || Europaket
|-
| FED || Fedex
|-
| FAC || Fiege Amazon Carma
|-
| FTD || Fedex Trade Documents
|-
| FXA || Fedex (Abholung)
|-
| FXP || Fedex PL (Polen)
|-
| FXS || Fedex Stratus REST API
|-
| GEO || Geodis
|-
| GLD || GLS DK (Dänemark)
|-
| GLE || GLS ES (Spanien)
|-
| GLF || GLS FR (Frankreich)
|-
| GLH || GLS HU (Ungarn)
|-
| GLI || GLS IT (Italien)
|-
| GLK || GLS SK (Slowakei)
|-
| GLL || GLS CZ (Tschechien)
|-
| GLN || GLS NL (Niederlande)
|-
| GLO || Glovo
|-
| GLP || GLS PL (Polen)
|-
| GLS || GLS DE / Ship IT (Deutschland)
|-
| GPP || General Purpose (konfigurierbar), auch G00 - G99
|-
| GPS || GLS Parcel Shop (GLS DE Parcelshop Suche)
|-
| GSA || GLS AT / Ship IT (Österreich)
|-
| GSD || GLS DK / Ship IT (Dänemark)
|-
| GSF || GLS FR / Ship IT (Frankreich)
|-
| GTT || GLS DE Track & Trace
|-
| HBG || Hermes Border Guru
|-
| HEH || Hermes Shipping Interface (HSI)
|-
| HES || Hermes Einrichtungs Service (HES)
|-
| HRB || Hornbach
|-
| HMP || Hellmann PL (Polen)
|-
|ICS || ICS
|-
| INP || Inpost24
|-
| IZP || Infens Zustellprofi
|-
|KOV || Kommt Overnight
|-
| KUR || Der Kurier
|-
| LFG || Liefergrün
|-
| LGX || Log X Star
|-
| MON || Mondial Relay
|-
| NCX || Nacex
|-
| OMS || Omest
|-
| ONT || Ontime
|-
| PAT || Post AT (Österreich)
|-
| PFI || Posti FI (Finnland)
|-
| PHR || Posti HR (Kroatien)
|-
| PIL || Pilot
|-
| PPL || PPL
|-
| PSI || Post SI (Slovenien)
|-
| PSK || Post SK (Slovakei)
|-
| SES || Seven Senders (7senders)
|-
| SHA || Schenker AT (Österreich)
|-
| SHD || Schenker
|-
| SHS || Schenker SE (Schweden)
|-
| SND || Sending
|-
| TBN || TNT NL - Retoure Belgien
|-
| TMP || TMParcel
|-
| TNF || TNT FR (Frankreich)
|-
| TNI || TNT IT (Italien)
|-
| TNN || TNT Post NL (Niederlande)
|-
| TNT || TNT (Deutschland)
|-
| TOH || TOF HU (Ungarn)
|-
| TPN || TPN
|-
| TRA || Tradebyte
|-
| TRM || Tiramizoo
|-
| UPA || UPS Pickup (Abholung)
|-
| UPG || UPS GG (Gefahrgut PreAvis)
|-
| UPP || UPS Paperless Document
|-
| UPT || UPS Tarifierung
|-
| VNP || Venipak
|-
| WYF || Wayfair
|}

Carrier API Fehlercodes

2026-03-24T15:12:12Z

Odelice:

[[en:Carrier_API_error_codes]]

== Allgemeines ==
Fehlercodes in der Carrier API sind nach dem Schema <code>AAA-SSS-GG-L[Code]</code>, wobei
* AAA = Applikation, in diesem Fall nur CAP für Carrier API
* SSS = Subgruppe, in diesem Fall das Plugin. Eine Auflistung der Plugins finden Sie weiter unten.
* GG = Fehlergruppe, diese teilt den Fehler in Kategorien, woher die Ursache in der Regel kommt
* L = Fehler-Level, wie schwerwiegend der Fehler ist: W = Warning, E = Error, C = Critical, F = Fatal
* [Code] = Ein numerischer Code, welche den Fehler in dieser Gruppe eindeutig zuordnet.

Beispiel: <code>CAP-HEH-02-E00005</code>

Bedeutet in diesem Fall ein Fehler innerhalb des Hermes HSI Moduls in der Gruppe 02 (Inhaltliche Fehler) mit dem Code 5 (Authentifizierung fehlgeschlagen).

Um einen Fehler zu suchen, suchen Sie bitte auf dieser Seite <code>(Strg+F)</code> zunächst mit dem eigentlichen Code.

Falls Sie den Code nicht direkt finden können, ersetzen Sie bitte die Subgruppe z.B. "HEH" durch <code>XXX</code>. Aus dem obigen Beispiel: <code>CAP-XXX-02-E00005</code>. Dieser Code ist in der Gruppe 02 vorhanden.

== Gruppe 00 - Grundlegende Fehler ==
Diese Fehler treten auf, wenn die Fehlerursache nicht bekannt ist (z.B. 00000 - Undefinierter Fehler) oder ein grundlegendes Problem in der Funktionweise der Carrier API vorliegt.

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-XXX-00-E00000 || Fehler in Webservice Anfrage: [Fehlermeldung] || Fehlerursache nicht bekannt. Genaue Fehlermeldung untersuchen, ggf. Logs einsehen.
|-
| CAP-XXX-00-E00001 || Plugin kann nicht erstellt werden || Problem beim aufrufen des jeweiligen Webservice-Plugins. Bitte Support kontaktieren
|-
| CAP-XXX-00-E00002 || Plugin veraltet || Das gewählte Carrier API Plugin ist veraltet und der Webservice wurde vom Frachtführer abgekündigt. Bitte Support kontaktieren
|}

== Gruppe 01 - Technische Fehler in der Anfrage ==
Diese Fehler treten auf, wenn die Anfrage aufgrund eines technischen Fehlers nicht erfolgreich war.
Dies können temporäre Probleme sein, wenn der Server z.B. nicht erreichbar ist (00001 - Verbindungsfehler) oder überlastet ist (00002 - Read timeout).
Oder aber grundlegende Probleme welche einen Eingriff erfordern (00004 - Zertifikatsfehler).

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-XXX-01-C00001 || [Connection error / Connection timeout] Es konnte keine Verbindung zum Webservice hergestellt werden. Bitte prüfen Sie Ihre Internet-Verbindung, URL, Firewall-, oder Proxy-Einstellungen. || Connection error: Verbindung nicht möglich. Eventuell wurde die Anfrage blockiert.
Connect timeout: Die Carrier API konnte nicht feststellen, dass die Verbindung blockiert wurde. Eventuell ist die Verbindungsqualität nicht ausreichend.
|-
| CAP-XXX-01-E00002 || Read timeout: Der Webservice hat nicht rechtzeitig auf die Anfrage reagiert. || In der Regel ist der Server vom Frachtführer überlastet. Sie können in den allgemeinen Einstellungen oder für diesen Endpoint versuchen, den Read timeout auf einen höheren Wert zu stellen.
|-
|-
| CAP-XXX-01-C00003 || DNS Fehler: Die URL [URL] ist unbekannt || Entweder blockiert Ihr DNS-Server die Anfrage der Carrier API oder die hinterlegte URL ist nicht korrekt.
|-
|-
| CAP-XXX-01-C00004 || Zertifikat vom Webservice kann nicht verifiziert werden. Bitte prüfen Sie Ihre Firewall oder URL. || Falls Ihre Firewall eine deep packet inspection enthält, stellt Sie ein Zwischen-Zertifikat bereit, welches der Carrier API nicht bekannt ist. Das wird von der Carrier-API als [https://de.wikipedia.org/wiki/Man-in-the-Middle-Angriff Man-in-the-Middle-Angriff] interpretiert.
Wenn Sie dem Zertifikat vertrauen, können Sie es X.509 kodiert unter [CarrierAPI]\config\certs hinterlegen.
|-
|-
| CAP-XXX-01-F00005 || Deserialisierungsfehler: Der Webservice hat ein ungültiges Dokument zurückgemeldet. || Bitte Support kontaktieren.
|-
|-
| CAP-XXX-01-E00006 || Labelkonvertierung fehlgeschlagen || Bitte Support kontaktieren.
|}

== Gruppe 02 - Inhaltliche Fehler in der Anfrage ==
Die Kommunikation mit dem Webservice war erfolgreich, allerdings entspricht die Antwort nicht der Erwartung. In der Regel hat der Webservice einen Fehler in der Anfrage (Sendungsdatensatz) gefunden und gibt diesen zurück.

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-XXX-02-E00001 || Allgemeiner Rückmeldungs-Fehler || Die Carrier API kann den Fehler nicht genau zuordnen. Bitte prüfen Sie die genaue Fehlermeldung zu diesem Fehlercode.
|-
| CAP-XXX-02-E00002 || Fehler vom Webservice: [Fehlertext] || Der Webservice hat einen genauen Fehlercode und/oder Fehlertext zurückgemeldet. Bitte diesen genau prüfen und ggf. den Datensatz korrigieren.
|-
| CAP-XXX-02-E00003 || Ungültige Antwort von Webservice: [Fehler-Detail] || Die Antwort vom Webservice entspricht nicht den Konventionen, welche der Carrier API bekannt sind. Es fehlen u.U. Pflichtfelder in der Antwort (z.B. Tracking-Nummer oder Label-Daten). Bitte prüfen Sie die Fehler-Details und kontaktieren Sie ggf. den Support.
|-
| CAP-XXX-02-E00004 || Webservice hat HTTP [HTTP-Code] zurückgegeben || Es sind keine genauen Fehler-Details bekannt, außer dass der Webservice generell ein "Nicht-OK" zurückgegeben hat.
In den Logs der Carrier API finden Sie in der Regel die gesamte Antwort des Webservice, welche eventuell weitere Details enthalten.
|-
| CAP-XXX-02-E00005 || Authentifizierung mit dem Webservice fehlgeschlagen. Bitte prüfen Sie Ihre Zugangsdaten. || In der Regel sind die in der Carrier API hinterlegten Zugangsdaten falsch, oder der Frachtführer hat Ihren Account noch nicht freigeschaltet.
|-
| CAP-XXX-02-E00006 || Der Webservice hat den Sendungsstaus nicht in angemessener Zeit geändert || Bei asynchronen Webservices (z.B: Inpost24 oder FedEx Stratus) wartet die Carrier API bis vom Webservice ein Abgeschlossen- oder Fehler-Status zurück kommt. Sollte dies nicht rechtzeitig erfolgen, dann wirft die Carrier API diesen Fehler.
|}

== Gruppe 03 - Validierungsfehler ==
Bei manchen Frachtführern führt die Carrier API eine begrenzte Validierung selbst durch und gibt bereits vor der Anfrage an den Webservice einen Fehler zurück, wenn absehbar ist, dass diese Anfrage beim Frachtführer nicht akzeptiert wird.

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-XXX-03-E00001 || Validierungsfehler: [Fehler-Details] || Validierungsfehler, welcher nicht unter einer der folgenden Kategorien zutrifft. Bitte die Fehler-Details prüfen.
|-
| CAP-XXX-03-E00002 || Ungültige Referenznummer || Der Webservice benötigt eine eindeutige Referenz-Nummer (z.B. Lieferschein-Nr.)
|-
|-
| CAP-XXX-03-E00003 || Empfänger Adresse ist ungültig || z.B. fehlende PLZ, Straße, Haus-Nr. usw.
|-
|-
| CAP-XXX-03-E00004 || Straße und Hausnummer muss getrennt werden || In der Sendung müssen Straße und Hausnummer separiert werden. Entweder wurde die Trennung im HVS32 nicht konfiguriert (Support kontaktieren) oder die Trennung war nicht erfolgreich (Datensatz kontrollieren: Hausnummer ganz am Ende oder Anfang der Straße?)
|-
|-
| CAP-XXX-03-E00005 || Trennung von Vor- und Nachname nicht möglich für: [Name] || Für die Trennung von Vor- und Nachnamen sind immer zwei Wörter erforderlich.
|-
|-
| CAP-XXX-03-E00006 || Ungültige Frankatur/Incoterm || Entweder fehlt eine Frankatur komplett oder der Frachtführer akzeptiert nur ganz bestimmte Frankaturen.
|-
|-
| CAP-XXX-03-E00007 || Termin Datum ist nicht gültig || Es wurde ein Dienst ausgewählt welcher ein Termin-Datum erwartet. Dieses ist entweder nicht belegt oder liegt in der Vergangenheit.
|-
|-
| CAP-XXX-03-E00008 || Kunden- / Account-Nr. ist ungültig || Die Kunden-Nr. im HVS32-Konfigurator oder der Benutzer im Carrier API Konfigurator entspricht nicht den Vorgaben des Frachtführers (z.B. numerisch).
|-
|-
| CAP-XXX-03-E00009 || Sendungsnummer ist ungültig || Das HVS32 sollte eigentlich eine (Versand-)Sendungs-Nummer erzeugen (Support kontaktieren) oder erwartet diese aus dem Vorsystem (Datensatz prüfen).
|-
|-
| CAP-XXX-03-E00010 || Trackingnummer ist ungültig || Das HVS32 sollte eigentlich eine Trackingnummer erzeugen (Support kontaktieren) oder erwartet diese aus dem Vorsystem (Datensatz prüfen).
|-
|-
| CAP-XXX-03-E00011 || Sonderdienst-ID ist ungültig || Der konfigurierte Dienst ist für diesen Frachtführer nicht gültig.
|-
|-
| CAP-XXX-03-E00012 || Ungültige E-Mail Adresse || Diese Sendung benötigt mit dem gewählten Dienst eine E-Mail Adresse. Diese wurde nicht übergeben. Bitte prüfen Sie den Datensatz.
|-
|-
| CAP-XXX-03-E00013 || Ungültige Telefonnummer || Diese Sendung benötigt mit dem gewählten Dienst eine Telefon-Nummer. Diese wurde nicht übergeben. Bitte prüfen Sie den Datensatz.
|-
|-
| CAP-XXX-03-E00014 || Ungültiger Warenwert || Diese Sendung benötigt mit dem gewählten Dienst einen Warenwert. Diese wurde nicht übergeben oder ist keine gültige Zahl. Bitte prüfen Sie den Datensatz.
|-
|-
| CAP-XXX-03-E00015 || Ungültiger Versicherungswert || Diese Sendung benötigt mit dem gewählten Dienst einen Versicherungswert. Diese wurde nicht übergeben oder ist keine gültige Zahl. Bitte prüfen Sie den Datensatz.
|-
|-
| CAP-XXX-03-E00016 || Ungültige ID für Paketshop || Für diese Sendung wurde eine Paketshop-Lieferung gewählt. Allerdings fehlt die dazugehörige Paketshop-ID oder sie ist nicht gültig (z.B. numerisch).
|-
|-
| CAP-XXX-03-E00017 || Fehlende Information für gewählten Service || Für diese Sendung wurde ein spezifischer Dienst gewählt. Allerdings fehlen für diesen Dienst zusätzliche Informationen, welche nun notwendig sind.
|-
|-
| CAP-XXX-03-E00030 || Gewicht ist ungültig || Das angegebene Packstück-Gewicht entspricht nicht den Vorgaben des Frachtführers (z.B. 0 kg oder mehr als der Frachtführer akzeptiert). Bitte prüfen Sie den Datensatz.
|-
|-
| CAP-XXX-03-E00031 || Paketabmessungen sind ungültig. || Der Frachtführer erwartet Paketabmessungen welche im Datensatz fehlen. Bitte prüfen Sie den Datensatz.
|-
|-
| CAP-XXX-03-E00032 || Verpackungart-ID ist ungültig || Entweder fehlt die Verpackungsart komplett oder der Frachtführer akzeptiert nur ganz bestimmte Verpackungsarten.
|-
|-
| CAP-XXX-03-E00033 || Paketinhalt ist ungültig || Diese Sendung benötigt mit dem gewählten Dienst den Paketinhalt. Dieser wurde nicht übergeben. Bitte prüfen Sie den Datensatz.
|-
|-
| CAP-XXX-03-E00038 || Keine Artikeldaten im Packstück vorhanden || Sendungen ins EU-Ausland benötigen in der Regel zusätzlich Artikeldaten um die Zollinformationen korrekt zu übergeben.
|-
|-
| CAP-XXX-03-E00039 || Keine Gefahrgutdaten im Packstück vorhanden || Beim gewählten Dienst handelt es sich um einen Gefahrgut-Dienst. Allerdings fehlen im Datensatz die Gefahrgutdaten.
|}

== Gruppe 04 - Konfigurationsfehler ==
Fehler der Gruppe 04 haben Ihre Ursache meist in einem nicht vollständig konfiguriertem Modul im HVS32 oder in der Carrier API. Unter Umständen kann aber auch der Datensatz fehlerhaft sein und auf eine falsche Konfiguration verweisen (z.B. wenn eine ungültige Versandart übergeben wurde).

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-000-04-C00001 || Keine Versandart gefunden für ID: [Versandart-ID] || Die Carrier API kann keinen Konfigurationseintrag mit der gewählten Versandart-ID finden. Entweder ist die Konfiguration unvollständig oder die übergebene Versandart-ID ist falsch.
|-
| CAP-000-04-C00002 || Kein Auftragggeber gefunden für ID: [Auftraggeber-ID] || Die Carrier API kann keinen Konfigurationseintrag mit der gewählten Auftraggeber-ID finden. Entweder ist die Konfiguration unvollständig oder die übergebene Auftraggeber-ID ist falsch.
|-
|-
| CAP-000-04-C00003 || Plugin [Plugin] ist nicht lizensiert || Die Versandart bzw. der Endpoint verweist auf ein Frachtführer-Plugin welches noch nicht oder nicht mehr lizensiert ist. Bitte kontaktieren Sie den Support.
|-
|-
| CAP-XXX-04-C00004 || Kein Endpoint definiert für Versandart: [Versandart-ID] || Die gewählte Versandart wurde in der Carrier API gefunden allerdings nicht den Endpoint, auf welche diese Versandart verweist. Bitte kontaktieren Sie den Support.
|-
|-
| CAP-XXX-04-C00005 || Endpoint URL ist ungültig: [URL] || Bei der im Endpoint konfigurierten URL handelt es sich nicht um eine gültige URL. Bitte kontaktieren Sie den Support.
|-
|-
| CAP-XXX-04-C00006 || Ungültige Konfiguration für: [Konfigurations-Details] || Eine Frachtführer-spezifische Konfiguration ist unvollständig. Bitte prüfen Sie die Detaillierte Fehlermeldung für mehr Details
|}

== Frachtführer-Spezifische Fehler ==
Manche Frachtführer haben spezialisierte Fehlercodes, sofern es sich um einen Fehler handelt, welcher nicht allgemein zugeordnet werden kann. In den meisten Fehlern handelt es sich um erweiterte Validierungsfehler aus der Gruppe 03.

=== GLS Ship IT ===

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-GLS-03-E00050 || Ungültige GLS Contact ID || Die im HVS32 konfigurierte Contact ID fehlt oder ist ungültig
|}

=== Hermes Shipping Interface (HSI) ===

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-HEH-03-E00050 || Ungültige Verpackungsart und Abmessungen. Mindestens eine Angabe ist erforderlich. || Hermes hat Verpackungen im Format XS, S, M, L, XL
|-
|-
| CAP-HEH-03-E00051 || Ungültiges Geburtsdatum für Ident-Service || Für diese Sendung wurde ein Ident-Service gewählt. Das Geburtsdatum fehlt allerdings oder handelt sich nicht um ein gültiges Datum.
|}

=== Schenker AT ===

{| class="wikitable"
|-
! style="width:140px" | Code !! style="width:300px" | Text !! Beschreibung
|-
| CAP-SHA-03-E00050 || Fehler in Gefahrgutsatz. Ungültige UN Nummer. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die UN-Nummer
|-
|-
| CAP-SHA-03-E00051 || Fehler in Gefahrgutsatz. Ungültige GG-Klasse. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Klasse.
|-
|-
| CAP-SHA-03-E00052 || Fehler in Gefahrgutsatz. Ungültiges GG-Gewicht. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie das GG-Gewicht.
|-
|-
| CAP-SHA-03-E00053 || Fehler in Gefahrgutsatz. Ungültige GG-Verpackung. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Verpackungsart.
|-
|-
| CAP-SHA-03-E00054 || Fehler in Gefahrgutsatz. Ungültige GG-Verpackungsgruppe. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Verpackungsgruppe.
|-
|-
| CAP-SHA-03-E00055 || Fehler in Gefahrgutsatz. Ungültige Bezeichnung. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die GG-Bezeichnung
|-
|-
| CAP-SHA-03-E00056 || Fehler in Gefahrgutsatz. Keine Netto-Explosivmasse definiert für GG-Klasse 1. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie die Netto-Explosivmasse. Außerdem: Wurde mit Schenker AT abgesprochen, dass Sie Torpedos verschicken?
|-
|-
| CAP-SHA-03-E00057 || Fehler in Gefahrgutsatz. Ungültiger Mengen-Typ. || Der Gefahrgutsatz ist unvollständig. Bitte prüfen Sie den Mengen-Typ (kg oder l)
|}

== Plugin Codes ==
Jedes Plugin hat seine eigene Sub-Gruppe für einen Fehlercode. Nachfolgend aufgelistet sind alle Plugins.

{| class="wikitable sortable"
|-
! Code !! Plugin
|-
| 000 || Unbekannt - Plugin konnte noch nicht ermittelt werden
|-
| AGX || AGX
|-
| AMZ || Amazon Merchant Fulfillment
|-
| AS2 || Amazon Shipping API v2
|-
| ASM || Amazon Selling Partner API - Merchant Fulfillment
|-
| ASV || Amazon Selling Partner API - Vendor Direct
|-
| DVF || AM.Exchange (DV-Freimachung)
|-
| ANL || Angel
|-
| APC || APC Overnight
|-
| ACO || Arco
|-
| ASE || Asendia
|-
| ATL || Atlas
|-
| CAL || Canis Lupus
|-
| CAR || Carousel
|-
| CEN || Centiro
|-
| CHR || Chronopost
|-
| CIP || Citipost
|-
| COU || Coureon
|-
| DSK || Danske
|-
| DCS || DCS
|-
| KUR || Der Kurier
|-
| DHP || DHL 24 PL
|-
| DEC || DHL eConnect
|-
| DHA || DHL ELP (Abholung)
|-
| DBB || DHL ES B2B
|-
| DHE || DHL ES B2C
|-
| DEL || DHL Express Routing Live
|-
| DET || DHL Express Routing Test
|-
| DHH || DHL Global Web Service (Ungarn)
|-
| DHN || DHL NL
|-
| DRL || DHL Retoure International (Legacy - veraltet)
|-
| DRI || DHL Retoure International
|-
| DHS || DHL SK (Slowakei)
|-
| DPD || DPD
|-
| DPA || DPD AT (Österreich)
|-
| DFR || DPD FR (Frankreich)
|-
| DPC || DPD HR (Kroatien)
|-
| DPH || DPD HU (Ungarn)
|-
| DPP || DPD DE Parcelshop Suche
|-
| DPL || DPD PL (Polen)
|-
| DPR || DPD RO (Rumänien)
|-
| DNL || DPD NL (Niederlande)
|-
| EPK || Europaket
|-
| FTD || Fedex Trade Documents
|-
| FXA || Fedex (Abholung)
|-
| FXP || Fedex PL (Polen)
|-
| FXS || Fedex Stratus REST API
|-
| FED || Fedex
|-
| FAC || Fiege Amazon Carma
|-
| GPP || General Purpose (konfigurierbar), auch G00 - G99
|-
| GEO || Geodis
|-
| GLO || Glovo
|-
| GLL || GLS CZ (Tschechien)
|-
| GLD || GLS DK (Dänemark)
|-
| GLE || GLS ES (Spanien)
|-
| GLF || GLS FR (Frankreich)
|-
| GLH || GLS HU (Ungarn)
|-
| GLI || GLS IT (Italien)
|-
| GLN || GLS NL (Niederlande)
|-
| GLP || GLS PL (Polen)
|-
| GPS || GLS Parcel Shop (GLS DE Parcelshop Suche)
|-
| GSA || GLS AT / Ship IT (Österreich)
|-
| GSD || GLS DK / Ship IT (Dänemark)
|-
| GSF || GLS FR / Ship IT (Frankreich)
|-
| GSP || GLS PL / Ship IT (Polen)
|-
| GLS || GLS DE / Ship IT (Deutschland)
|-
| GLK || GLS SK (Slowakei)
|-
| GTT || GLS DE Track & Trace
|-
| HMP || Hellmann PL (Polen)
|-
| HBG || Hermes Border Guru
|-
| HES || Hermes Einrichtungs Service (HES)
|-
| HEH || Hermes Shipping Interface (HSI)
|-
| HRB || Hornbach
|-
| ICS || ICS
|-
| INP || Inpost24
|-
| DIM || Internetmarke (Deutsche Post)
|-
| IZP || Infens Zustellprofi
|-
| KOV || Kommt Overnight
|-
| LFG || Liefergrün
|-
| LGX || Log X Star
|-
| MON || Mondial Relay
|-
| PPL || PPL
|-
| NCX || Nacex
|-
| OMS || Omest
|-
| ONT || Ontime
|-
| PLW || Palletways
|-
| PIL || Pilot
|-
| PAT || Post AT (Österreich)
|-
| PHR || Posti HR (Kroatien)
|-
| PFI || Posti FI (Finnland)
|-
| PON || Post Nord
|-
| PSI || Post SI (Slovenien)
|-
| PSK || Post SK (Slovakei)
|-
| PPL || PPL
|-
| SHA || Schenker AT (Österreich)
|-
| SHD || Schenker
|-
| SHS || Schenker SE (Schweden)
|-
| SND || Sending
|-
| SES || Seven Senders (7senders)
|-
| SPR || SPRING
|-
| TDN || TDN
|-
| TRM || Tiramizoo
|-
| TMP || TMParcel
|-
| TNI || TNT IT (Italien)
|-
| TNF || TNT FR (Frankreich)
|-
| TNN || TNT Post NL (Niederlande)
|-
| TBN || TNT NL - Retoure Belgien
|-
| TNT || TNT (Deutschland)
|-
| TOH || TOF HU (Ungarn)
|-
| TPN || TPN
|-
| 0 || 0
|-
| UPG || UPS GG (Gefahrgut PreAvis)
|-
| UPP || UPS Paperless Document
|-
| UPA || UPS Pickup (Abholung)
|-
| UPA || UPS Pickup (Abholung)
|-
| UPT || UPS Tarifierung
|-
| VNP || Venipak
|-
| WYF || Wayfair
|}

Interfaces: Security Levels and Authentication

2026-03-23T12:41:27Z

Odelice:

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)<br>
'''As of DGS version 3.8.41, the certificate can also be imported into DGS as a PFX file – the certificate and the private key are extracted from the PFX in the process. Please make sure that, if present, the certificate chain is fully included in the certificate (or PFX) (if required by the client).'''<br><br>
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.44''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."

To request the initial tokens we offer multiple options.

You can either request the tokens via Authorization Basic, in which the ClientID + ClientSecret are exposed in the HTTP header.<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>

Another option is to request the tokens via JWT. In this option the ClientID is within the payload and the JWT is signed with the ClientSecret. This option offers additional securities, since the ClientSecret itself is never exposed.<div class="toccolours mw-collapsible mw-collapsed"><div>'''Example of token request (generating access and refresh tokens with JWT)'''</div><div class="mw-collapsible-content">
For the token request via JWT (jwt-bearer) the ClientID is within the payload as ''sub'' and signed with ClientSecret. The JWT must be transmitted in the HTTP header ''client_assertion''. To use JWT authentification the HTTP header ''client_assertion_type'' with value ''jwt-bearer''.

Additionally, the '''grant_type''' with the value ''client_credentials'' is necessary for this function.

In this example following '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - was used.

Following '''ClientSecret''' was used - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight></div></div><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br>

==Managing Client Credentials in the DGS==
The client credentials are managed in the DataGatewayServer. You can create new credentials or delete existing ones.<br>
To do this, start the Credentials Configurator (.exe) located in the installation directory of the DataGatewayServer.
===Config===
[[File:Authorization Credentials 001.png|thumb|right|Credentials Configurator - config]]
On this screen, general configurations can be made.
* '''check invalid logins'''<br>If this option is active, the number of invalid authentication attempts will be counted. After '''max invalid logins''' within '''timespan in seconds''', all credentials will be locked.
* '''execute CODE RED for OAuth2.0 CC'''<br>If this option is active when using OAuth2.0 CC, a '''CODE RED''' will be triggered if a REFRESH TOKEN is reused multiple times. This action deactivates all ACCESS and REFRESH TOKENS, requiring new tokens to be requested via client credentials. Additionally, the DGS Configurator can be configured to send an email notification in the event of a CODE RED.
* '''Lock Credentials / Unlock Credentials'''<br>With this button, all credentials can be locked or unlocked. For instance, if all client credentials were locked due to the '''check invalid logins''' option, they can be unlocked here. This action takes effect immediately without needing to save.
* Save<br>This button persistently saves the settings and credentials. The options and credentials only become active after saving. A DGS restart is not required.
===Managing Credentials===
[[File:Authorization Credentials 002.png|thumb|right|Credentials Configurator - OAuth2.0 CC]]
[[File:Authorization Credentials 003.png|thumb|right|Enter Username / ClientID]]
[[File:Authorization Credentials 004.png|thumb|right|Show Credentials Dialog]]
To manage your credentials, select the appropriate tab for the authentication method configured in the DGS (e.g., OAuth2.0 CC).
* '''add'''<br>create new credentials. Note that the password or client secret will only be displayed once in a dialog. Be sure to copy it to a secure location and ensure no unauthorized persons have access to it.
* '''change secret''' or '''change password'''<br>assign a new password or client secret. As with the add function, the password or client secret will only be displayed once in a dialog.
* '''remove'''<br>remove the selected credentials.

Schnittstellen: Security Levels und Authentifizierung

2026-03-23T12:38:21Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>

'''Ab DGS Version 3.8.41, kann das Zertifikat auch als PFX ins DGS importiert werden - das Zertifikat und der Private-Key werden dabei aus dem PFX extrahiert. Bitte stellen Sie sicher, dass falls vorhanden die Zertifikatskette vollständig im Zertifikat (bzw. PFX) hinterlegt ist (wenn der Client dies erfordert)'''<br><br>
Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.44''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>Bei der initialen Tokenanfrage stehen verschiedene zwei Möglichkeiten zum Abrufen bereit.

Zum einen kann man die Token über die Authorization Basic anfragen, bei welchem die ClientID + ClientSecret im HTTP-Header mitgegeben werden.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>Eine weitere Variante die Token abzurufen ist über einen JWT. Bei dieser Methode wird die ClientID im Payload vom JWT übermittelt und das JWT selbst mit dem ClientSecret signiert. Diese Möglichkeit bietet eine zusätzliche Sicherheit, da dass ClientSecret selbst nie exposed wird.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken über JWT generieren)</div>
<div class="mw-collapsible-content">
Bei der Token-Anfrage '''JWT (jwt-bearer)''' muss die Client-ID und das Client-Secret in einem JWT übermittelt werden. Dabei wird die '''ClientID''' im JWT Payload als "sub" übermittelt und mit dem ClientSecret signiert. Das JWT wird Im HTTP-Header als ''client_assertion'' übermittelt. Die Anfrage über das JWT erfolgt über den HTTP-Header ''client_assertion_type''.

Zusätzlich ist für diese Funktion der '''grant_type''' mit dem Wert ''client_credentials'' notwendig.

In diesem Beispiel wurde die '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - verwendet.

Das '''ClientSecret''' lautet - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br>

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können Sie die die ausgewählten Credentials entfernen.

HVS32 Automatik-Polling Funktionen

2025-12-05T14:42:28Z

Odelice:

[[en:HVS32_automatic_polling_functions]]
= Datentypen =
'''Integer''' - Zahl mit ausschließlich numerischen Zeichen (0-9).<br>
'''Decimal''' - Zahl mit Nachkommastellen<br>
'''String''' - Beliebige Zeichen aus dem Zeichensatz ISO-8859-1. Maximale Länge darf nicht überschritten werden.<br>
= Zusätzliche Datentypen =
Zusätzliche Datentypen, welche in der Beschreibung vorkommen, stehen in einer 1:n Relation zu den Packstücken.
Bitte entnehmen Sie der jeweiligen Schnittstellen-Dokumentation des entsprechenden Plugins (File, JDBC, SAP, etc.), wie diese Relation realisiert werden muss.



== ArtikelDaten ==
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
|Satz-Kennung
|[[#Datentypen|String]]
|3
| -
|'''Wird nur bei Datei Verabeitung benötigt'''
Satzkennung in der Polling Datei: "ART"
|-
|'''--- ARTIKELDATEN-TEIL ---'''
|
|
|
|
|-
| ANZAHLBUEGEL || [[#Datentypen|Integer]] || - || - || Nur für Hängeversand: Anzahl der Bügel auf welche die Artikelgruppe aufgeteilt ist
|-
| ANZAHLPOSETIKETTEN || [[#Datentypen|Integer]] || - || - || Anzahl Artikeletiketten, welche gedruckt werden sollen
|-
| ARTIKELBTNNR || [[#Datentypen|String]] || 25 || - || BTN Nummer / Zolltarifnummer
|-
| ARTIKELEAN || [[#Datentypen|String]] || 20 || - || EAN Nummer
|-
| ARTIKELEINHEIT || [[#Datentypen|String]] || 10 || - || Einheit der Artikelmenge
|-
| ARTIKELGEWICHT || [[#Datentypen|Decimal]] || 9 || 3 || Gewicht des Artikels in kg
|-
| ARTIKELGRUPPE || [[#Datentypen|String]] || 50 || - || Artikelgruppe
|-
| ARTIKELMENGE || [[#Datentypen|Decimal]] || 9 || 3 || Menge des Artikels
|-
| ARTIKELSERVICES || [[#Datentypen|String]] || 100 || - || Pipe getrennte Services für diesen Artikel
|-
| ARTIKELSOLLMENGE || [[#Datentypen|Decimal]] || 9 || 3 || -
|-
| ARTIKELTEXT1 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELTEXT2 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELTEXT3 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELTEXT4 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELVOLUMEN || [[#Datentypen|Decimal]] || 9 || 3 || Volumen des Artikels
|-
| ARTIKELWAEHRUNG || [[#Datentypen|String]] || 3 || - || Währung in welcher der Wert des Artikels angegeben wird
|-
| ARTIKELWERT || [[#Datentypen|Decimal]] || 18 || 2 || Wert des Artikels
|-
| CHARGEFLAG || [[#Datentypen|String]] || 1 || - ||
|-
| KUNDENARTIKELNR || [[#Datentypen|String]] || 50 || - || Artikelnummer
|-
| KUNDENBESTELLNR || [[#Datentypen|String]] || 50 || - || Bestellnummer
|-
| POSAUFTRAGNR || [[#Datentypen|String]] || 50 || - || Auftragsnummer
|-
| POSLIEFERNR || [[#Datentypen|String]] || 40 || - || Lieferscheinnummer
|-
| POSITIONNR || [[#Datentypen|String]] || 50 || - || Laufende Nummer innerhalb des Packstücks
|-
| SERIENNR || [[#Datentypen|String]] || 30 || - || Seriennummer
|-
| URSPRUNGLAND || [[HVS32 Automatik-Polling Funktionen#Datentypen|String]] || 2 || - || Ursprungsland des Artikels
|}



== Gefahrgut ==

In der Gefahrgut Abwicklung bieten wir zwei Möglichkeiten der Abwicklung an. Zum einen können die kompletten Gefahrgutdaten ans HVS32 übermittelt werden [[HVS32 Automatik-Polling Funktionen#Gefahrgut (aus den Positionsdaten)|(aus den Positionsdaten)]].

Zum anderen gibt es die Möglichkeit, die Gefahrgutdaten ins HVS32 zu importieren und dort zu pflegen (siehe [[Verarbeitungsbeschreibung: Gefahrgut|Gefahrgutstamm]]). In diesem Fall müssen nicht alle Gefahrgutdaten ans HVS32 übermittelt werden, sondern werden aus dem im HVS32 hinterlegten Stamm ausgelesen. [[HVS32 Automatik-Polling Funktionen#Gefahrgut (über Gefahrgutstamm im HVS32)|(über Gefahrgutstamm im HVS32)]]
===Gefahrgut (aus den Positionsdaten)===
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
|Satz-Kennung
|[[#Datentypen|String]]
|3
| -
|'''Wird nur bei Datei Verabeitung benötigt'''
Satzkennung in der Polling Datei: "GEF"
|-
|'''--- GEFAHRGUTDATEN-TEIL ---'''
|
|
|
|
|-
| '''GEFAHRGUTBEFOERDKAT''' ||[[#Datentypen|Integer]] || 1 || - || Beförderungskategorie, Pflicht (siehe ADR-Tabelle Spalte (15)), kann 0-4 sein. Achtung! Muss unbedingt korrekt sein.
|-
| GEFAHRGUTBEGRENZTEMENGE || [[#Datentypen|String]] || 1 || - || T wenn der Stoff mit Status LQ / Begrenzte Menge nach ADR 3.4 verschickt wird, ansonsten F, Pflicht
|-
| '''GEFAHRGUTBEZEICHNUNG''' ||[[#Datentypen|String]] || 110 || - || Pflicht (siehe ADR-Tabelle Spalte (2))
|-
| GEFAHRGUTBUCHST640 || [[#Datentypen|String]] || 1 || - || Buchstabe für Sondervorschrift 640, bedingte Pflicht bei Stoffen, bei denen die Sondervorschrift 640 gilt (siehe ADR-Tabelle Spalte (6))
|-
| GEFAHRGUTFFCODE || [[#Datentypen|String]] ||  ||  || 
|-
| GEFAHRGUTFAKTOR || [[#Datentypen|Integer]] || 3 || - || Bewertungsfaktor für Punktesummation auf dem Beförderungspapier, (kann 0, 1, 3, 50 oder 999 sein), eigentlich Pflicht, kann aber eindeutig aus der Beförderungskategorie geschlossen werden, daher muss es nicht unbedingt belegt sein
|-
| GEFAHRGUTFREIGESTMENGE || [[#Datentypen|String]] || 1 || - || T wenn der Stoff mit Status EQ / Excepted Quantities nach ADR 3.5 verschickt wird, ansonsten F, Pflicht
|-
| GEFAHRGUTID || [[#Datentypen|String]] || 20 || - || Eindeutige Suchnummer für Gefahrgut-Stammdaten
|-
| GEFAHRGUTKCODE || [[#Datentypen|String]] || 10 || - || Klassifizierungscode, Pflicht (siehe ADR-Tabelle Spalte (3b))
|-
| '''GEFAHRGUTKLASSE''' ||[[#Datentypen|String]] || 100 || - || Pflicht (siehe ADR-Tabelle Spalte (3a))
|-
| '''GEFAHRGUTMENGE''' ||[[#Datentypen|Decimal]] || 8 || 3 || Stoff-Menge an Gefahrgut, die ADR-technisch zu deklarieren ist ( in Litern bei Flüssigkeiten und verdichteten Gasen, sonst in kg, bei LQ-Gefahrgut immer kg )
|-
| '''GEFAHRGUTMENGENEINHEIT''' ||[[#Datentypen|String]] || 2 || - || Mengeneinheit zur Stoff-Menge. ‚1‘ oder ‚l‘: Liter ; ‚0‘ oder ‚kg‘ oder leer: kg
|-
| GEFAHRGUTNEBENGEFAHR || [[#Datentypen|String]] || 10 || - || bedingte Pflicht bei Stoffen, bei denen neben der Hauptgefahr-Klasse/Zettelnummer noch Nebengefahr-Zettelnummern vorhanden sind (siehe ADR-Tabelle Spalte (5), wenn dort z.B. 3+6.1+8 eingetragen ist, sind 6.1 und 8 die Nebengefahr-Zettelnummern und als (6.1)(8) im Feld Nebengefahr zu übermitteln )
|-
| GEFAHRGUTNETTOEXPLMASSE || [[#Datentypen|Decimal]] || 8 || 3 || Netto-Explosivmasse in kg, nur bei Gefahrgütern der Klasse 1
|-
| GEFAHRGUTPOSITIONNR || [[#Datentypen|Integer]] || - || - || -
|-
| GEFAHRGUTTECHBENENNUNG || [[#Datentypen|String]] || 150 || - || bedingt Pflicht bei N.A.G. Gefahrgut (d.h. wenn die Bezeichnung mit N.A.G. endet)
|-
| GEFAHRGUTTUNNELBCODE || [[#Datentypen|String]] || 10 || - || Tunnelbeschränkungscode, Pflicht (siehe ADR-Tabelle Spalte (15))
|-
| '''GEFAHRGUTUNNR''' ||[[#Datentypen|String]] || 10 || - || Pflicht (siehe ADR-Tabelle Spalte (1))
|-
| GEFAHRGUTUMWELTGEF || [[#Datentypen|String]] || 1 || - || T wenn Stoff umweltgefährdend ist , ansonsten F, Pflicht bei umweltgefährdenden Stoffen
|-
| GEFAHRGUTVPG || [[#Datentypen|String]] || 3 || - || Verpackungsgruppe, bedingt Pflicht bei den Stoffen, bei denen diese in der ADR-Tabelle belegt ist, kann I,II oder III sein oder gar nicht belegt (letzteres z.B. bei Klasse 2)) (siehe ADR-Tabelle Spalte (4))
|-
| '''GEFAHRGUTVERPANZAHL''' ||[[#Datentypen|Integer]] || 4 || - || Anzahl der Einheiten, in denen das Gefahrgut verpackt ist (in Zusammenhang mit dem nächsten Feld GefahrgutVerpackungsart)
|-
| '''GEFAHRGUTVERPACKUNGSART''' ||[[#Datentypen|String]] || 5 || - || ADR-Code der Verpackungsart, z.B. 4G für Kiste (Pappe), Pflicht, siehe separate Doc f. Verpackungscodes
|}
===Gefahrgut (über [[Verarbeitungsbeschreibung: Gefahrgut|Gefahrgutstamm im HVS32]])===
{| class="wikitable sortable"
|-
!Feldname !!Typ!!Max Länge!! Dezimalstellen!!Belegung
|-
|'''GefahrgutID'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|String]]||20||- ||Eindeutige Suchnummer für Gefahrgut-Stammdaten
|-
|'''GefahrgutMenge'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|Decimal]]||8||3||-
|-
|'''GefahrgutVerpAnzahl'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|Integer]]||-||-||-
|-
|'''GefahrgutMengenEinheit'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|String]]||2||- ||'0' bzw Blank: Kilogramm; '1': Liter
|-
|GefahrgutNettoExplMasse ||[[HVS32 Automatik-Polling Funktionen#Datentypen|Decimal]]||8||3 ||Nur bei Klasse 1, dann aber Pflicht
|}

= Packstück-Verarbeitung (VersandDatenAnfrage) =
Die Gatewayfunktion VersandDatenAnfrage wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort ein Etikett für ein Packstück zu erzeugen und verbuchen.
Ein Etikett wird für alle weiteren Funktionen wir Storno, Verladefreigabe, etc. anhand der hostseitigen Packstück-ID identifiziert. Diese wird im Feld PackstueckID übergeben und muss dementsprechend innerhalb des Versandsystems eindeutig sein.

Durch eine zusätzliche Konfiguration im HVS32 kann die VersandDatenAnfrage auch dazu verwendet werden, um einen Nachdruck anzustoßen. Dabei muss bei der erneuten Anfrage die selbe PackstueckID verwendet werden.<br>
<br>
<big>'''Übergabe Parameter'''</big>
<br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| ANSPRECHPARTNER || [[#Datentypen|String]] || 50 || - || Empfänger Ansprechpartner
|-
| ANZAHLARTIKEL || [[#Datentypen|Integer]] || 6 || - || Anzahl Artikel (Druck auf Etikett)
|-
| [[#ArtikelDaten|ARTIKELDATEN]] || [[#Datentypen|Sequence]] '''[[#ArtikelDaten|<ArtikelDaten>]]''' || - || - || Eine Liste der [[#ArtikelDaten|Packstück-Artikel]] vom Typ '''[[#ArtikelDaten|ArtikelDaten]]''' (1:n)
|-
| AUFTRAGNR || [[#Datentypen|String]] || 20 || - || -
|-
| '''AUFTRAGGEBERID''' || [[#Datentypen|String]] || 10 || - || Mandantenkennung aus dem HVS32
|-
| AVISHINWEIS1 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISHINWEIS2 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISZUSATZ1 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 1
|-
| AVISZUSATZ2 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 2
|-
| BARCODEID || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETEXT || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETYP || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BESTELLNR || [[#Datentypen|String]] || 20 || - || Metro-Bestellnr (Metro-Versand)
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name eines Ausgabekanals (Drucker) im HVS32 über den das Etikett gedruckt wird. (Benötigt Druckerspooler Erweiterungsmodul)
|-
| EMAIL || [[#Datentypen|String]] || 100 || - || E-Mail Adresse des Empfängers (z.B.: für die Automatische E-Mail Avisierung)
|-
| EMPFMOBILFUNKNR || [[#Datentypen|String]] || 20 || - || Mobilfunknummer des Empfängers
|-
| FAXNR || [[#Datentypen|String]] || 20 || - || Faxnummer des Empfängers
|-
| FLEXZUSTELLUNGEMAILADRESSE || [[#Datentypen|String]] || 80 || - || Flex-Zustellung Emailadresse
|-
| FRACHTBRIEF || [[#Datentypen|String]] || 20 || - || Frachtbrief Nummer falls Frachtbrief durch Vorsystem gedruckt werden soll
|-
| FRACHTFUEHRERKDNR || [[#Datentypen|String]] || 10 || - || Kundennummer des Frachtzahlers beim Frachtführer
|-
| FRANKATURKENNUNG || [[#Datentypen|String]] || 10 || - || -
|-
| [[#Gefahrgut|GEFAHRGUT]] || [[#Datentypen|Sequence]] '''[[#Gefahrgut|<Gefahrgut>]]''' || - || - || Eine Liste der [[#Gefahrgut|Gefahrgüter]] vom Typ '''[[#Gefahrgut|Gefahrgut]]''' (1:n)
|-
| '''GEWICHT''' ||[[#Datentypen|Decimal]] || 8 || 3 || Bruttogewicht in KG
|-
| HOSTTRACKINGNR || [[#Datentypen|String]] || 35 || - || Paketnummer aus dem Hostsystem
|-
| ILNNR || [[#Datentypen|String]] || 20 || - || ILN des Empfängers (Pflicht bei Metro-Versand)
|-
| KOSTENSTELLE || [[#Datentypen|String]] || 30 || - || -
|-
| KUNDENNR || [[#Datentypen|String]] || 20 || - || Kundennummer des Empfängers beim Versender
|-
| LAGERKENNZEICHEN || [[#Datentypen|Integer]] || - || - || -
|-
| LETZTESPACKSTUECK || [[#Datentypen|String]] || 1 || - || T/F: T=letztes Packstüeck der Sendung (wird bei Hängeversand zum Drucken der Sendungs-Hängekarte benötigt)
|-
| LIEFERANTENID || [[#Datentypen|Integer]] || - || - || -
|-
| '''LIEFERSCHEINNR''' || [[#Datentypen|String]] || 40 || - || Wird im HVS32 als Such-Nummer verwendet
|-
| NACHNAHME || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| NETTOGEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Nettogewicht in KG
|-
| NEUTBIC || [[#Datentypen|String]] || 11 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTBANKBEZEICHNUNG || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTIBAN || [[#Datentypen|String]] || 31 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTKONTOINHABER || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERLKZ || [[#Datentypen|String]] || 3 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME1 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME2 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME3 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERORT || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERPLZ || [[#Datentypen|String]] || 10 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERSTRASSE || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NNVERMERK || [[#Datentypen|String]] || 1 || - || 'B': Bar / 'V': Verrechnungsscheck
|-
| NNVERWENDUNG || [[#Datentypen|String]] || 30 || - || Nachnahme Verwendungszweck
|-
| NNWAEHRUNG || [[#Datentypen|String]] || 3 || - || Nachnahme - ISO-Währungscode
|-
| '''PACKSTKGES''' || [[#Datentypen|Integer]] || - || - || Gesamt-Anzahl Colli der Sendung
|-
| '''PACKSTKNR''' || [[#Datentypen|Integer]] || - || - || Laufende Nr pro Sendung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| PACKSTUECKBREITE || [[#Datentypen|Integer]] || - || - || Breite in cm
|-
| PACKSTUECKHOEHE || [[#Datentypen|Integer]] || - || - || Höhe in cm
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || Eindeutige Nummer für das Paket im Vorsystem. Wird als eindeutige Paketreferenz benötigt um das Etikett später zu stornieren oder zu Verladen.
|-
| PACKSTUECKLAENGE || [[#Datentypen|Integer]] || - || - || Länge in cm
|-
| PAPERLESSINVOICE || [[#Datentypen|String]] || 1 || - || Nur im UPS PaperlessInvoice Fall (T=PaperlessInvoice / F=nicht PaperlessInvoice)
|-
| POSTLEITCODE || [[#Datentypen|String]] || 15 || - || -
|-
| POSTZIELFRACHTZENT || [[#Datentypen|String]] || 5 || - || -
|-
| RECHNUNGSEMPFLKZ || [[#Datentypen|String]] || 5 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFNAME1 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME2 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME3 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFORT || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFPLZ || [[#Datentypen|String]] || 10 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFSTRASSE || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSNR || [[#Datentypen|String]] || 20 || - || Rechnungsnummer
|-
| SENDUNGSINHALT || [[#Datentypen|String]] || 30 || - || -
|-
| SONDERDIENSTE || [[#Datentypen|String]] || 30 || - || Versandart-spezifisch belegt
|-
| SPERRFLAG || [[#Datentypen|String]] || 1 || - || T/F: T=Sperren, sonst nicht sperren
|-
| TELEFONNR || [[#Datentypen|String]] || 20 || - || Telefonnummer des Empfängers
|-
| TERMINART || [[#Datentypen|String]] || 1 || - || 'A' = ab diesem Tag liefern
'B' = bis zu diesem Tag liefern

'F' = an diesem Tag liefern
|-
| TERMINDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| TERMINZEIT || [[#Datentypen|Calendar]] || 5 || - || HH:MM
|-
| USTIDNR || [[#Datentypen|String]] || 20 || - || UmsatzsteuerNr des Empfängers
|-
| VERPACKUNGSART || [[#Datentypen|String]] || 6 || - || -
|-
| '''VERSANDARTID''' || [[#Datentypen|String]] || 10 || - || Versandartkennung aus dem HVS32
|-
| VERSICHERUNGSWERT || [[#Datentypen|Decimal]] || 18 || 2 || Höhe Versicherungswert
|-
| VORPACKDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| VWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Versicherungswert - ISO-Währungscode
|-
| WARENWERT || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke, die diesem Packstück zugewiesen wird
|-
| WWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Warenwert - ISO-Währungscode
|-
| ZAHLUNGSBEDINGUNG || [[#Datentypen|String]] || 10 || - || 'S' = Sender, 'R' = Empfänger
|-
| ZBZOLL || [[#Datentypen|String]] || 1 || - || Zahlungsbedingung für Zoll Steuern 'S' = Sender, 'R' = Empfänger
|-
| ZIELADRBAHNHOF || [[#Datentypen|String]] || 30 || - || PLZ und Ort
|-
| '''ZIELADRLKZ''' || [[#Datentypen|String]] || 5 || - || Lieferadresse
|-
| '''ZIELADRNAME1''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME2 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME3 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME4 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRORT''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRPLZ''' || [[#Datentypen|String]] || 10 || - || Lieferadresse
|-
| ZIELADRREGION || [[#Datentypen|String]] || 20 || - || Staat/Provinz (z.B.: für Sendungen in die USA wichtig)
|-
| '''ZIELADRSTRASSE''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|}

<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung|
|-
| AUSGANGDATETIME || [[#Datentypen|String]] || 10 || - || Datum, wann das Etikett an den Frachtführer übermittelt worden ist (TT.MM.JJJJ)
|-
| DRUCKDATETIME || [[#Datentypen|String]] || 19 || - || Datum, wann das Etikett im HVS32 gedruckt worden ist (TT.MM.JJJJ HH:mm:SS)
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 wenn Erfolgreich
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| GEBUEHR || [[#Datentypen|Decimal]] || 18 || 2 || Frachtkosten
|-
| GEBUEHRWAEHRUNG || [[#Datentypen|String]] || 3 || - || Frachkosten ISO-Währungscode
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || PackstueckID aus der Anfrage
|-
| RETOURTRACKINGNR || [[#Datentypen|String]] || 50 || - || Paketnummer für die Retoure
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || Paketnummer
|-
| TRACKINGURL || [[#Datentypen|String]] || 255 || - || URL des Trackinglinks zur Sendungsverfolgung
|-
| VERSANDSENDUNGSNR || [[#Datentypen|String]] || - || - || -
|}

= Etikett nachdrucken (VersandDatenWdhDruck) =
Die Gatewayfunktion VersandDatenWdhDruck wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort ein Etikett für ein Packstück nachzudrucken.
Ein Etikett wird anhand der hostseitigen Packstück-ID nachgedruckt. Diese wird im Feld PackstueckID übergeben.
Bei manchen Frachtführern (z.B. DPD) werden beim Nachdruck neue Trackingnummern vergeben. Somit ist die alte Trackingnummer nicht mehr gültig und das alte Versandetikett muss vernichtet werden.
Die neue Trackingnummer kann in der Rückmeldung zurückgemeldet werden.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || '''Eindeutige''' Nummer für das Paket im Vorsystem.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Ausgabekanal, an welchem das Etikett nachgedruckt werden soll (benötigt HVS32 Erweiterungsmodul "Druckerspooler")
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || (neue) TrackingNr des Packstücks
|}

= Packstück stornieren (StornoVersandDaten) =
Die Gatewayfunktion StornoVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort bestehende Packstücke zu stornieren, die noch nicht auf einer Ausgangsliste sind.
In der Regel wird ein Packstück anhand der hostseitigen Packstück-ID storniert. Diese wird im Feld PackstueckID übergeben.
Zusätzlich zur hostseitigen Packstück-ID kann auch die TrackingNr zur Identifikation des Packstücks beitragen, für den Fall, dass die hostseitige Packstück-ID keine Eindeutigkeit garantieren kann.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Storno wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || '''Eindeutige''' Nummer für das Paket im Vorsystem.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Packstück verladen/freigeben (VerladeVersandDaten) =
Die Gatewayfunktion VerladeVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort Packstücke für den Ausgang frei zu geben.
Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Tagesabschluss berücksichtigt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreicher Freigabe wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || '''Eindeutige''' Nummer für das Paket im Vorsystem.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| SPERRKENNZEICHEN || [[#Datentypen|String]] || 1 || - || "J" wenn das Packstück gesperrt werden soll
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke auf welche das Packstück gebucht werden soll
|-
| SAMMELFREIGABE || [[#Datentypen|String]] || 1 || - || "T" bei einer Sammel-Freigabe (Alle Packstücke mit identischer VE-ReferenzNr freigeben)
|-
| VEREFERENZNR || [[#Datentypen|String]] || 20 || - || muss bei einer Sammel-Freigabe gefüllt sein
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Tagesabschluss (Tagesabschluss) =
Das Gateway sendet die Tagesabschluss-Anfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit ein Tagesabschluss anhand der zusätzlich übergebenen Parameter ausgelöst.
Der Tagesabschluss setzt sich aus den Punkten Ausgangsliste erzeugen und Frachtführer DFÜ erzeugen zusammen.
Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Tagesabschluss berücksichtigt. Standardmäßig sind alle Packstücke freigegeben, außer sie wurden durch das Erweiterungsmodul Ausgangsscannung gesperrt.
Die Rückmeldung im HVS32 findet nach dem Ausführen des Tagesabschluss statt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Tagesabschluss wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Tagesabschluss ausführen soll.
|-
| FRACHTFUEHRERTYPLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Frachführern mitgegeben werden. Es können n-Frachtführer abgeschlossen werden.
(Option MultiFFTagesabschluss muss im HVS32 aktiv sein)
|-
| AUFTRAGGEBERIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Auftraggebern mitgegeben werden. Es können n-Auftraggeber abgeschlossen werden.
(Option MultiAGTagesabschluss muss im HVS32 aktiv sein)
|-
| VERSANDARTIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Versandarten mitgegeben werden. Es können n-Versandarten abgeschlossen werden.
(Option MultiVATagesabschluss muss im HVS32 aktiv sein)
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Kennzeichen der abzuschließenden Wechselbrücke. Hiermit können nur bestimmte Sendungen abgeschlossen werden.
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name des Ausgabekanals auf welchem die Liste gedruckt werden soll
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Ausgangsliste erzeugen (Listenabschluss) =
Das Gateway sendet die Listenabschluss-Anfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit eine Ausgangsliste anhand der zusätzlich übergebenen Parameter erzeugt.
Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Listenabschluss berücksichtigt. Standardmäßig sind alle Packstücke freigegeben, außer sie wurden durch das Erweiterungsmodul Ausgangsscannung gesperrt.
Die Rückmeldung im HVS32 findet nach dem Erzeugen der Ausgangsliste statt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Listenabschluss wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Tagesabschluss ausführen soll.
|-
| FRACHTFUEHRERTYPLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Frachführern mitgegeben werden. Es können n-Frachtführer abgeschlossen werden.
(Option MultiFFTagesabschluss muss im HVS32 aktiv sein)
|-
| AUFTRAGGEBERIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Auftraggebern mitgegeben werden. Es können n-Auftraggeber abgeschlossen werden.
(Option MultiAGTagesabschluss muss im HVS32 aktiv sein)
|-
| VERSANDARTIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Versandarten mitgegeben werden. Es können n-Versandarten abgeschlossen werden.
(Option MultiVATagesabschluss muss im HVS32 aktiv sein)
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Kennzeichen der abzuschließenden Wechselbrücke. Hiermit können nur bestimmte Sendungen abgeschlossen werden.
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name des Ausgabekanals auf welchem die Liste gedruckt werden soll
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Frachtführer DFÜ erzeugen (EDIAbschluss) =
Das Gateway sendet die EDIAbschluss-Anfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit eine Frachtführer DFÜ anhand der zusätzlich übergebenen Parameter erzeugt und (falls konfiguriert) an den Frachtführer übertragen.
Nur Packstücke, für welche zuvor eine Ausgangsliste erzeugt wurde, werden für eine Frachtführer DFÜ berücksichtigt.
Die Rückmeldung im HVS32 findet nach dem Erzeugen der Frachtführer DFÜ statt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem EDIAbschluss wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Tagesabschluss ausführen soll.
|-
| FRACHTFUEHRERTYPLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Frachführern mitgegeben werden. Es können n-Frachtführer abgeschlossen werden.
(Option MultiFFTagesabschluss muss im HVS32 aktiv sein)
|-
| AUFTRAGGEBERIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Auftraggebern mitgegeben werden. Es können n-Auftraggeber abgeschlossen werden.
(Option MultiAGTagesabschluss muss im HVS32 aktiv sein)
|-
| VERSANDARTIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Versandarten mitgegeben werden. Es können n-Versandarten abgeschlossen werden.
(Option MultiVATagesabschluss muss im HVS32 aktiv sein)
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Kennzeichen der abzuschließenden Wechselbrücke. Hiermit können nur bestimmte Sendungen abgeschlossen werden.
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Packstückdaten prüfen (VersandDatenPruefAnfrage) =
Das Gateway sendet die VersandDatenPruefAnfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit eine VersandDatenAnfrage simuliert.
Dabei werden keine Etiketten gedruckt und das Packstück bzw. das Etikett wird nicht verbucht, jedoch sind alle weiteren Prozesse identisch zur VersandDatenAnfrage (Routenermittlung, Trackingnummer-Ermittlung, Adressprüfung, etc.)
Diese Funktion dient dazu im Vorfeld alle Versand-Daten zu validieren.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| ANSPRECHPARTNER || [[#Datentypen|String]] || 50 || - || Empfänger Ansprechpartner
|-
| ANZAHLARTIKEL || [[#Datentypen|Integer]] || 6 || - || Anzahl Artikel (Druck auf Etikett)
|-
| [[#ArtikelDaten|ARTIKELDATEN]] || [[#Datentypen|Sequence]] '''[[#ArtikelDaten|<ArtikelDaten>]]''' || - || - || Eine Liste der [[#ArtikelDaten|Packstück-Artikel]] vom Typ '''[[#ArtikelDaten|ArtikelDaten]]''' (1:n)
|-
| AUFTRAGNR || [[#Datentypen|String]] || 20 || - || -
|-
| '''AUFTRAGGEBERID''' || [[#Datentypen|String]] || 10 || - || Mandantenkennung aus dem HVS32
|-
| AVISHINWEIS1 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISHINWEIS2 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISZUSATZ1 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 1
|-
| AVISZUSATZ2 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 2
|-
| BARCODEID || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETEXT || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETYP || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BESTELLNR || [[#Datentypen|String]] || 20 || - || Metro-Bestellnr (Metro-Versand)
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name eines Ausgabekanals (Drucker) im HVS32 über den das Etikett gedruckt wird. (Benötigt Druckerspooler Erweiterungsmodul)
|-
| EMAIL || [[#Datentypen|String]] || 100 || - || E-Mail Adresse des Empfängers (z.B.: für die Automatische E-Mail Avisierung)
|-
| EMPFMOBILFUNKNR || [[#Datentypen|String]] || 20 || - || Mobilfunknummer des Empfängers
|-
| FAXNR || [[#Datentypen|String]] || 20 || - || Faxnummer des Empfängers
|-
| FLEXZUSTELLUNGEMAILADRESSE || [[#Datentypen|String]] || 80 || - || Flex-Zustellung Emailadresse
|-
| FRACHTBRIEF || [[#Datentypen|String]] || 20 || - || Frachtbrief Nummer falls Frachtbrief durch Vorsystem gedruckt werden soll
|-
| FRACHTFUEHRERKDNR || [[#Datentypen|String]] || 10 || - || Kundennummer des Frachtzahlers beim Frachtführer
|-
| FRANKATURKENNUNG || [[#Datentypen|String]] || 10 || - || -
|-
| [[#Gefahrgut|GEFAHRGUT]] || [[#Datentypen|Sequence]] '''[[#Gefahrgut|<Gefahrgut>]]''' || - || - || Eine Liste der [[#Gefahrgut|Gefahrgüter]] vom Typ '''[[#Gefahrgut|Gefahrgut]]''' (1:n)
|-
| '''GEWICHT''' ||[[#Datentypen|Decimal]] || 8 || 3 || Bruttogewicht in KG
|-
| HOSTTRACKINGNR || [[#Datentypen|String]] || 35 || - || Paketnummer aus dem Hostsystem
|-
| ILNNR || [[#Datentypen|String]] || 20 || - || ILN des Empfängers (Pflicht bei Metro-Versand)
|-
| KOSTENSTELLE || [[#Datentypen|String]] || 30 || - || -
|-
| KUNDENNR || [[#Datentypen|String]] || 20 || - || Kundennummer des Empfängers beim Versender
|-
| LAGERKENNZEICHEN || [[#Datentypen|Integer]] || - || - || -
|-
| LETZTESPACKSTUECK || [[#Datentypen|String]] || 1 || - || T/F: T=letztes Packstüeck der Sendung (wird bei Hängeversand zum Drucken der Sendungs-Hängekarte benötigt)
|-
| LIEFERANTENID || [[#Datentypen|Integer]] || - || - || -
|-
| '''LIEFERSCHEINNR''' || [[#Datentypen|String]] || 40 || - || Wird im HVS32 als Such-Nummer verwendet
|-
| NACHNAHME || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| NETTOGEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Nettogewicht in KG
|-
| NEUTBIC || [[#Datentypen|String]] || 11 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTBANKBEZEICHNUNG || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTIBAN || [[#Datentypen|String]] || 31 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTKONTOINHABER || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERLKZ || [[#Datentypen|String]] || 3 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME1 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME2 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME3 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERORT || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERPLZ || [[#Datentypen|String]] || 10 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERSTRASSE || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NNVERMERK || [[#Datentypen|String]] || 1 || - || B': Bar / 'V': Verrechnungsscheck
|-
| NNVERWENDUNG || [[#Datentypen|String]] || 30 || - || Nachnahme Verwendungszweck
|-
| NNWAEHRUNG || [[#Datentypen|String]] || 3 || - || Nachnahme - ISO-Währungscode
|-
| '''PACKSTKGES''' || [[#Datentypen|Integer]] || - || - || Gesamt-Anzahl Colli der Sendung
|-
| '''PACKSTKNR''' || [[#Datentypen|Integer]] || - || - || Laufende Nr pro Sendung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeten soll.
|-
| PACKSTUECKBREITE || [[#Datentypen|Integer]] || - || - || Breite in cm
|-
| PACKSTUECKHOEHE || [[#Datentypen|Integer]] || - || - || Höhe in cm
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Nummer für das Paket im Vorsystem. Wird als eindeutige Paketreferenz benötigt um das Etikett später zu stornieren oder zu Verladen.
|-
| PACKSTUECKLAENGE || [[#Datentypen|Integer]] || - || - || Länge in cm
|-
| PAPERLESSINVOICE || [[#Datentypen|String]] || 1 || - || Nur im UPS PaperlessInvoice Fall (T=PaperlessInvoice / F=nicht PaperlessInvoice)
|-
| POSTLEITCODE || [[#Datentypen|String]] || 15 || - || -
|-
| POSTZIELFRACHTZENT || [[#Datentypen|String]] || 5 || - || -
|-
| RECHNUNGSEMPFLKZ || [[#Datentypen|String]] || 5 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFNAME1 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME2 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME3 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFORT || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFPLZ || [[#Datentypen|String]] || 10 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFSTRASSE || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSNR || [[#Datentypen|String]] || 20 || - || Rechnungsnummer
|-
| SENDUNGSINHALT || [[#Datentypen|String]] || 30 || - || -
|-
| SONDERDIENSTE || [[#Datentypen|String]] || 30 || - || Versandart-spezifisch belegt
|-
| SPERRFLAG || [[#Datentypen|String]] || 1 || - || T/F: T=Sperren, sonst nicht sperren
|-
| TELEFONNR || [[#Datentypen|String]] || 20 || - || Telefonnummer des Empfängers
|-
| TERMINART || [[#Datentypen|String]] || 1 || - || 'A'b / 'B'is / 'F'ix
|-
| TERMINDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| TERMINZEIT || [[#Datentypen|Calendar]] || 5 || - || HH:MM
|-
| USTIDNR || [[#Datentypen|String]] || 20 || - || UmsatzsteuerNr des Empfängers
|-
| VERPACKUNGSART || [[#Datentypen|String]] || 6 || - || -
|-
| '''VERSANDARTID''' || [[#Datentypen|String]] || 10 || - || Versandartkennung aus dem HVS32
|-
| VERSICHERUNGSWERT || [[#Datentypen|Decimal]] || 18 || 2 || Höhe Versicherungswert
|-
| VORPACKDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| VWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Versicherungswert - ISO-Währungscode
|-
| WARENWERT || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke, die diesem Packstück zugewiesen wird
|-
| WWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Warenwert - ISO-Währungscode
|-
| ZAHLUNGSBEDINGUNG || [[#Datentypen|String]] || 10 || - || 'S' = Sender, 'R' = Empfänger
|-
| ZBZOLL || [[#Datentypen|String]] || 1 || - || Zahlungsbedingung für Zoll Steuern 'S' = Sender, 'R' = Empfänger
|-
| ZIELADRBAHNHOF || [[#Datentypen|String]] || 30 || - || PLZ und Ort
|-
| '''ZIELADRLKZ''' || [[#Datentypen|String]] || 5 || - || Lieferadresse
|-
| '''ZIELADRNAME1''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME2 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME3 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME4 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRORT''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRPLZ''' || [[#Datentypen|String]] || 10 || - || Lieferadresse
|-
| ZIELADRREGION || [[#Datentypen|String]] || 20 || - || Staat/Provinz (z.B.: für Sendungen in die USA wichtig)
|-
| '''ZIELADRSTRASSE''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|}

<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung|
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 wenn Erfolgreich
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| GEBUEHR || [[#Datentypen|Decimal]] || 18 || 2 || Frachtkosten
|-
| GEBUEHRWAEHRUNG || [[#Datentypen|String]] || 3 || - || Frachkosten ISO-Währungscode
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || PackstueckID aus der Anfrage
|}

= Packstückdaten aktualisieren (UpdateVersandDaten) =
Die Gatewayfunktion UpdateVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort die Daten von bestehende Packstücken zu verändern.
Diese Anfrage wird zum Beispiel gesendet, wenn der Warenwert für ein Packstück erst zu einem späteren Zeitpunkt bekannt ist.
Aktualisiert werden können Daten innerhalb der Tabellen Versandeinheit, Abrechnungseinheit und Lieferung. Dabei wird stets über das Feld PackstueckID und bei Belegung auch über das Feld TrackingNr gesucht.
<br><br>
'''Bei dieser Anfrage werden allerdings die zu aktualisierenden Felder und Inhalte nicht mehr nach den Richtlinien des Frachtführers geprüft (z.B. Gewichtsgrenzen, etc.). Es muss somit vom Vorsystem sichergestellt werden, dass die aktualisierenden Werte mit den Richtlinien des Frachtführers übereinstimmen. Sollte dies nicht möglich sein, kann diese Funktion nicht genutzt werden, sondern das Etikett muss storniert und neu verarbeitet werden. Außerdem können Felder, welche bereits auf einem Etikett angedruckt oder vom Versandsystem HVS32 in einer Frachtführerabwicklung ermittelt wurden (z.B. Adresse, Route, TrackingNr, Sonderdienste, etc.) nicht manipuliert werden.'''<br><br>

'''ACHTUNG: Alle Felder, welche im Versandsystem aktualisiert werden sollen, müssen vor der Nutzung dieser Funktion abgestimmt und im Versandsystem entsprechend konfiguriert werden!'''<br><br>
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Update wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || Eindeutige Nummer für das Paket im Vorsystem. Wird als eindeutige Paketreferenz benötigt um den Datensatz zu identifizieren.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| ANSPRECHPARTNER || [[#Datentypen|String]] || 50 || - || Empfänger Ansprechpartner
|-
| AVISHINWEIS1 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISHINWEIS2 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISZUSATZ1 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 1
|-
| AVISZUSATZ2 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 2
|-
| BESTELLNR || [[#Datentypen|String]] || 20 || - || Metro-Bestellnr (Metro-Versand)
|-
| EMAIL || [[#Datentypen|String]] || 100 || - || E-Mail Adresse des Empfängers (z.B.: für die Automatische E-Mail Avisierung)
|-
| EMPFMOBILFUNKNR || [[#Datentypen|String]] || 20 || - || Mobilfunknummer des Empfängers
|-
| FAXNR || [[#Datentypen|String]] || 20 || - || Faxnummer des Empfängers
|-
| FLEXZUSTELLUNGEMAILADRESSE || [[#Datentypen|String]] || 80 || - || Flex-Zustellung Emailadresse
|-
| GEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Bruttogewicht in KG
|-
| NETTOGEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Nettogewicht in KG
|-
| ILNNR || [[#Datentypen|String]] || 20 || - || ILN des Empfängers (Pflicht bei Metro-Versand)
|-
| KOSTENSTELLE || [[#Datentypen|String]] || 30 || - || -
|-
| LIEFERANTENID || [[#Datentypen|Integer]] || - || - || -
|-
| NACHNAHME || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| NNVERMERK || [[#Datentypen|String]] || 1 || - || B': Bar / 'V': Verrechnungsscheck
|-
| NNVERWENDUNG || [[#Datentypen|String]] || 30 || - || Nachnahme Verwendungszweck
|-
| NNWAEHRUNG || [[#Datentypen|String]] || 3 || - || Nachnahme - ISO-Währungscode
|-
| PACKSTUECKBREITE || [[#Datentypen|Integer]] || - || - || Breite in cm
|-
| PACKSTUECKHOEHE || [[#Datentypen|Integer]] || - || - || Höhe in cm
|-
| PACKSTUECKLAENGE || [[#Datentypen|Integer]] || - || - || Länge in cm
|-
| RECHNUNGSEMPFLKZ || [[#Datentypen|String]] || 5 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFNAME1 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME2 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME3 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFORT || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFPLZ || [[#Datentypen|String]] || 10 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFSTRASSE || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSNR || [[#Datentypen|String]] || 20 || - || Rechnungsnummer
|-
| SENDUNGSINHALT || [[#Datentypen|String]] || 30 || - || -
|-
| TELEFONNR || [[#Datentypen|String]] || 20 || - || Telefonnummer des Empfängers
|-
| VORPACKDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| VERSICHERUNGSWERT || [[#Datentypen|Decimal]] || 18 || 2 || Höhe Versicherungswert
|-
| VWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Versicherungswert - ISO-Währungscode
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke, die diesem Packstück zugewiesen wird
|-
| WARENWERT || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| WWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Warenwert - ISO-Währungscode
|}

<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Packstückdaten anonymisieren (AnonymisiereVersandDaten) =
Das Gateway sendet die AnonymisiereVersandDaten an das Automatik-Polling des HVS32. Im HVS32 werden somit Kunden bezogene Daten für den entsprechenden Datensatz gemäß DSGVO anonymisiert.
Diese Anonymisierung wird unwiderruflich und endgültig auf der Datenbankebene des Versandsystems durchgeführt. Eine Wiederherstellung der ursprünglichen Daten ist somit nicht mehr möglich.
Log-Dateien, Rückmelde-Dateien, bereits übertragene Frachtführer DFÜs etc. sind hiervon nicht betroffen. Es können ausschließlich Packstücke und Sendungen anonymisiert werden, welche bereits Tages abgeschlossen sind.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || PackstückID des Packstücks, welches anonymisiert werden soll.
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || TrackingNr des Packstücks, welches anonymisiert werden soll.
|-
| LIEFERSCHEINNR || [[#Datentypen|String]] || 40 || - || LieferscheinNr der Sendung, welche anonymisiert werden soll.
|-
| AUFTRAGSNR || [[#Datentypen|String]] || 50 || - || AuftragsNr der Sendung, welche anonymisiert werden soll.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der die Anonymisierung verarbeiten soll.
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Statusdaten für ein Packstück abrufen (StatusDatenAnfrage) =
Das Gateway sendet die StatusDatenAnfrage an das Automatik-Polling des HVS32. Im HVS32 werden zu diesem Packstück alle vorhandenen Statusdaten abgerufen und ans Gateway zurückgemeldet.<br>
Das Packstück wird anhand der PackstueckId, der TrackingNr oder einer kombination aus beiden (falls nur einer der beiden Referenzen nicht eundeutig ist) identifiziert.<br><br>
Werden im HVS32 zu der Referenz mehrere Packstücke identifiziert, so wird immer das aktuellste Packstück verwendet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Packstueck-Id aus dem Hostsystem, welches das Packstück identifiziert.
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || TrackingNr des Packstuecks.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, welcher die Anfrage verarbeiten soll (Optional).
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|-
| EINTRAGDATETIME || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit, wann der Statuscode ins HVS32 importiert worden ist (Format abhängig vom Betriebssystem - DE: dd.mm.yyyy hh:mm:ss)
|-
| EINTRAGDATETIME_TIMESTAMP || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit, wann der Statuscode ins HVS32 importiert worden ist (Format: yyyy-mm-dd hh:mm:ss.SSS)
|-
| EMPFANGSQUITTIERER || [[#Datentypen|String]] || 100 || - || Name des Empfängers, der das Paket/die Sendung entgegen nahm
|-
| FEHLERSTATUS || [[#Datentypen|String]] || 2 || - || I = Info, F = Fehler
|-
| FFSTATUSCODE || [[#Datentypen|String]] || 10 || - || Frachtführerspezifischer Statuscode
|-
| FFSTATUSKLARTEXT || [[#Datentypen|String]] || 250 || - || Klartext der den Statuscode beschreibt
|-
| FFZUSATZCODE || [[#Datentypen|String]] || 10 || - || Zusätzlicher Statuscode
|-
| FFZUSATZKLARTEXT || [[#Datentypen|String]] || 120 || - || Klartext der den zusätzlichen Statuscode beschreibt
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Packstueck-Id aus dem Hostsystem, welches das Packstück identifiziert.
|-
| STATUSDATETIME || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit des Statuscodes (Format abhängig vom Betriebssystem - DE: dd.mm.yyyy hh:mm:ss)
|-
| STATUSDATETIME_TIMESTAMP || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit des Statuscodes (Format: yyyy-mm-dd hh:mm:ss.SSS)
|-
| STATUSORT || [[#Datentypen|String]] || 30 || - || Ort an dem der Status eingetreten ist (z.B. Nummer des Depots)
|-
| STATUSTYP || [[#Datentypen|String]] || 30 || - || E = Endestatus, Z = Zwischenstatus
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || Trackingnummer
|-
| ZUSATZKLARTEXT || [[#Datentypen|String]] || 80 || - || Zusätzliche Informationen
|}

= Packstückdaten abrufen (PackstueckDatenAnfrage) =
Das Gateway sendet die PackstueckDatenAnfrage an das Automatik-Polling des HVS32. Im HVS32 werden zu diesem Packstück alle vorhandenen Informationen abgerufen und ans Gateway zurückgemeldet.<br>
Das Packstück wird anhand der PackstueckId, der TrackingNr oder einer kombination aus beiden (falls nur einer der beiden Referenzen nicht eundeutig ist) identifiziert.<br><br>
Werden im HVS32 zu der Referenz mehrere Packstücke identifiziert, so wird immer das aktuellste Packstück verwendet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Packstueck-Id aus dem Hostsystem, welches das Packstück identifiziert.
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || TrackingNr des Packstuecks.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, welcher die Anfrage verarbeiten soll (Optional).
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|-
| AUSGANGDATETIME || [[#Datentypen|String]] || 10 || - || Datum, wann das Etikett an den Frachtführer übermittelt worden ist (Format abhängig vom Betriebssystem - DE: dd.mm.yyyy)
|-
| DRUCKDATETIME || [[#Datentypen|String]] || 25 || - || Datum, wann das Etikett im HVS32 gedruckt worden ist (Format abhängig vom Betriebssystem - DE: dd.mm.yyyy hh:mm:ss)
|-
| GEBUEHR || [[#Datentypen|Decimal]] || 18 || 2 || Frachtkosten vom Packstück oder der Sendung
|-
| GEBUEHRWAEHRUNG || [[#Datentypen|String]] || 3 || - || Frachkosten ISO-Währungscode
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || Paketnummer
|-
| VERSANDSENDUNGSNR || [[#Datentypen|String]] || - || - || -
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Packstueck-Id aus dem Hostsystem, welches das Packstück identifiziert.
|-
| PAKETSTATUS || [[#Datentypen|String]] || 3 || - || HVS32 code für Paketstatus
|-
| PAKETSTATUSDETAILS || [[#Datentypen|String]] || 200 || - || Beschreibung vom Paketstatus
|-
| PAKETSTATUSDETAILS_EN || [[#Datentypen|String]] || 200 || - || Englische Beschreibung vom Paketstatus
|}

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2025-12-05T14:28:32Z

Odelice:

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERCODE CHAR(1)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
</source>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die StatusDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'Z_STATUSDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)

EXPORTING
STATUSDATEN TABLE
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)
EINTRAGDATETIME CHAR(20)
EMPFANGSQUITTIERER CHAR(100)
FEHLERSTATUS CHAR(2)
FFSTATUSCODE CHAR(10)
FFSTATUSKLARTEXT CHAR(250)
FFZUSATZCODE CHAR(10)
FFZUSATZKLARTEXT CHAR(120)
STATUSDATETIME CHAR(20)
STATUSORT CHAR(30)
STATUSTYP CHAR(2)
ZUSATZKLARTEXT CHAR(80)
</source>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die PackstueckDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'Z_PACKSTUECKDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)

EXPORTING
PACKSTUECKRUECK STRUCTURE
PAKETSTATUS CHAR(3)
PAKETSTATUSDETAILS CHAR(200)
PAKETSTATUSDETAILS_EN CHAR(200)
PACKSTUECKID CHAR(20)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERCODE CHAR(1)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2025-12-05T14:23:04Z

Odelice:

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
</source>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die StatusDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'Z_STATUSDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)

EXPORTING
STATUSDATEN TABLE
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)
EINTRAGDATETIME CHAR(20)
EMPFANGSQUITTIERER CHAR(100)
FEHLERSTATUS CHAR(2)
FFSTATUSCODE CHAR(10)
FFSTATUSKLARTEXT CHAR(250)
FFZUSATZCODE CHAR(10)
FFZUSATZKLARTEXT CHAR(120)
STATUSDATETIME CHAR(20)
STATUSORT CHAR(30)
STATUSTYP CHAR(2)
ZUSATZKLARTEXT CHAR(80)
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2025-12-05T14:22:04Z

Odelice:

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
</source>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die StatusDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'Z_STATUSDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)

EXPORTING
FEHLERCODE CHAR(1)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
STATUSDATEN TABLE
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)
EINTRAGDATETIME CHAR(20)
EMPFANGSQUITTIERER CHAR(100)
FEHLERSTATUS CHAR(2)
FFSTATUSCODE CHAR(10)
FFSTATUSKLARTEXT CHAR(250)
FFZUSATZCODE CHAR(10)
FFZUSATZKLARTEXT CHAR(120)
STATUSDATETIME CHAR(20)
STATUSORT CHAR(30)
STATUSTYP CHAR(2)
ZUSATZKLARTEXT CHAR(80)
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2025-12-05T14:21:45Z

Odelice:

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
</source>
</div></div>
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die StatusDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'Z_STATUSDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)

EXPORTING
FEHLERCODE CHAR(1)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
STATUSDATEN TABLE
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)
EINTRAGDATETIME CHAR(20)
EMPFANGSQUITTIERER CHAR(100)
FEHLERSTATUS CHAR(2)
FFSTATUSCODE CHAR(10)
FFSTATUSKLARTEXT CHAR(250)
FFZUSATZCODE CHAR(10)
FFZUSATZKLARTEXT CHAR(120)
STATUSDATETIME CHAR(20)
STATUSORT CHAR(30)
STATUSTYP CHAR(2)
ZUSATZKLARTEXT CHAR(80)
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 Automatik-Polling Funktionen

2025-12-05T14:19:46Z

Odelice:

[[en:HVS32_automatic_polling_functions]]
= Datentypen =
'''Integer''' - Zahl mit ausschließlich numerischen Zeichen (0-9).<br>
'''Decimal''' - Zahl mit Nachkommastellen<br>
'''String''' - Beliebige Zeichen aus dem Zeichensatz ISO-8859-1. Maximale Länge darf nicht überschritten werden.<br>
= Zusätzliche Datentypen =
Zusätzliche Datentypen, welche in der Beschreibung vorkommen, stehen in einer 1:n Relation zu den Packstücken.
Bitte entnehmen Sie der jeweiligen Schnittstellen-Dokumentation des entsprechenden Plugins (File, JDBC, SAP, etc.), wie diese Relation realisiert werden muss.



== ArtikelDaten ==
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
|Satz-Kennung
|[[#Datentypen|String]]
|3
| -
|'''Wird nur bei Datei Verabeitung benötigt'''
Satzkennung in der Polling Datei: "ART"
|-
|'''--- ARTIKELDATEN-TEIL ---'''
|
|
|
|
|-
| ANZAHLBUEGEL || [[#Datentypen|Integer]] || - || - || Nur für Hängeversand: Anzahl der Bügel auf welche die Artikelgruppe aufgeteilt ist
|-
| ANZAHLPOSETIKETTEN || [[#Datentypen|Integer]] || - || - || Anzahl Artikeletiketten, welche gedruckt werden sollen
|-
| ARTIKELBTNNR || [[#Datentypen|String]] || 25 || - || BTN Nummer / Zolltarifnummer
|-
| ARTIKELEAN || [[#Datentypen|String]] || 20 || - || EAN Nummer
|-
| ARTIKELEINHEIT || [[#Datentypen|String]] || 10 || - || Einheit der Artikelmenge
|-
| ARTIKELGEWICHT || [[#Datentypen|Decimal]] || 9 || 3 || Gewicht des Artikels in kg
|-
| ARTIKELGRUPPE || [[#Datentypen|String]] || 50 || - || Artikelgruppe
|-
| ARTIKELMENGE || [[#Datentypen|Decimal]] || 9 || 3 || Menge des Artikels
|-
| ARTIKELSERVICES || [[#Datentypen|String]] || 100 || - || Pipe getrennte Services für diesen Artikel
|-
| ARTIKELSOLLMENGE || [[#Datentypen|Decimal]] || 9 || 3 || -
|-
| ARTIKELTEXT1 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELTEXT2 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELTEXT3 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELTEXT4 || [[#Datentypen|String]] || 100 || - || Artikelbezeichnung
|-
| ARTIKELVOLUMEN || [[#Datentypen|Decimal]] || 9 || 3 || Volumen des Artikels
|-
| ARTIKELWAEHRUNG || [[#Datentypen|String]] || 3 || - || Währung in welcher der Wert des Artikels angegeben wird
|-
| ARTIKELWERT || [[#Datentypen|Decimal]] || 18 || 2 || Wert des Artikels
|-
| CHARGEFLAG || [[#Datentypen|String]] || 1 || - ||
|-
| KUNDENARTIKELNR || [[#Datentypen|String]] || 50 || - || Artikelnummer
|-
| KUNDENBESTELLNR || [[#Datentypen|String]] || 50 || - || Bestellnummer
|-
| POSAUFTRAGNR || [[#Datentypen|String]] || 50 || - || Auftragsnummer
|-
| POSLIEFERNR || [[#Datentypen|String]] || 40 || - || Lieferscheinnummer
|-
| POSITIONNR || [[#Datentypen|String]] || 50 || - || Laufende Nummer innerhalb des Packstücks
|-
| SERIENNR || [[#Datentypen|String]] || 30 || - || Seriennummer
|-
| URSPRUNGLAND || [[HVS32 Automatik-Polling Funktionen#Datentypen|String]] || 2 || - || Ursprungsland des Artikels
|}



== Gefahrgut ==

In der Gefahrgut Abwicklung bieten wir zwei Möglichkeiten der Abwicklung an. Zum einen können die kompletten Gefahrgutdaten ans HVS32 übermittelt werden [[HVS32 Automatik-Polling Funktionen#Gefahrgut (aus den Positionsdaten)|(aus den Positionsdaten)]].

Zum anderen gibt es die Möglichkeit, die Gefahrgutdaten ins HVS32 zu importieren und dort zu pflegen (siehe [[Verarbeitungsbeschreibung: Gefahrgut|Gefahrgutstamm]]). In diesem Fall müssen nicht alle Gefahrgutdaten ans HVS32 übermittelt werden, sondern werden aus dem im HVS32 hinterlegten Stamm ausgelesen. [[HVS32 Automatik-Polling Funktionen#Gefahrgut (über Gefahrgutstamm im HVS32)|(über Gefahrgutstamm im HVS32)]]
===Gefahrgut (aus den Positionsdaten)===
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
|Satz-Kennung
|[[#Datentypen|String]]
|3
| -
|'''Wird nur bei Datei Verabeitung benötigt'''
Satzkennung in der Polling Datei: "GEF"
|-
|'''--- GEFAHRGUTDATEN-TEIL ---'''
|
|
|
|
|-
| '''GEFAHRGUTBEFOERDKAT''' ||[[#Datentypen|Integer]] || 1 || - || Beförderungskategorie, Pflicht (siehe ADR-Tabelle Spalte (15)), kann 0-4 sein. Achtung! Muss unbedingt korrekt sein.
|-
| GEFAHRGUTBEGRENZTEMENGE || [[#Datentypen|String]] || 1 || - || T wenn der Stoff mit Status LQ / Begrenzte Menge nach ADR 3.4 verschickt wird, ansonsten F, Pflicht
|-
| '''GEFAHRGUTBEZEICHNUNG''' ||[[#Datentypen|String]] || 110 || - || Pflicht (siehe ADR-Tabelle Spalte (2))
|-
| GEFAHRGUTBUCHST640 || [[#Datentypen|String]] || 1 || - || Buchstabe für Sondervorschrift 640, bedingte Pflicht bei Stoffen, bei denen die Sondervorschrift 640 gilt (siehe ADR-Tabelle Spalte (6))
|-
| GEFAHRGUTFFCODE || [[#Datentypen|String]] ||  ||  || 
|-
| GEFAHRGUTFAKTOR || [[#Datentypen|Integer]] || 3 || - || Bewertungsfaktor für Punktesummation auf dem Beförderungspapier, (kann 0, 1, 3, 50 oder 999 sein), eigentlich Pflicht, kann aber eindeutig aus der Beförderungskategorie geschlossen werden, daher muss es nicht unbedingt belegt sein
|-
| GEFAHRGUTFREIGESTMENGE || [[#Datentypen|String]] || 1 || - || T wenn der Stoff mit Status EQ / Excepted Quantities nach ADR 3.5 verschickt wird, ansonsten F, Pflicht
|-
| GEFAHRGUTID || [[#Datentypen|String]] || 20 || - || Eindeutige Suchnummer für Gefahrgut-Stammdaten
|-
| GEFAHRGUTKCODE || [[#Datentypen|String]] || 10 || - || Klassifizierungscode, Pflicht (siehe ADR-Tabelle Spalte (3b))
|-
| '''GEFAHRGUTKLASSE''' ||[[#Datentypen|String]] || 100 || - || Pflicht (siehe ADR-Tabelle Spalte (3a))
|-
| '''GEFAHRGUTMENGE''' ||[[#Datentypen|Decimal]] || 8 || 3 || Stoff-Menge an Gefahrgut, die ADR-technisch zu deklarieren ist ( in Litern bei Flüssigkeiten und verdichteten Gasen, sonst in kg, bei LQ-Gefahrgut immer kg )
|-
| '''GEFAHRGUTMENGENEINHEIT''' ||[[#Datentypen|String]] || 2 || - || Mengeneinheit zur Stoff-Menge. ‚1‘ oder ‚l‘: Liter ; ‚0‘ oder ‚kg‘ oder leer: kg
|-
| GEFAHRGUTNEBENGEFAHR || [[#Datentypen|String]] || 10 || - || bedingte Pflicht bei Stoffen, bei denen neben der Hauptgefahr-Klasse/Zettelnummer noch Nebengefahr-Zettelnummern vorhanden sind (siehe ADR-Tabelle Spalte (5), wenn dort z.B. 3+6.1+8 eingetragen ist, sind 6.1 und 8 die Nebengefahr-Zettelnummern und als (6.1)(8) im Feld Nebengefahr zu übermitteln )
|-
| GEFAHRGUTNETTOEXPLMASSE || [[#Datentypen|Decimal]] || 8 || 3 || Netto-Explosivmasse in kg, nur bei Gefahrgütern der Klasse 1
|-
| GEFAHRGUTPOSITIONNR || [[#Datentypen|Integer]] || - || - || -
|-
| GEFAHRGUTTECHBENENNUNG || [[#Datentypen|String]] || 150 || - || bedingt Pflicht bei N.A.G. Gefahrgut (d.h. wenn die Bezeichnung mit N.A.G. endet)
|-
| GEFAHRGUTTUNNELBCODE || [[#Datentypen|String]] || 10 || - || Tunnelbeschränkungscode, Pflicht (siehe ADR-Tabelle Spalte (15))
|-
| '''GEFAHRGUTUNNR''' ||[[#Datentypen|String]] || 10 || - || Pflicht (siehe ADR-Tabelle Spalte (1))
|-
| GEFAHRGUTUMWELTGEF || [[#Datentypen|String]] || 1 || - || T wenn Stoff umweltgefährdend ist , ansonsten F, Pflicht bei umweltgefährdenden Stoffen
|-
| GEFAHRGUTVPG || [[#Datentypen|String]] || 3 || - || Verpackungsgruppe, bedingt Pflicht bei den Stoffen, bei denen diese in der ADR-Tabelle belegt ist, kann I,II oder III sein oder gar nicht belegt (letzteres z.B. bei Klasse 2)) (siehe ADR-Tabelle Spalte (4))
|-
| '''GEFAHRGUTVERPANZAHL''' ||[[#Datentypen|Integer]] || 4 || - || Anzahl der Einheiten, in denen das Gefahrgut verpackt ist (in Zusammenhang mit dem nächsten Feld GefahrgutVerpackungsart)
|-
| '''GEFAHRGUTVERPACKUNGSART''' ||[[#Datentypen|String]] || 5 || - || ADR-Code der Verpackungsart, z.B. 4G für Kiste (Pappe), Pflicht, siehe separate Doc f. Verpackungscodes
|}
===Gefahrgut (über [[Verarbeitungsbeschreibung: Gefahrgut|Gefahrgutstamm im HVS32]])===
{| class="wikitable sortable"
|-
!Feldname !!Typ!!Max Länge!! Dezimalstellen!!Belegung
|-
|'''GefahrgutID'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|String]]||20||- ||Eindeutige Suchnummer für Gefahrgut-Stammdaten
|-
|'''GefahrgutMenge'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|Decimal]]||8||3||-
|-
|'''GefahrgutVerpAnzahl'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|Integer]]||-||-||-
|-
|'''GefahrgutMengenEinheit'''||[[HVS32 Automatik-Polling Funktionen#Datentypen|String]]||2||- ||'0' bzw Blank: Kilogramm; '1': Liter
|-
|GefahrgutNettoExplMasse ||[[HVS32 Automatik-Polling Funktionen#Datentypen|Decimal]]||8||3 ||Nur bei Klasse 1, dann aber Pflicht
|}

= Packstück-Verarbeitung (VersandDatenAnfrage) =
Die Gatewayfunktion VersandDatenAnfrage wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort ein Etikett für ein Packstück zu erzeugen und verbuchen.
Ein Etikett wird für alle weiteren Funktionen wir Storno, Verladefreigabe, etc. anhand der hostseitigen Packstück-ID identifiziert. Diese wird im Feld PackstueckID übergeben und muss dementsprechend innerhalb des Versandsystems eindeutig sein.

Durch eine zusätzliche Konfiguration im HVS32 kann die VersandDatenAnfrage auch dazu verwendet werden, um einen Nachdruck anzustoßen. Dabei muss bei der erneuten Anfrage die selbe PackstueckID verwendet werden.<br>
<br>
<big>'''Übergabe Parameter'''</big>
<br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| ANSPRECHPARTNER || [[#Datentypen|String]] || 50 || - || Empfänger Ansprechpartner
|-
| ANZAHLARTIKEL || [[#Datentypen|Integer]] || 6 || - || Anzahl Artikel (Druck auf Etikett)
|-
| [[#ArtikelDaten|ARTIKELDATEN]] || [[#Datentypen|Sequence]] '''[[#ArtikelDaten|<ArtikelDaten>]]''' || - || - || Eine Liste der [[#ArtikelDaten|Packstück-Artikel]] vom Typ '''[[#ArtikelDaten|ArtikelDaten]]''' (1:n)
|-
| AUFTRAGNR || [[#Datentypen|String]] || 20 || - || -
|-
| '''AUFTRAGGEBERID''' || [[#Datentypen|String]] || 10 || - || Mandantenkennung aus dem HVS32
|-
| AVISHINWEIS1 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISHINWEIS2 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISZUSATZ1 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 1
|-
| AVISZUSATZ2 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 2
|-
| BARCODEID || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETEXT || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETYP || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BESTELLNR || [[#Datentypen|String]] || 20 || - || Metro-Bestellnr (Metro-Versand)
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name eines Ausgabekanals (Drucker) im HVS32 über den das Etikett gedruckt wird. (Benötigt Druckerspooler Erweiterungsmodul)
|-
| EMAIL || [[#Datentypen|String]] || 100 || - || E-Mail Adresse des Empfängers (z.B.: für die Automatische E-Mail Avisierung)
|-
| EMPFMOBILFUNKNR || [[#Datentypen|String]] || 20 || - || Mobilfunknummer des Empfängers
|-
| FAXNR || [[#Datentypen|String]] || 20 || - || Faxnummer des Empfängers
|-
| FLEXZUSTELLUNGEMAILADRESSE || [[#Datentypen|String]] || 80 || - || Flex-Zustellung Emailadresse
|-
| FRACHTBRIEF || [[#Datentypen|String]] || 20 || - || Frachtbrief Nummer falls Frachtbrief durch Vorsystem gedruckt werden soll
|-
| FRACHTFUEHRERKDNR || [[#Datentypen|String]] || 10 || - || Kundennummer des Frachtzahlers beim Frachtführer
|-
| FRANKATURKENNUNG || [[#Datentypen|String]] || 10 || - || -
|-
| [[#Gefahrgut|GEFAHRGUT]] || [[#Datentypen|Sequence]] '''[[#Gefahrgut|<Gefahrgut>]]''' || - || - || Eine Liste der [[#Gefahrgut|Gefahrgüter]] vom Typ '''[[#Gefahrgut|Gefahrgut]]''' (1:n)
|-
| '''GEWICHT''' ||[[#Datentypen|Decimal]] || 8 || 3 || Bruttogewicht in KG
|-
| HOSTTRACKINGNR || [[#Datentypen|String]] || 35 || - || Paketnummer aus dem Hostsystem
|-
| ILNNR || [[#Datentypen|String]] || 20 || - || ILN des Empfängers (Pflicht bei Metro-Versand)
|-
| KOSTENSTELLE || [[#Datentypen|String]] || 30 || - || -
|-
| KUNDENNR || [[#Datentypen|String]] || 20 || - || Kundennummer des Empfängers beim Versender
|-
| LAGERKENNZEICHEN || [[#Datentypen|Integer]] || - || - || -
|-
| LETZTESPACKSTUECK || [[#Datentypen|String]] || 1 || - || T/F: T=letztes Packstüeck der Sendung (wird bei Hängeversand zum Drucken der Sendungs-Hängekarte benötigt)
|-
| LIEFERANTENID || [[#Datentypen|Integer]] || - || - || -
|-
| '''LIEFERSCHEINNR''' || [[#Datentypen|String]] || 40 || - || Wird im HVS32 als Such-Nummer verwendet
|-
| NACHNAHME || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| NETTOGEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Nettogewicht in KG
|-
| NEUTBIC || [[#Datentypen|String]] || 11 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTBANKBEZEICHNUNG || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTIBAN || [[#Datentypen|String]] || 31 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTKONTOINHABER || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERLKZ || [[#Datentypen|String]] || 3 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME1 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME2 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME3 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERORT || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERPLZ || [[#Datentypen|String]] || 10 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERSTRASSE || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NNVERMERK || [[#Datentypen|String]] || 1 || - || 'B': Bar / 'V': Verrechnungsscheck
|-
| NNVERWENDUNG || [[#Datentypen|String]] || 30 || - || Nachnahme Verwendungszweck
|-
| NNWAEHRUNG || [[#Datentypen|String]] || 3 || - || Nachnahme - ISO-Währungscode
|-
| '''PACKSTKGES''' || [[#Datentypen|Integer]] || - || - || Gesamt-Anzahl Colli der Sendung
|-
| '''PACKSTKNR''' || [[#Datentypen|Integer]] || - || - || Laufende Nr pro Sendung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| PACKSTUECKBREITE || [[#Datentypen|Integer]] || - || - || Breite in cm
|-
| PACKSTUECKHOEHE || [[#Datentypen|Integer]] || - || - || Höhe in cm
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || Eindeutige Nummer für das Paket im Vorsystem. Wird als eindeutige Paketreferenz benötigt um das Etikett später zu stornieren oder zu Verladen.
|-
| PACKSTUECKLAENGE || [[#Datentypen|Integer]] || - || - || Länge in cm
|-
| PAPERLESSINVOICE || [[#Datentypen|String]] || 1 || - || Nur im UPS PaperlessInvoice Fall (T=PaperlessInvoice / F=nicht PaperlessInvoice)
|-
| POSTLEITCODE || [[#Datentypen|String]] || 15 || - || -
|-
| POSTZIELFRACHTZENT || [[#Datentypen|String]] || 5 || - || -
|-
| RECHNUNGSEMPFLKZ || [[#Datentypen|String]] || 5 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFNAME1 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME2 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME3 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFORT || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFPLZ || [[#Datentypen|String]] || 10 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFSTRASSE || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSNR || [[#Datentypen|String]] || 20 || - || Rechnungsnummer
|-
| SENDUNGSINHALT || [[#Datentypen|String]] || 30 || - || -
|-
| SONDERDIENSTE || [[#Datentypen|String]] || 30 || - || Versandart-spezifisch belegt
|-
| SPERRFLAG || [[#Datentypen|String]] || 1 || - || T/F: T=Sperren, sonst nicht sperren
|-
| TELEFONNR || [[#Datentypen|String]] || 20 || - || Telefonnummer des Empfängers
|-
| TERMINART || [[#Datentypen|String]] || 1 || - || 'A' = ab diesem Tag liefern
'B' = bis zu diesem Tag liefern

'F' = an diesem Tag liefern
|-
| TERMINDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| TERMINZEIT || [[#Datentypen|Calendar]] || 5 || - || HH:MM
|-
| USTIDNR || [[#Datentypen|String]] || 20 || - || UmsatzsteuerNr des Empfängers
|-
| VERPACKUNGSART || [[#Datentypen|String]] || 6 || - || -
|-
| '''VERSANDARTID''' || [[#Datentypen|String]] || 10 || - || Versandartkennung aus dem HVS32
|-
| VERSICHERUNGSWERT || [[#Datentypen|Decimal]] || 18 || 2 || Höhe Versicherungswert
|-
| VORPACKDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| VWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Versicherungswert - ISO-Währungscode
|-
| WARENWERT || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke, die diesem Packstück zugewiesen wird
|-
| WWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Warenwert - ISO-Währungscode
|-
| ZAHLUNGSBEDINGUNG || [[#Datentypen|String]] || 10 || - || 'S' = Sender, 'R' = Empfänger
|-
| ZBZOLL || [[#Datentypen|String]] || 1 || - || Zahlungsbedingung für Zoll Steuern 'S' = Sender, 'R' = Empfänger
|-
| ZIELADRBAHNHOF || [[#Datentypen|String]] || 30 || - || PLZ und Ort
|-
| '''ZIELADRLKZ''' || [[#Datentypen|String]] || 5 || - || Lieferadresse
|-
| '''ZIELADRNAME1''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME2 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME3 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME4 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRORT''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRPLZ''' || [[#Datentypen|String]] || 10 || - || Lieferadresse
|-
| ZIELADRREGION || [[#Datentypen|String]] || 20 || - || Staat/Provinz (z.B.: für Sendungen in die USA wichtig)
|-
| '''ZIELADRSTRASSE''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|}

<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung|
|-
| AUSGANGDATETIME || [[#Datentypen|String]] || 10 || - || Datum, wann das Etikett an den Frachtführer übermittelt worden ist (TT.MM.JJJJ)
|-
| DRUCKDATETIME || [[#Datentypen|String]] || 19 || - || Datum, wann das Etikett im HVS32 gedruckt worden ist (TT.MM.JJJJ HH:mm:SS)
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 wenn Erfolgreich
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| GEBUEHR || [[#Datentypen|Decimal]] || 18 || 2 || Frachtkosten
|-
| GEBUEHRWAEHRUNG || [[#Datentypen|String]] || 3 || - || Frachkosten ISO-Währungscode
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || PackstueckID aus der Anfrage
|-
| RETOURTRACKINGNR || [[#Datentypen|String]] || 50 || - || Paketnummer für die Retoure
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || Paketnummer
|-
| TRACKINGURL || [[#Datentypen|String]] || 255 || - || URL des Trackinglinks zur Sendungsverfolgung
|-
| VERSANDSENDUNGSNR || [[#Datentypen|String]] || - || - || -
|}

= Etikett nachdrucken (VersandDatenWdhDruck) =
Die Gatewayfunktion VersandDatenWdhDruck wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort ein Etikett für ein Packstück nachzudrucken.
Ein Etikett wird anhand der hostseitigen Packstück-ID nachgedruckt. Diese wird im Feld PackstueckID übergeben.
Bei manchen Frachtführern (z.B. DPD) werden beim Nachdruck neue Trackingnummern vergeben. Somit ist die alte Trackingnummer nicht mehr gültig und das alte Versandetikett muss vernichtet werden.
Die neue Trackingnummer kann in der Rückmeldung zurückgemeldet werden.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || '''Eindeutige''' Nummer für das Paket im Vorsystem.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Ausgabekanal, an welchem das Etikett nachgedruckt werden soll (benötigt HVS32 Erweiterungsmodul "Druckerspooler")
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || (neue) TrackingNr des Packstücks
|}

= Packstück stornieren (StornoVersandDaten) =
Die Gatewayfunktion StornoVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort bestehende Packstücke zu stornieren, die noch nicht auf einer Ausgangsliste sind.
In der Regel wird ein Packstück anhand der hostseitigen Packstück-ID storniert. Diese wird im Feld PackstueckID übergeben.
Zusätzlich zur hostseitigen Packstück-ID kann auch die TrackingNr zur Identifikation des Packstücks beitragen, für den Fall, dass die hostseitige Packstück-ID keine Eindeutigkeit garantieren kann.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Storno wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || '''Eindeutige''' Nummer für das Paket im Vorsystem.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Packstück verladen/freigeben (VerladeVersandDaten) =
Die Gatewayfunktion VerladeVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort Packstücke für den Ausgang frei zu geben.
Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Tagesabschluss berücksichtigt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreicher Freigabe wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || '''Eindeutige''' Nummer für das Paket im Vorsystem.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| SPERRKENNZEICHEN || [[#Datentypen|String]] || 1 || - || "J" wenn das Packstück gesperrt werden soll
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke auf welche das Packstück gebucht werden soll
|-
| SAMMELFREIGABE || [[#Datentypen|String]] || 1 || - || "T" bei einer Sammel-Freigabe (Alle Packstücke mit identischer VE-ReferenzNr freigeben)
|-
| VEREFERENZNR || [[#Datentypen|String]] || 20 || - || muss bei einer Sammel-Freigabe gefüllt sein
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Tagesabschluss (Tagesabschluss) =
Das Gateway sendet die Tagesabschluss-Anfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit ein Tagesabschluss anhand der zusätzlich übergebenen Parameter ausgelöst.
Der Tagesabschluss setzt sich aus den Punkten Ausgangsliste erzeugen und Frachtführer DFÜ erzeugen zusammen.
Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Tagesabschluss berücksichtigt. Standardmäßig sind alle Packstücke freigegeben, außer sie wurden durch das Erweiterungsmodul Ausgangsscannung gesperrt.
Die Rückmeldung im HVS32 findet nach dem Ausführen des Tagesabschluss statt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Tagesabschluss wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Tagesabschluss ausführen soll.
|-
| FRACHTFUEHRERTYPLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Frachführern mitgegeben werden. Es können n-Frachtführer abgeschlossen werden.
(Option MultiFFTagesabschluss muss im HVS32 aktiv sein)
|-
| AUFTRAGGEBERIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Auftraggebern mitgegeben werden. Es können n-Auftraggeber abgeschlossen werden.
(Option MultiAGTagesabschluss muss im HVS32 aktiv sein)
|-
| VERSANDARTIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Versandarten mitgegeben werden. Es können n-Versandarten abgeschlossen werden.
(Option MultiVATagesabschluss muss im HVS32 aktiv sein)
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Kennzeichen der abzuschließenden Wechselbrücke. Hiermit können nur bestimmte Sendungen abgeschlossen werden.
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name des Ausgabekanals auf welchem die Liste gedruckt werden soll
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Ausgangsliste erzeugen (Listenabschluss) =
Das Gateway sendet die Listenabschluss-Anfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit eine Ausgangsliste anhand der zusätzlich übergebenen Parameter erzeugt.
Nur Packstücke, welche für den Ausgang freigegeben wurden, werden für den Listenabschluss berücksichtigt. Standardmäßig sind alle Packstücke freigegeben, außer sie wurden durch das Erweiterungsmodul Ausgangsscannung gesperrt.
Die Rückmeldung im HVS32 findet nach dem Erzeugen der Ausgangsliste statt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Listenabschluss wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Tagesabschluss ausführen soll.
|-
| FRACHTFUEHRERTYPLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Frachführern mitgegeben werden. Es können n-Frachtführer abgeschlossen werden.
(Option MultiFFTagesabschluss muss im HVS32 aktiv sein)
|-
| AUFTRAGGEBERIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Auftraggebern mitgegeben werden. Es können n-Auftraggeber abgeschlossen werden.
(Option MultiAGTagesabschluss muss im HVS32 aktiv sein)
|-
| VERSANDARTIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Versandarten mitgegeben werden. Es können n-Versandarten abgeschlossen werden.
(Option MultiVATagesabschluss muss im HVS32 aktiv sein)
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Kennzeichen der abzuschließenden Wechselbrücke. Hiermit können nur bestimmte Sendungen abgeschlossen werden.
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name des Ausgabekanals auf welchem die Liste gedruckt werden soll
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Frachtführer DFÜ erzeugen (EDIAbschluss) =
Das Gateway sendet die EDIAbschluss-Anfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit eine Frachtführer DFÜ anhand der zusätzlich übergebenen Parameter erzeugt und (falls konfiguriert) an den Frachtführer übertragen.
Nur Packstücke, für welche zuvor eine Ausgangsliste erzeugt wurde, werden für eine Frachtführer DFÜ berücksichtigt.
Die Rückmeldung im HVS32 findet nach dem Erzeugen der Frachtführer DFÜ statt.
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem EDIAbschluss wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Tagesabschluss ausführen soll.
|-
| FRACHTFUEHRERTYPLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Frachführern mitgegeben werden. Es können n-Frachtführer abgeschlossen werden.
(Option MultiFFTagesabschluss muss im HVS32 aktiv sein)
|-
| AUFTRAGGEBERIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Auftraggebern mitgegeben werden. Es können n-Auftraggeber abgeschlossen werden.
(Option MultiAGTagesabschluss muss im HVS32 aktiv sein)
|-
| VERSANDARTIDLIST || [[#Datentypen|String]] || 250 || - || Hier kann eine Semikolon separierte Liste mit den abzuschließenden Versandarten mitgegeben werden. Es können n-Versandarten abgeschlossen werden.
(Option MultiVATagesabschluss muss im HVS32 aktiv sein)
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Kennzeichen der abzuschließenden Wechselbrücke. Hiermit können nur bestimmte Sendungen abgeschlossen werden.
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Packstückdaten prüfen (VersandDatenPruefAnfrage) =
Das Gateway sendet die VersandDatenPruefAnfrage an das Automatik-Polling des HVS32. Im HVS32 wird somit eine VersandDatenAnfrage simuliert.
Dabei werden keine Etiketten gedruckt und das Packstück bzw. das Etikett wird nicht verbucht, jedoch sind alle weiteren Prozesse identisch zur VersandDatenAnfrage (Routenermittlung, Trackingnummer-Ermittlung, Adressprüfung, etc.)
Diese Funktion dient dazu im Vorfeld alle Versand-Daten zu validieren.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| ANSPRECHPARTNER || [[#Datentypen|String]] || 50 || - || Empfänger Ansprechpartner
|-
| ANZAHLARTIKEL || [[#Datentypen|Integer]] || 6 || - || Anzahl Artikel (Druck auf Etikett)
|-
| [[#ArtikelDaten|ARTIKELDATEN]] || [[#Datentypen|Sequence]] '''[[#ArtikelDaten|<ArtikelDaten>]]''' || - || - || Eine Liste der [[#ArtikelDaten|Packstück-Artikel]] vom Typ '''[[#ArtikelDaten|ArtikelDaten]]''' (1:n)
|-
| AUFTRAGNR || [[#Datentypen|String]] || 20 || - || -
|-
| '''AUFTRAGGEBERID''' || [[#Datentypen|String]] || 10 || - || Mandantenkennung aus dem HVS32
|-
| AVISHINWEIS1 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISHINWEIS2 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISZUSATZ1 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 1
|-
| AVISZUSATZ2 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 2
|-
| BARCODEID || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETEXT || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BARCODETYP || [[#Datentypen|String]] || - || - || Zusatzfeld für evtl. Erweiterungen
|-
| BESTELLNR || [[#Datentypen|String]] || 20 || - || Metro-Bestellnr (Metro-Versand)
|-
| DRUCKERNAME || [[#Datentypen|String]] || 30 || - || Name eines Ausgabekanals (Drucker) im HVS32 über den das Etikett gedruckt wird. (Benötigt Druckerspooler Erweiterungsmodul)
|-
| EMAIL || [[#Datentypen|String]] || 100 || - || E-Mail Adresse des Empfängers (z.B.: für die Automatische E-Mail Avisierung)
|-
| EMPFMOBILFUNKNR || [[#Datentypen|String]] || 20 || - || Mobilfunknummer des Empfängers
|-
| FAXNR || [[#Datentypen|String]] || 20 || - || Faxnummer des Empfängers
|-
| FLEXZUSTELLUNGEMAILADRESSE || [[#Datentypen|String]] || 80 || - || Flex-Zustellung Emailadresse
|-
| FRACHTBRIEF || [[#Datentypen|String]] || 20 || - || Frachtbrief Nummer falls Frachtbrief durch Vorsystem gedruckt werden soll
|-
| FRACHTFUEHRERKDNR || [[#Datentypen|String]] || 10 || - || Kundennummer des Frachtzahlers beim Frachtführer
|-
| FRANKATURKENNUNG || [[#Datentypen|String]] || 10 || - || -
|-
| [[#Gefahrgut|GEFAHRGUT]] || [[#Datentypen|Sequence]] '''[[#Gefahrgut|<Gefahrgut>]]''' || - || - || Eine Liste der [[#Gefahrgut|Gefahrgüter]] vom Typ '''[[#Gefahrgut|Gefahrgut]]''' (1:n)
|-
| '''GEWICHT''' ||[[#Datentypen|Decimal]] || 8 || 3 || Bruttogewicht in KG
|-
| HOSTTRACKINGNR || [[#Datentypen|String]] || 35 || - || Paketnummer aus dem Hostsystem
|-
| ILNNR || [[#Datentypen|String]] || 20 || - || ILN des Empfängers (Pflicht bei Metro-Versand)
|-
| KOSTENSTELLE || [[#Datentypen|String]] || 30 || - || -
|-
| KUNDENNR || [[#Datentypen|String]] || 20 || - || Kundennummer des Empfängers beim Versender
|-
| LAGERKENNZEICHEN || [[#Datentypen|Integer]] || - || - || -
|-
| LETZTESPACKSTUECK || [[#Datentypen|String]] || 1 || - || T/F: T=letztes Packstüeck der Sendung (wird bei Hängeversand zum Drucken der Sendungs-Hängekarte benötigt)
|-
| LIEFERANTENID || [[#Datentypen|Integer]] || - || - || -
|-
| '''LIEFERSCHEINNR''' || [[#Datentypen|String]] || 40 || - || Wird im HVS32 als Such-Nummer verwendet
|-
| NACHNAHME || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| NETTOGEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Nettogewicht in KG
|-
| NEUTBIC || [[#Datentypen|String]] || 11 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTBANKBEZEICHNUNG || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTIBAN || [[#Datentypen|String]] || 31 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTKONTOINHABER || [[#Datentypen|String]] || 40 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERLKZ || [[#Datentypen|String]] || 3 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME1 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME2 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERNAME3 || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERORT || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERPLZ || [[#Datentypen|String]] || 10 || - || Nur bei Neutral-Absendern belegt
|-
| NEUTABSENDERSTRASSE || [[#Datentypen|String]] || 50 || - || Nur bei Neutral-Absendern belegt
|-
| NNVERMERK || [[#Datentypen|String]] || 1 || - || B': Bar / 'V': Verrechnungsscheck
|-
| NNVERWENDUNG || [[#Datentypen|String]] || 30 || - || Nachnahme Verwendungszweck
|-
| NNWAEHRUNG || [[#Datentypen|String]] || 3 || - || Nachnahme - ISO-Währungscode
|-
| '''PACKSTKGES''' || [[#Datentypen|Integer]] || - || - || Gesamt-Anzahl Colli der Sendung
|-
| '''PACKSTKNR''' || [[#Datentypen|Integer]] || - || - || Laufende Nr pro Sendung
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeten soll.
|-
| PACKSTUECKBREITE || [[#Datentypen|Integer]] || - || - || Breite in cm
|-
| PACKSTUECKHOEHE || [[#Datentypen|Integer]] || - || - || Höhe in cm
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Nummer für das Paket im Vorsystem. Wird als eindeutige Paketreferenz benötigt um das Etikett später zu stornieren oder zu Verladen.
|-
| PACKSTUECKLAENGE || [[#Datentypen|Integer]] || - || - || Länge in cm
|-
| PAPERLESSINVOICE || [[#Datentypen|String]] || 1 || - || Nur im UPS PaperlessInvoice Fall (T=PaperlessInvoice / F=nicht PaperlessInvoice)
|-
| POSTLEITCODE || [[#Datentypen|String]] || 15 || - || -
|-
| POSTZIELFRACHTZENT || [[#Datentypen|String]] || 5 || - || -
|-
| RECHNUNGSEMPFLKZ || [[#Datentypen|String]] || 5 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFNAME1 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME2 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME3 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFORT || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFPLZ || [[#Datentypen|String]] || 10 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFSTRASSE || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSNR || [[#Datentypen|String]] || 20 || - || Rechnungsnummer
|-
| SENDUNGSINHALT || [[#Datentypen|String]] || 30 || - || -
|-
| SONDERDIENSTE || [[#Datentypen|String]] || 30 || - || Versandart-spezifisch belegt
|-
| SPERRFLAG || [[#Datentypen|String]] || 1 || - || T/F: T=Sperren, sonst nicht sperren
|-
| TELEFONNR || [[#Datentypen|String]] || 20 || - || Telefonnummer des Empfängers
|-
| TERMINART || [[#Datentypen|String]] || 1 || - || 'A'b / 'B'is / 'F'ix
|-
| TERMINDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| TERMINZEIT || [[#Datentypen|Calendar]] || 5 || - || HH:MM
|-
| USTIDNR || [[#Datentypen|String]] || 20 || - || UmsatzsteuerNr des Empfängers
|-
| VERPACKUNGSART || [[#Datentypen|String]] || 6 || - || -
|-
| '''VERSANDARTID''' || [[#Datentypen|String]] || 10 || - || Versandartkennung aus dem HVS32
|-
| VERSICHERUNGSWERT || [[#Datentypen|Decimal]] || 18 || 2 || Höhe Versicherungswert
|-
| VORPACKDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| VWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Versicherungswert - ISO-Währungscode
|-
| WARENWERT || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke, die diesem Packstück zugewiesen wird
|-
| WWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Warenwert - ISO-Währungscode
|-
| ZAHLUNGSBEDINGUNG || [[#Datentypen|String]] || 10 || - || 'S' = Sender, 'R' = Empfänger
|-
| ZBZOLL || [[#Datentypen|String]] || 1 || - || Zahlungsbedingung für Zoll Steuern 'S' = Sender, 'R' = Empfänger
|-
| ZIELADRBAHNHOF || [[#Datentypen|String]] || 30 || - || PLZ und Ort
|-
| '''ZIELADRLKZ''' || [[#Datentypen|String]] || 5 || - || Lieferadresse
|-
| '''ZIELADRNAME1''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME2 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME3 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| ZIELADRNAME4 || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRORT''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|-
| '''ZIELADRPLZ''' || [[#Datentypen|String]] || 10 || - || Lieferadresse
|-
| ZIELADRREGION || [[#Datentypen|String]] || 20 || - || Staat/Provinz (z.B.: für Sendungen in die USA wichtig)
|-
| '''ZIELADRSTRASSE''' || [[#Datentypen|String]] || 50 || - || Lieferadresse
|}

<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung|
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 wenn Erfolgreich
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || Wird im Fehlerfall befüllt
|-
| GEBUEHR || [[#Datentypen|Decimal]] || 18 || 2 || Frachtkosten
|-
| GEBUEHRWAEHRUNG || [[#Datentypen|String]] || 3 || - || Frachkosten ISO-Währungscode
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || PackstueckID aus der Anfrage
|}

= Packstückdaten aktualisieren (UpdateVersandDaten) =
Die Gatewayfunktion UpdateVersandDaten wird vom Data-Gateway-Server im Automatik-Polling Modus an das HVS32 gesendet, um dort die Daten von bestehende Packstücken zu verändern.
Diese Anfrage wird zum Beispiel gesendet, wenn der Warenwert für ein Packstück erst zu einem späteren Zeitpunkt bekannt ist.
Aktualisiert werden können Daten innerhalb der Tabellen Versandeinheit, Abrechnungseinheit und Lieferung. Dabei wird stets über das Feld PackstueckID und bei Belegung auch über das Feld TrackingNr gesucht.
<br><br>
'''Bei dieser Anfrage werden allerdings die zu aktualisierenden Felder und Inhalte nicht mehr nach den Richtlinien des Frachtführers geprüft (z.B. Gewichtsgrenzen, etc.). Es muss somit vom Vorsystem sichergestellt werden, dass die aktualisierenden Werte mit den Richtlinien des Frachtführers übereinstimmen. Sollte dies nicht möglich sein, kann diese Funktion nicht genutzt werden, sondern das Etikett muss storniert und neu verarbeitet werden. Außerdem können Felder, welche bereits auf einem Etikett angedruckt oder vom Versandsystem HVS32 in einer Frachtführerabwicklung ermittelt wurden (z.B. Adresse, Route, TrackingNr, Sonderdienste, etc.) nicht manipuliert werden.'''<br><br>

'''ACHTUNG: Alle Felder, welche im Versandsystem aktualisiert werden sollen, müssen vor der Nutzung dieser Funktion abgestimmt und im Versandsystem entsprechend konfiguriert werden!'''<br><br>
Es stehen keine Packstück-/Sendungs-Daten für die Rückmeldung zur Verfügung. Nach erfolgreichem Update wird lediglich das Feld Fehler mit Wert 0 zurückgemeldet - bzw. im Fehlerfall wird Fehler mit dem Wert 1 sowie der Fehlertext1 zurückgemeldet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| '''PACKSTUECKID''' || [[#Datentypen|String]] || 20 || - || Eindeutige Nummer für das Paket im Vorsystem. Wird als eindeutige Paketreferenz benötigt um den Datensatz zu identifizieren.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der den Auftrag verarbeiten soll.
|-
| ANSPRECHPARTNER || [[#Datentypen|String]] || 50 || - || Empfänger Ansprechpartner
|-
| AVISHINWEIS1 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISHINWEIS2 || [[#Datentypen|String]] || 100 || - || -
|-
| AVISZUSATZ1 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 1
|-
| AVISZUSATZ2 || [[#Datentypen|String]] || 60 || - || Zusatz zu Fest-AVIS-Schlüssel 2
|-
| BESTELLNR || [[#Datentypen|String]] || 20 || - || Metro-Bestellnr (Metro-Versand)
|-
| EMAIL || [[#Datentypen|String]] || 100 || - || E-Mail Adresse des Empfängers (z.B.: für die Automatische E-Mail Avisierung)
|-
| EMPFMOBILFUNKNR || [[#Datentypen|String]] || 20 || - || Mobilfunknummer des Empfängers
|-
| FAXNR || [[#Datentypen|String]] || 20 || - || Faxnummer des Empfängers
|-
| FLEXZUSTELLUNGEMAILADRESSE || [[#Datentypen|String]] || 80 || - || Flex-Zustellung Emailadresse
|-
| GEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Bruttogewicht in KG
|-
| NETTOGEWICHT || [[#Datentypen|Decimal]] || 8 || 3 || Nettogewicht in KG
|-
| ILNNR || [[#Datentypen|String]] || 20 || - || ILN des Empfängers (Pflicht bei Metro-Versand)
|-
| KOSTENSTELLE || [[#Datentypen|String]] || 30 || - || -
|-
| LIEFERANTENID || [[#Datentypen|Integer]] || - || - || -
|-
| NACHNAHME || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| NNVERMERK || [[#Datentypen|String]] || 1 || - || B': Bar / 'V': Verrechnungsscheck
|-
| NNVERWENDUNG || [[#Datentypen|String]] || 30 || - || Nachnahme Verwendungszweck
|-
| NNWAEHRUNG || [[#Datentypen|String]] || 3 || - || Nachnahme - ISO-Währungscode
|-
| PACKSTUECKBREITE || [[#Datentypen|Integer]] || - || - || Breite in cm
|-
| PACKSTUECKHOEHE || [[#Datentypen|Integer]] || - || - || Höhe in cm
|-
| PACKSTUECKLAENGE || [[#Datentypen|Integer]] || - || - || Länge in cm
|-
| RECHNUNGSEMPFLKZ || [[#Datentypen|String]] || 5 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFNAME1 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME2 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFNAME3 || [[#Datentypen|String]] || 50 || - || Rechnungsempfänger
|-
| RECHNUNGSEMPFORT || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFPLZ || [[#Datentypen|String]] || 10 || - || Rechnungsadresse
|-
| RECHNUNGSEMPFSTRASSE || [[#Datentypen|String]] || 50 || - || Rechnungsadresse
|-
| RECHNUNGSNR || [[#Datentypen|String]] || 20 || - || Rechnungsnummer
|-
| SENDUNGSINHALT || [[#Datentypen|String]] || 30 || - || -
|-
| TELEFONNR || [[#Datentypen|String]] || 20 || - || Telefonnummer des Empfängers
|-
| VORPACKDATUM || [[#Datentypen|String]] || 10 || - || TT.MM.JJJJ
|-
| VERSICHERUNGSWERT || [[#Datentypen|Decimal]] || 18 || 2 || Höhe Versicherungswert
|-
| VWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Versicherungswert - ISO-Währungscode
|-
| WECHSELBRUECKE || [[#Datentypen|String]] || 20 || - || Wechselbrücke, die diesem Packstück zugewiesen wird
|-
| WARENWERT || [[#Datentypen|Decimal]] || 18 || 2 || -
|-
| WWWAEHRUNG || [[#Datentypen|String]] || 3 || - || Warenwert - ISO-Währungscode
|}

<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Packstückdaten anonymisieren (AnonymisiereVersandDaten) =
Das Gateway sendet die AnonymisiereVersandDaten an das Automatik-Polling des HVS32. Im HVS32 werden somit Kunden bezogene Daten für den entsprechenden Datensatz gemäß DSGVO anonymisiert.
Diese Anonymisierung wird unwiderruflich und endgültig auf der Datenbankebene des Versandsystems durchgeführt. Eine Wiederherstellung der ursprünglichen Daten ist somit nicht mehr möglich.
Log-Dateien, Rückmelde-Dateien, bereits übertragene Frachtführer DFÜs etc. sind hiervon nicht betroffen. Es können ausschließlich Packstücke und Sendungen anonymisiert werden, welche bereits Tages abgeschlossen sind.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || PackstückID des Packstücks, welches anonymisiert werden soll.
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || TrackingNr des Packstücks, welches anonymisiert werden soll.
|-
| LIEFERSCHEINNR || [[#Datentypen|String]] || 40 || - || LieferscheinNr der Sendung, welche anonymisiert werden soll.
|-
| AUFTRAGSNR || [[#Datentypen|String]] || 50 || - || AuftragsNr der Sendung, welche anonymisiert werden soll.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, der die Anonymisierung verarbeiten soll.
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|}

= Statusdaten für ein Packstück abrufen (StatusDatenAnfrage) =
Das Gateway sendet die StatusDatenAnfrage an das Automatik-Polling des HVS32. Im HVS32 werden zu diesem Packstück alle vorhandenen Statusdaten abgerufen und ans Gateway zurückgemeldet.<br>
Das Packstück wird anhand der PackstueckId, der TrackingNr oder einer kombination aus beiden (falls nur einer der beiden Referenzen nicht eundeutig ist) identifiziert.<br><br>
Werden im HVS32 zu der Referenz mehrere Packstücke identifiziert, so wird immer das aktuellste Packstück verwendet.
<br><br><big>'''Übergabe Parameter'''</big><br>
<small>'''Fett''' dargestellte Felder müssen IMMER belegt sein</small>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Packstueck-Id aus dem Hostsystem, welches das Packstück identifiziert.
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || TrackingNr des Packstuecks.
|-
| PACKPLATZ || [[#Datentypen|String]] || 10 || - || HVS32-Packplatz-Client, welcher die Anfrage verarbeiten soll (Optional).
|}
<br><big>'''Rückgabe Parameter'''</big><br>
{| class="wikitable sortable"
|-
! Feldname !! Typ !! Max Länge !! Dezimalstellen !! Belegung
|-
| FEHLER || [[#Datentypen|Integer]] || - || - || 0 = Erfolgreich, 1 = Fehler
|-
| FEHLERTEXT1 || [[#Datentypen|String]] || 200 || - || -
|-
| FEHLERTEXT2 || [[#Datentypen|String]] || 200 || - || -
|-
| EINTRAGDATETIME || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit, wann der Statuscode ins HVS32 importiert worden ist (Format abhängig vom Betriebssystem)
|-
| EINTRAGDATETIME_TIMESTAMP || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit, wann der Statuscode ins HVS32 importiert worden ist (Format: dd.mm.yyyy hh:mm:ss)
|-
| EMPFANGSQUITTIERER || [[#Datentypen|String]] || 100 || - || Name des Empfängers, der das Paket/die Sendung entgegen nahm
|-
| FEHLERSTATUS || [[#Datentypen|String]] || 2 || - || I = Info, F = Fehler
|-
| FFSTATUSCODE || [[#Datentypen|String]] || 10 || - || Frachtführerspezifischer Statuscode
|-
| FFSTATUSKLARTEXT || [[#Datentypen|String]] || 250 || - || Klartext der den Statuscode beschreibt
|-
| FFZUSATZCODE || [[#Datentypen|String]] || 10 || - || Zusätzlicher Statuscode
|-
| FFZUSATZKLARTEXT || [[#Datentypen|String]] || 120 || - || Klartext der den zusätzlichen Statuscode beschreibt
|-
| PACKSTUECKID || [[#Datentypen|String]] || 20 || - || Eindeutige Packstueck-Id aus dem Hostsystem, welches das Packstück identifiziert.
|-
| STATUSDATETIME || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit des Statuscodes (Format abhängig vom Betriebssystem)
|-
| STATUSDATETIME_TIMESTAMP || [[#Datentypen|String]] || 25 || - || Datum und optional Uhrzeit des Statuscodes (Format: dd.mm.yyyy hh:mm:ss)
|-
| STATUSORT || [[#Datentypen|String]] || 30 || - || Ort an dem der Status eingetreten ist (z.B. Nummer des Depots)
|-
| STATUSTYP || [[#Datentypen|String]] || 30 || - || E = Endestatus, Z = Zwischenstatus
|-
| TRACKINGNR || [[#Datentypen|String]] || 35 || - || Trackingnummer
|-
| ZUSATZKLARTEXT || [[#Datentypen|String]] || 80 || - || Zusätzliche Informationen
|}

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2025-12-05T13:59:04Z

Odelice:

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
</source>
</div></div>
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die StatusDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'Z_STATUSDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)

EXPORTING
STATUSDATEN TABLE
PACKSTUECKID CHAR(30)
TRACKINGNR CHAR(35)
EINTRAGDATETIME CHAR(20)
EMPFANGSQUITTIERER CHAR(100)
FEHLERSTATUS CHAR(2)
FFSTATUSCODE CHAR(10)
FFSTATUSKLARTEXT CHAR(250)
FFZUSATZCODE CHAR(10)
FFZUSATZKLARTEXT CHAR(120)
STATUSDATETIME CHAR(20)
STATUSORT CHAR(30)
STATUSTYP CHAR(2)
ZUSATZKLARTEXT CHAR(80)
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

Interfaces: Security Levels and Authentication

2025-05-26T14:35:41Z

Odelice:

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)<br>
Please make sure that the certificate chain in the provided certificate is complete.<br><br>
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.39''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."

To request the initial tokens we offer multiple options.

You can either request the tokens via Authorization Basic, in which the ClientID + ClientSecret are exposed in the HTTP header.<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>

Another option is to request the tokens via JWT. In this option the ClientID is within the payload and the JWT is signed with the ClientSecret. This option offers additional securities, since the ClientSecret itself is never exposed.<div class="toccolours mw-collapsible mw-collapsed"><div>'''Example of token request (generating access and refresh tokens with JWT)'''</div><div class="mw-collapsible-content">
For the token request via JWT (jwt-bearer) the ClientID is within the payload as ''sub'' and signed with ClientSecret. The JWT must be transmitted in the HTTP header ''client_assertion''. To use JWT authentification the HTTP header ''client_assertion_type'' with value ''jwt-bearer''.

Additionally, the '''grant_type''' with the value ''client_credentials'' is necessary for this function.

In this example following '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - was used.

Following '''ClientSecret''' was used - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight></div></div><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br>

==Managing Client Credentials in the DGS==
The client credentials are managed in the DataGatewayServer. You can create new credentials or delete existing ones.<br>
To do this, start the Credentials Configurator (.exe) located in the installation directory of the DataGatewayServer.
===Config===
[[File:Authorization Credentials 001.png|thumb|right|Credentials Configurator - config]]
On this screen, general configurations can be made.
* '''check invalid logins'''<br>If this option is active, the number of invalid authentication attempts will be counted. After '''max invalid logins''' within '''timespan in seconds''', all credentials will be locked.
* '''execute CODE RED for OAuth2.0 CC'''<br>If this option is active when using OAuth2.0 CC, a '''CODE RED''' will be triggered if a REFRESH TOKEN is reused multiple times. This action deactivates all ACCESS and REFRESH TOKENS, requiring new tokens to be requested via client credentials. Additionally, the DGS Configurator can be configured to send an email notification in the event of a CODE RED.
* '''Lock Credentials / Unlock Credentials'''<br>With this button, all credentials can be locked or unlocked. For instance, if all client credentials were locked due to the '''check invalid logins''' option, they can be unlocked here. This action takes effect immediately without needing to save.
* Save<br>This button persistently saves the settings and credentials. The options and credentials only become active after saving. A DGS restart is not required.
===Managing Credentials===
[[File:Authorization Credentials 002.png|thumb|right|Credentials Configurator - OAuth2.0 CC]]
[[File:Authorization Credentials 003.png|thumb|right|Enter Username / ClientID]]
[[File:Authorization Credentials 004.png|thumb|right|Show Credentials Dialog]]
To manage your credentials, select the appropriate tab for the authentication method configured in the DGS (e.g., OAuth2.0 CC).
* '''add'''<br>create new credentials. Note that the password or client secret will only be displayed once in a dialog. Be sure to copy it to a secure location and ensure no unauthorized persons have access to it.
* '''change secret''' or '''change password'''<br>assign a new password or client secret. As with the add function, the password or client secret will only be displayed once in a dialog.
* '''remove'''<br>remove the selected credentials.

Interfaces: Security Levels and Authentication

2025-05-26T14:35:19Z

Odelice:

[[en:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)<br>
Please make sure that the certificate chain in the provided certificate is complete.<br><br>
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.39''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."

To request the initial tokens we offer multiple options.

You can either request the tokens via Authorization Basic, in which the ClientID + ClientSecret are exposed in the HTTP header.<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>

Another option is to request the tokens via JWT. In this option the ClientID is within the payload and the JWT is signed with the ClientSecret. This option offers additional securities, since the ClientSecret itself is never exposed.<div class="toccolours mw-collapsible mw-collapsed"><div>'''Example of token request (generating access and refresh tokens with JWT)'''</div><div class="mw-collapsible-content">
For the token request via JWT (jwt-bearer) the ClientID is within the payload as ''sub'' and signed with ClientSecret. The JWT must be transmitted in the HTTP header ''client_assertion''. To use JWT authentification the HTTP header ''client_assertion_type'' with value ''jwt-bearer''.

Additionally, the '''grant_type''' with the value ''client_credentials'' is necessary for this function.

In this example following '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - was used.

Following '''ClientSecret''' was used - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight></div></div><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br>

==Managing Client Credentials in the DGS==
The client credentials are managed in the DataGatewayServer. You can create new credentials or delete existing ones.<br>
To do this, start the Credentials Configurator (.exe) located in the installation directory of the DataGatewayServer.
===Config===
[[File:Authorization Credentials 001.png|thumb|right|Credentials Configurator - config]]
On this screen, general configurations can be made.
* '''check invalid logins'''<br>If this option is active, the number of invalid authentication attempts will be counted. After '''max invalid logins''' within '''timespan in seconds''', all credentials will be locked.
* '''execute CODE RED for OAuth2.0 CC'''<br>If this option is active when using OAuth2.0 CC, a '''CODE RED''' will be triggered if a REFRESH TOKEN is reused multiple times. This action deactivates all ACCESS and REFRESH TOKENS, requiring new tokens to be requested via client credentials. Additionally, the DGS Configurator can be configured to send an email notification in the event of a CODE RED.
* '''Lock Credentials / Unlock Credentials'''<br>With this button, all credentials can be locked or unlocked. For instance, if all client credentials were locked due to the '''check invalid logins''' option, they can be unlocked here. This action takes effect immediately without needing to save.
* Save<br>This button persistently saves the settings and credentials. The options and credentials only become active after saving. A DGS restart is not required.
===Managing Credentials===
[[File:Authorization Credentials 002.png|thumb|right|Credentials Configurator - OAuth2.0 CC]]
[[File:Authorization Credentials 003.png|thumb|right|Enter Username / ClientID]]
[[File:Authorization Credentials 004.png|thumb|right|Show Credentials Dialog]]
To manage your credentials, select the appropriate tab for the authentication method configured in the DGS (e.g., OAuth2.0 CC).
* '''add'''<br>create new credentials. Note that the password or client secret will only be displayed once in a dialog. Be sure to copy it to a secure location and ensure no unauthorized persons have access to it.
* '''change secret''' or '''change password'''<br>assign a new password or client secret. As with the add function, the password or client secret will only be displayed once in a dialog.
* '''remove'''<br>remove the selected credentials.

Schnittstellen: Security Levels und Authentifizierung

2025-05-26T14:35:04Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>
Stellen Sie sicher, dass falls vorhanden die Zertifikatskette vollständig im Zertifikat hinterlegt ist.<br><br>
Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.39''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>Bei der initialen Tokenanfrage stehen verschiedene zwei Möglichkeiten zum Abrufen bereit.

Zum einen kann man die Token über die Authorization Basic anfragen, bei welchem die ClientID + ClientSecret im HTTP-Header mitgegeben werden.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>Eine weitere Variante die Token abzurufen ist über einen JWT. Bei dieser Methode wird die ClientID im Payload vom JWT übermittelt und das JWT selbst mit dem ClientSecret signiert. Diese Möglichkeit bietet eine zusätzliche Sicherheit, da dass ClientSecret selbst nie exposed wird.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken über JWT generieren)</div>
<div class="mw-collapsible-content">
Bei der Token-Anfrage '''JWT (jwt-bearer)''' muss die Client-ID und das Client-Secret in einem JWT übermittelt werden. Dabei wird die '''ClientID''' im JWT Payload als "sub" übermittelt und mit dem ClientSecret signiert. Das JWT wird Im HTTP-Header als ''client_assertion'' übermittelt. Die Anfrage über das JWT erfolgt über den HTTP-Header ''client_assertion_type''.

Zusätzlich ist für diese Funktion der '''grant_type''' mit dem Wert ''client_credentials'' notwendig.

In diesem Beispiel wurde die '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - verwendet.

Das '''ClientSecret''' lautet - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br>

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können Sie die die ausgewählten Credentials entfernen.

HVS32 SAP RFC Schnittstelle (Interaktiv)

2025-05-20T07:57:33Z

Odelice:

[[en:HVS32_SAP_RFC_Interface_(Interactive)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.6.0.550 oder höher
|-
| DGS-Plugins || HVS32Server, SAP RFC Client
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Verbindung über das RFC-Protokoll mit einem ABAP Applikations-Server die SAP Bibliothek "JCo". Bei interaktiver Verarbeitung werden Anfragen aus dem Versandsystem heraus an das SAP-System gestellt. Dabei agiert der DGS als RFC Client-Programm, welches sich explizit an einen bestimmten SAP-Applikationsserver zur Bearbeitung der Anfrage wendet.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

<gallery>
RFCClientSapServer.png|Architektur: DGS SAP/RFC Client
RFCClientSapServerGroup.png|Architektur: DGS SAP/RFC Client (Server Gruop)
</gallery>

= Notwendige SAP-Komponenten/-Parameter =

* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen

<br>
folgende Parameter werden vom DGS benötigt, um RFC Bausteine bei einem SAP System aufzurufen:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.ashost || SAP-Applikation-Server auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| RFCFunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>

Das HVS32 sendet die Daten in den Import-Parametern - alle Parameter, welche an das HVS32 übertragen werden sollen, müssen in die Export-Parameter geschrieben werden. Die Kommunikation ist bidirektional, d.h. die Rückmeldung von SAP erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br><br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Funktionen_Interaktiv|Verfügbare HVS32 Funktionen]]'''

= Beispiele =

<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'.

IMPORTING
REFERENCENO CHAR(40)

EXPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)

TABLE DGPOSITIONS
UNNR CHAR(4)
KLASSE CHAR(6)
VPG CHAR(5)
KCODE CHAR(5)
BEZEICHNUNG CHAR(110)
MENGE CHAR(9)
BEGRENZTEMENGE CHAR(1)
VERPANZAHL CHAR(10)
VERPACKUNGSART CHAR(8)
NEBENGEFAHR CHAR(20)
BUCHST640 CHAR(1)
MENGENEINHEIT CHAR(2)
BEFOERDKAT CHAR(10)
FAKTOR CHAR(10)
NETTOEXPLMASSE CHAR(9)
TUNNELBCODE CHAR(10)
FREIGESTMENGE CHAR(1)
FFCODE CHAR(20)
</source>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die PaketscheinDruckMeldung</div>
<div class="mw-collapsible-content">
<source>
'ZHVSPAKETSCHEINDRUCKMELDUNG'.
IMPORTING
PACKSTUECKRUECK STRUCTURE
LIEFERSCHEINNR CHAR(40)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
GEWICHT CHAR(9)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
EXPORTING
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)
</source>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die AusgangslistenRueckMeldung</div>
<div class="mw-collapsible-content">
<source>
'ZHVSAusgangslistenRueckMeldung'.
IMPORTING
AUSGANGSLISTENR (20)
PACKSTUECKRUECK TABLE
LIEFERSCHEINNR CHAR(40)
TRACKINGNR CHAR(35)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)

oder

'ZHVSAusgangslistenRueckMeldung'.
IMPORTING
AUSGANGSLISTENR (20)

TABLE PACKSTUECKRUECK
LIEFERSCHEINNR CHAR(40)
TRACKINGNR CHAR(35)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
</source>
</div></div>

= FAQ / Troubleshooting =

HVS32 SAP RFC Interface (Polling)

2025-04-11T09:03:15Z

Odelice:

[[de:HVS32_SAP_RFC_Schnittstelle_(Automatik-Polling)]]

= Requirements =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 or higher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Functional description =
The DataGatewayServer (DGS) uses the SAP library "JCo" for communication with an SAP system and acts as a JCo server program during automatic polling.

The DGS is the central communication unit through which all data is exchanged between the shipping system and the SAP system. It runs in the context of a service on a Windows server.

Any RFC functions can be implemented in the DGS, which are called from an RFC client (SAP).

A separate RFC module must be used for each HVS32 function. The structure of the RFC module (fields, tables, structures) without implementation must be available in the SAP system on an application server for the DGS - since the metadata of the RFC modules are retrieved at system startup.

The DGS registers itself under a program ID at a SAP gateway (not for a specific SAP system) and waits for incoming RFC calls.

If an RFC call is transmitted from any SAP system to this SAP Gateway with the option "Connection with an already registered program" (with the same program ID), the connection with the DGS takes place.

After executing an RFC function, the DGS waits for further RFC calls from the same or another SAP system.

In the event of an interrupted or terminated RFC connection, the DGS automatically re-registers with the same SAP gateway under the same program ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC server at central SAP gateway.
</gallery>

= Required SAP components/parameters =
* latest version 3 of SAP library Java Connector "JCo" in 64Bit.
* SAP GUI installation on the server where the DataGatewayServer is installed - alternatively a manual adjustment of %SystemRoot%\system32\drivers\etc\services and %SystemRoot%\system32\drivers\etc\hosts.
* SAP RFC User with enough permissions
**For permissions you can start with ''SAP note 460089 - Minimum authorization profiles for external RFC programs''
* a defined destination with connection type T (TCP/IP connection) in the SAP system via transaction SM59
([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
the following parameters are required by the DGS to register with a program ID at a SAP gateway:
{| class="wikitable"
|-
! Parameter !! Description
|-
| jco.server.gwhost || SAP gateway at which the function modules are registered
|-
| jco.server.gwserv || SAP gateway service (port) which is used (e.g. sapgw00)
|-
| jco.server.progid || program ID from SM59 under which the registration takes place
|-
| jco.server.connection_count || Number of simultaneous connections that can be used later by SAP to call the program
|-
| jco.client.ashost || SAP application server on which the structure of the RFC block is located
|-
| jco.client.sysnr || SAP system no.
|-
| jco.client.client || Client ID (SAP)
|-
| jco.client.user || SAP user with rights to execute RFC
|-
| jco.client.passwd || Password
|-
| rfcfunctions || List of function modules provided by the DataGatewayServer to SAP
|}
If load balancing (SAP Message Server) is used on the SAP side for client-side RFC calls, the following must be configured instead of the ashost and sysnr parameters:
{| class="wikitable"
|-
! Parameter !! Description
|-
| jco.client.mshost || IP or name of the SAP Message Server
|-
| jco.client.r3name || System ID of the SAP system
|-
| jco.client.group || Name of the SAP server group
|}

= Available HVS32 functions =
Item data and dangerous goods information must be defined as Table or Struct in the RFC module, as they have a 1:n relationship to the package data.<br>
All parameters which are to be sent to the HVS32 must be written into the import parameters. The feedback from the HVS32 is done in the export parameters. The communication is bidirectional, i.e. the feedback is done synchronously in the same transaction as the request.<br>

Please note that the field descriptions refer only to a standard, which should serve as a suggestion for the interface. Function names, field names /-lengths /-formats may differ in principle, but in this case must be considered/analyzed individually.<br>
<br>
'''[[HVS32 automatic polling functions|Available HVS32 functions]]'''

= Examples =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of RFC module structure for shippingDataRequest</div>
<div class="mw-collapsible-content">
<source>
'Z_HVS_VERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDEN_NR CHAR(20)
ZIEL_ADR_NAME1 CHAR(50)
ZIEL_ADR_NAME2 CHAR(50)
ZIEL_ADR_NAME3 CHAR(50)
ZIEL_ADR_STRASSE CHAR(50)
ZIEL_ADR_LKZ CHAR(5)
ZIEL_ADR_PLZ CHAR(10)
ZIEL_ADR_ORT CHAR(50)
ZIEL_ADR_REGION CHAR(20)
ZIEL_ADR_BAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFON_NR CHAR(20)
FAX_NR CHAR(20)
UST_ID_NR CHAR(20)
ILN_NR CHAR(20)
AUFTRAGGEBER_ID CHAR(10)
VERSANDART_ID CHAR(10)
AVIS_HINWEIS1 CHAR(30)
AVIS_HINWEIS2 CHAR(30)
AVIS_ZUSATZ1 CHAR(20)
AVIS_ZUSATZ2 CHAR(20)
LIEFERSCHEIN_NR CHAR(40)
AUFTRAG_NR CHAR(20)
BESTELL_NR CHAR(20)
WARENWERT CHAR(19)
WW_WAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NN_WAEHRUNG CHAR(3)
NN_VERMERK CHAR(1)
NN_VERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VW_WAEHRUNG CHAR(3)
FRANKATUR_KENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZB_ZOLL CHAR(1)
FRACHTFUEHRER_KD_NR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGS_INHALT CHAR(30)
TERMIN_ART CHAR(1)
TERMIN_DATUM CHAR(10)
TERMIN_ZEIT CHAR(5)
NEUTABSENDER_NAME1 CHAR(30)
NEUTABSENDER_NAME2 CHAR(30)
NEUTABSENDER_NAME3 CHAR(30)
NEUTABSENDER_STRASSE CHAR(30)
NEUTABSENDER_LKZ CHAR(3)
NEUTABSENDER_PLZ CHAR(10)
NEUTABSENDER_ORT CHAR(30)
RECHNUNGS_EMPF_NAME1 CHAR(50)
RECHNUNGS_EMPF_NAME2 CHAR(50)
RECHNUNGS_EMPF_NAME3 CHAR(50)
RECHNUNGS_EMPF_STRASSE CHAR(50)
RECHNUNGS_EMPF_LKZ CHAR(5)
RECHNUNGS_EMPF_PLZ CHAR(10)
RECHNUNGS_EMPF_ORT CHAR(50)
POST_LEITCODE CHAR(15)
POST_ZIEL_FRACHTZENT CHAR(5)
FRACHT_BRIEF CHAR(20)
GEWICHT CHAR(9)
NETTO_GEWICHT CHAR(9)
PACK_STK_GES CHAR(10)
PACK_STK_NR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECK_LAENGE CHAR(10)
PACKSTUECK_BREITE CHAR(10)
PACKSTUECK_HOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECK_ID CHAR(15)
ANZAHL_ARTIKEL CHAR(10)
ZUSATZ_ZEILE1 CHAR(150)
ZUSATZ_ZEILE2 CHAR(150)
FREI_AVIS1 CHAR(62)
FREI_AVIS2 CHAR(62)
HV_ELEKTRONIK_ARTIKEL CHAR(1)
EMPF_EMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
UNNR CHAR(4)
KLASSE CHAR(6)
VPG CHAR(5)
K_CODE CHAR(5)
BEZEICHNUNG CHAR(110)
MENGE CHAR(9)
BEGRENZTE_MENGE CHAR(1)
VERP_ANZAHL CHAR(10)
VERPACKUNGSART CHAR(8)
NEBEN_GEFAHR CHAR(20)
BUCHST640 CHAR(1)
MENGEN_EINHEIT CHAR(2)
BEFOERD_KAT CHAR(10)
FAKTOR CHAR(10)
NETTO_EXPL_MASSE CHAR(9)
TUNNEL_B_CODE CHAR(10)
FREIGEST_MENGE CHAR(1)
FF_CODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKING_NR CHAR(35)
VERSAND_SENDUNGS_NR CHAR(20)
DRUCK_DATE_TIME CHAR(10)
AUSGANG_DATE_TIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHR_WAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)

}
</source>
</div></div>

= FAQ / Troubleshooting =
=== Define destination via SM59 ===
To set up an RFC connection in SAP, which is intended for the connection of the HVS32 shipping system, please proceed as follows:
# Go to transaction sm59
# Select the type T (TCP/IP connections) '''[Abb.1]'''
# Create a new connection with the "create" button
# Specify an RFC destination (e.g. "RFC_HVS32")
# Set the activation type to "Registered server program
# Set a program ID (e.g. "HVS32") '''[Abb.2]'''
# Open the "MDMP & Unicode" tab
# Set the communication type to "Unicode" '''[Abb.3]''''
# Save the settings
# You can test the connection via "Connection Test" once the DataGatewayServer is installed on the target system and started as a service '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2025-04-11T09:01:08Z

Odelice: /* Voraussetzungen */

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)

}
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2025-04-11T09:00:56Z

Odelice: /* Notwendige SAP-Komponenten/-Parameter */

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.6.0.550 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)

}
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP IDOC Schnittstelle (Automatik-Polling)

2025-04-11T09:00:45Z

Odelice: /* Notwendige SAP-Komponenten/-Parameter */

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP IDoc Server, (optional für Rückmeldungen via IDoc: SAP IDoc Client)
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Die Daten werden im IDoc-Format über das auf TCP/IP basierende SAP-RFC-Protokoll (Remote Function Call) vom DGS empfangen. Je HVS32-Funktion muss ein eigener IDoc Type verwendet werden. Die IDoc-Typen können sowohl Basistypen, individualisierte Basistypen als auch komplett individuelle IDocs sein.<br>
<br>
Damit vom SAP-System IDocs an den DataGatewayServer gesendet werden können, registriert sich dieser selbständig als externes RFC-Server-Programm (unter einer Programm-ID) bei einem SAP-Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.<br>
<br>
Nach dem Erzeugen des IDoc, wird dieses über einen transaktionsbasierten RFC an den DataGatewayServer gesendet. Dabei wird nicht auf eine Antwort gewartet, das heißt der Aufruf erfolgt asynchron.<br>
Sobald das IDoc im DGS ankommt, wird anhand der enthaltenen Steuerinformationen eine passende HVS32-Station zur Verarbeitung gesucht. Falls keine Station zur Verfügung steht, wird das IDoc als fehlerhaft protokolliert und verworfen. Im anderen Fall werden die Daten in das spezielle HVS32-XML-Format umgesetzt, das schließlich an die ausgewählte HVS32-Station zur Verarbeitung weitergereicht wird.
Im HVS32 findet eine sequentielle Verarbeitung aller ankommenden Aufträge statt. Somit kann eine Station nicht mehrere Aufträge parallel verarbeiten. Anschließend werden die Rückmeldedaten an den DGS gegeben, welcher anhand dieser Information das IDoc als erledigt markiert.<br>
Wie im Ablauf zu sehen ist, wird keine direkte Rückmeldung an SAP geschickt. Der Grund dafür liegt bei der asynchronen Verarbeitung von IDocs, wodurch kein Anfrage-Antwort-Dialog zwischen dem Versandsystem und dem SAP-System zustande kommt. Dennoch besteht grundsätzlich die Möglichkeit die Rückmeldedaten (wie z.B. Paketnummer) über ein separates IDoc nach der Verarbeitung, ebenfalls asynchron, an SAP zu senden.

<gallery>
Sapidocablauf.jpg|Ablauf: DGS SAP/IDoc Server
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in 64Bit und "JIDocLib"
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ (64bit) voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
**alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
**Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* SAP RFC User mit entsprechender Berechtigung
** Bzgl. der Berechtigung kann man mit dem ''SAP note 460089 - Minimum authorization profiles for external RFC programs'' anfangen
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Server / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| IDocTypes || Liste von IDoc-Typen, die vom DataGatewayServer interpretiert werden sollen
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im IDoc als Untersegment des Packstück-Segments definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Die Kommunikation ist unidirektional, d.h. eine Rückmeldung aus dem HVS32 erfolgt nicht bzw. asynchron in einer eigenen Trasaktion<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
* DELVRY05, DELVRY07
* DESADV01

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP IDOC Schnittstelle (Automatik-Polling)

2025-04-10T07:58:24Z

Odelice:

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.40 oder höher
|-
| DGS-Plugins || HVS32Client, SAP IDoc Server, (optional für Rückmeldungen via IDoc: SAP IDoc Client)
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Die Daten werden im IDoc-Format über das auf TCP/IP basierende SAP-RFC-Protokoll (Remote Function Call) vom DGS empfangen. Je HVS32-Funktion muss ein eigener IDoc Type verwendet werden. Die IDoc-Typen können sowohl Basistypen, individualisierte Basistypen als auch komplett individuelle IDocs sein.<br>
<br>
Damit vom SAP-System IDocs an den DataGatewayServer gesendet werden können, registriert sich dieser selbständig als externes RFC-Server-Programm (unter einer Programm-ID) bei einem SAP-Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.<br>
<br>
Nach dem Erzeugen des IDoc, wird dieses über einen transaktionsbasierten RFC an den DataGatewayServer gesendet. Dabei wird nicht auf eine Antwort gewartet, das heißt der Aufruf erfolgt asynchron.<br>
Sobald das IDoc im DGS ankommt, wird anhand der enthaltenen Steuerinformationen eine passende HVS32-Station zur Verarbeitung gesucht. Falls keine Station zur Verfügung steht, wird das IDoc als fehlerhaft protokolliert und verworfen. Im anderen Fall werden die Daten in das spezielle HVS32-XML-Format umgesetzt, das schließlich an die ausgewählte HVS32-Station zur Verarbeitung weitergereicht wird.
Im HVS32 findet eine sequentielle Verarbeitung aller ankommenden Aufträge statt. Somit kann eine Station nicht mehrere Aufträge parallel verarbeiten. Anschließend werden die Rückmeldedaten an den DGS gegeben, welcher anhand dieser Information das IDoc als erledigt markiert.<br>
Wie im Ablauf zu sehen ist, wird keine direkte Rückmeldung an SAP geschickt. Der Grund dafür liegt bei der asynchronen Verarbeitung von IDocs, wodurch kein Anfrage-Antwort-Dialog zwischen dem Versandsystem und dem SAP-System zustande kommt. Dennoch besteht grundsätzlich die Möglichkeit die Rückmeldedaten (wie z.B. Paketnummer) über ein separates IDoc nach der Verarbeitung, ebenfalls asynchron, an SAP zu senden.

<gallery>
Sapidocablauf.jpg|Ablauf: DGS SAP/IDoc Server
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in 64Bit und "JIDocLib"
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ (64bit) voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
**alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
**Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Server / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| IDocTypes || Liste von IDoc-Typen, die vom DataGatewayServer interpretiert werden sollen
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im IDoc als Untersegment des Packstück-Segments definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Die Kommunikation ist unidirektional, d.h. eine Rückmeldung aus dem HVS32 erfolgt nicht bzw. asynchron in einer eigenen Trasaktion<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
* DELVRY05, DELVRY07
* DESADV01

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP IDOC Schnittstelle (Automatik-Polling)

2025-04-10T07:57:41Z

Odelice:

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.6.0.550 oder höher
|-
| DGS-Plugins || HVS32Client, SAP IDoc Server, (optional für Rückmeldungen via IDoc: SAP IDoc Client)
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Die Daten werden im IDoc-Format über das auf TCP/IP basierende SAP-RFC-Protokoll (Remote Function Call) vom DGS empfangen. Je HVS32-Funktion muss ein eigener IDoc Type verwendet werden. Die IDoc-Typen können sowohl Basistypen, individualisierte Basistypen als auch komplett individuelle IDocs sein.<br>
<br>
Damit vom SAP-System IDocs an den DataGatewayServer gesendet werden können, registriert sich dieser selbständig als externes RFC-Server-Programm (unter einer Programm-ID) bei einem SAP-Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.<br>
<br>
Nach dem Erzeugen des IDoc, wird dieses über einen transaktionsbasierten RFC an den DataGatewayServer gesendet. Dabei wird nicht auf eine Antwort gewartet, das heißt der Aufruf erfolgt asynchron.<br>
Sobald das IDoc im DGS ankommt, wird anhand der enthaltenen Steuerinformationen eine passende HVS32-Station zur Verarbeitung gesucht. Falls keine Station zur Verfügung steht, wird das IDoc als fehlerhaft protokolliert und verworfen. Im anderen Fall werden die Daten in das spezielle HVS32-XML-Format umgesetzt, das schließlich an die ausgewählte HVS32-Station zur Verarbeitung weitergereicht wird.
Im HVS32 findet eine sequentielle Verarbeitung aller ankommenden Aufträge statt. Somit kann eine Station nicht mehrere Aufträge parallel verarbeiten. Anschließend werden die Rückmeldedaten an den DGS gegeben, welcher anhand dieser Information das IDoc als erledigt markiert.<br>
Wie im Ablauf zu sehen ist, wird keine direkte Rückmeldung an SAP geschickt. Der Grund dafür liegt bei der asynchronen Verarbeitung von IDocs, wodurch kein Anfrage-Antwort-Dialog zwischen dem Versandsystem und dem SAP-System zustande kommt. Dennoch besteht grundsätzlich die Möglichkeit die Rückmeldedaten (wie z.B. Paketnummer) über ein separates IDoc nach der Verarbeitung, ebenfalls asynchron, an SAP zu senden.

<gallery>
Sapidocablauf.jpg|Ablauf: DGS SAP/IDoc Server
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in 64Bit und "JIDocLib"
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ (64bit) voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
**alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
**Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Server / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| IDocTypes || Liste von IDoc-Typen, die vom DataGatewayServer interpretiert werden sollen
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im IDoc als Untersegment des Packstück-Segments definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Die Kommunikation ist unidirektional, d.h. eine Rückmeldung aus dem HVS32 erfolgt nicht bzw. asynchron in einer eigenen Trasaktion<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
* DELVRY05, DELVRY07
* DESADV01

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

Interfaces: Security Levels and Authentication

2025-02-14T09:23:09Z

Odelice:

[[en:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)<br>
Please make sure that the certificate chain in the provided certificate is complete.<br><br>
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.39''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."

To request the initial tokens we offer multiple options.

You can either request the tokens via Authorization Basic, in which the ClientID + ClientSecret are exposed in the HTTP header.<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>

Another option is to request the tokens via JWT. In this option the ClientID is within the payload and the JWT is signed with the ClientSecret. This option offers additional securities, since the ClientSecret itself is never exposed.<div class="toccolours mw-collapsible mw-collapsed"><div>'''Example of token request (generating access and refresh tokens with JWT)'''</div><div class="mw-collapsible-content">
For the token request via JWT (jwt-bearer) the ClientID is within the payload as ''sub'' and signed with ClientSecret. The JWT must be transmitted in the HTTP header ''client_assertion''. To use JWT authentification the HTTP header ''client_assertion_type'' with value ''jwt-bearer''.

Additionally, the '''grant_type''' with the value ''client_credentials'' is necessary for this function.

In this example following '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - was used.

Following '''ClientSecret''' was used - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight></div></div><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

==Managing Client Credentials in the DGS==
The client credentials are managed in the DataGatewayServer. You can create new credentials or delete existing ones.<br>
To do this, start the Credentials Configurator (.exe) located in the installation directory of the DataGatewayServer.
===Config===
[[File:Authorization Credentials 001.png|thumb|right|Credentials Configurator - config]]
On this screen, general configurations can be made.
* '''check invalid logins'''<br>If this option is active, the number of invalid authentication attempts will be counted. After '''max invalid logins''' within '''timespan in seconds''', all credentials will be locked.
* '''execute CODE RED for OAuth2.0 CC'''<br>If this option is active when using OAuth2.0 CC, a '''CODE RED''' will be triggered if a REFRESH TOKEN is reused multiple times. This action deactivates all ACCESS and REFRESH TOKENS, requiring new tokens to be requested via client credentials. Additionally, the DGS Configurator can be configured to send an email notification in the event of a CODE RED.
* '''Lock Credentials / Unlock Credentials'''<br>With this button, all credentials can be locked or unlocked. For instance, if all client credentials were locked due to the '''check invalid logins''' option, they can be unlocked here. This action takes effect immediately without needing to save.
* Save<br>This button persistently saves the settings and credentials. The options and credentials only become active after saving. A DGS restart is not required.
===Managing Credentials===
[[File:Authorization Credentials 002.png|thumb|right|Credentials Configurator - OAuth2.0 CC]]
[[File:Authorization Credentials 003.png|thumb|right|Enter Username / ClientID]]
[[File:Authorization Credentials 004.png|thumb|right|Show Credentials Dialog]]
To manage your credentials, select the appropriate tab for the authentication method configured in the DGS (e.g., OAuth2.0 CC).
* '''add'''<br>create new credentials. Note that the password or client secret will only be displayed once in a dialog. Be sure to copy it to a secure location and ensure no unauthorized persons have access to it.
* '''change secret''' or '''change password'''<br>assign a new password or client secret. As with the add function, the password or client secret will only be displayed once in a dialog.
* '''remove'''<br>remove the selected credentials.

Interfaces: Security Levels and Authentication

2025-02-14T09:22:46Z

Odelice: jwt for oauth2

[[null]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)<br>
Please make sure that the certificate chain in the provided certificate is complete.<br><br>
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.39''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."

To request the initial tokens we offer multiple options.

You can either request the tokens via Authorization Basic, in which the ClientID + ClientSecret are exposed in the HTTP header.<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>

Another option is to request the tokens via JWT. In this option the ClientID is within the payload and the JWT is signed with the ClientSecret. This option offers additional securities, since the ClientSecret itself is never exposed.<div class="toccolours mw-collapsible mw-collapsed"><div>'''Example of token request (generating access and refresh tokens with JWT)'''</div><div class="mw-collapsible-content">
For the token request via JWT (jwt-bearer) the ClientID is within the payload as ''sub'' and signed with ClientSecret. The JWT must be transmitted in the HTTP header ''client_assertion''. To use JWT authentification the HTTP header ''client_assertion_type'' with value ''jwt-bearer''.

Additionally, the '''grant_type''' with the value ''client_credentials'' is necessary for this function.

In this example following '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - was used.

Following '''ClientSecret''' was used - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight></div></div><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

==Managing Client Credentials in the DGS==
The client credentials are managed in the DataGatewayServer. You can create new credentials or delete existing ones.<br>
To do this, start the Credentials Configurator (.exe) located in the installation directory of the DataGatewayServer.
===Config===
[[File:Authorization Credentials 001.png|thumb|right|Credentials Configurator - config]]
On this screen, general configurations can be made.
* '''check invalid logins'''<br>If this option is active, the number of invalid authentication attempts will be counted. After '''max invalid logins''' within '''timespan in seconds''', all credentials will be locked.
* '''execute CODE RED for OAuth2.0 CC'''<br>If this option is active when using OAuth2.0 CC, a '''CODE RED''' will be triggered if a REFRESH TOKEN is reused multiple times. This action deactivates all ACCESS and REFRESH TOKENS, requiring new tokens to be requested via client credentials. Additionally, the DGS Configurator can be configured to send an email notification in the event of a CODE RED.
* '''Lock Credentials / Unlock Credentials'''<br>With this button, all credentials can be locked or unlocked. For instance, if all client credentials were locked due to the '''check invalid logins''' option, they can be unlocked here. This action takes effect immediately without needing to save.
* Save<br>This button persistently saves the settings and credentials. The options and credentials only become active after saving. A DGS restart is not required.
===Managing Credentials===
[[File:Authorization Credentials 002.png|thumb|right|Credentials Configurator - OAuth2.0 CC]]
[[File:Authorization Credentials 003.png|thumb|right|Enter Username / ClientID]]
[[File:Authorization Credentials 004.png|thumb|right|Show Credentials Dialog]]
To manage your credentials, select the appropriate tab for the authentication method configured in the DGS (e.g., OAuth2.0 CC).
* '''add'''<br>create new credentials. Note that the password or client secret will only be displayed once in a dialog. Be sure to copy it to a secure location and ensure no unauthorized persons have access to it.
* '''change secret''' or '''change password'''<br>assign a new password or client secret. As with the add function, the password or client secret will only be displayed once in a dialog.
* '''remove'''<br>remove the selected credentials.

Schnittstellen: Security Levels und Authentifizierung

2025-02-14T09:05:37Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>
Stellen Sie sicher, dass falls vorhanden die Zertifikatskette vollständig im Zertifikat hinterlegt ist.<br><br>
Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.39''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>Bei der initialen Tokenanfrage stehen verschiedene zwei Möglichkeiten zum Abrufen bereit.

Zum einen kann man die Token über die Authorization Basic anfragen, bei welchem die ClientID + ClientSecret im HTTP-Header mitgegeben werden.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>Eine weitere Variante die Token abzurufen ist über einen JWT. Bei dieser Methode wird die ClientID im Payload vom JWT übermittelt und das JWT selbst mit dem ClientSecret signiert. Diese Möglichkeit bietet eine zusätzliche Sicherheit, da dass ClientSecret selbst nie exposed wird.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken über JWT generieren)</div>
<div class="mw-collapsible-content">
Bei der Token-Anfrage '''JWT (jwt-bearer)''' muss die Client-ID und das Client-Secret in einem JWT übermittelt werden. Dabei wird die '''ClientID''' im JWT Payload als "sub" übermittelt und mit dem ClientSecret signiert. Das JWT wird Im HTTP-Header als ''client_assertion'' übermittelt. Die Anfrage über das JWT erfolgt über den HTTP-Header ''client_assertion_type''.

Zusätzlich ist für diese Funktion der '''grant_type''' mit dem Wert ''client_credentials'' notwendig.

In diesem Beispiel wurde die '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - verwendet.

Das '''ClientSecret''' lautet - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können Sie die die ausgewählten Credentials entfernen.

Schnittstellen: Security Levels und Authentifizierung

2025-02-14T09:04:51Z

Odelice: tokenanfrage über jwt

[[null]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>
Stellen Sie sicher, dass falls vorhanden die Zertifikatskette vollständig im Zertifikat hinterlegt ist.<br><br>
Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.39''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>Bei der initialen Tokenanfrage stehen verschiedene zwei Möglichkeiten zum Abrufen bereit.

Zum einen kann man die Token über die Authorization Basic anfragen, bei welchem die ClientID + ClientSecret im HTTP-Header mitgegeben werden.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>Eine weitere Variante die Token abzurufen ist über einen JWT. Bei dieser Methode wird die ClientID im Payload vom JWT übermittelt und das JWT selbst mit dem ClientSecret signiert. Diese Möglichkeit bietet eine zusätzliche Sicherheit, da dass ClientSecret selbst nie exposed wird.
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken über JWT generieren)</div>
<div class="mw-collapsible-content">
Bei der Token-Anfrage '''JWT (jwt-bearer)''' muss die Client-ID und das Client-Secret in einem JWT übermittelt werden. Dabei wird die '''ClientID''' im JWT Payload als "sub" übermittelt und mit dem ClientSecret signiert. Das JWT wird Im HTTP-Header als ''client_assertion'' übermittelt. Die Anfrage über das JWT erfolgt über den HTTP-Header ''client_assertion_type''.

Zusätzlich ist für diese Funktion der '''grant_type''' mit dem Wert ''client_credentials'' notwendig.

In diesem Beispiel wurde die '''ClientID''' - ''huF3sPp5g5zUXP70bQ3O'' - verwendet.

Das '''ClientSecret''' lautet - ''yX2[K2DC*CjvUI3Us!eCrM@B%5OHJ@U5JCw+)Jv1b+3@1f[?YOw]mxmc(Aes)K5N''
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
client_assertion_type: jwt-bearer
client_assertion: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJodUYzc1BwNWc1elVYUDcwYlEzTyIsIm5hbWUiOiJIZWlkbGVyIFN0cmljaGNvZGUgR21iSCBURVNUIiwiaWF0IjoxODE2MjM5MDIyfQ.xKwD4wnQud55LVqvs47Sy0jKhpbxb0JVZtgMWWbjNKo
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können Sie die die ausgewählten Credentials entfernen.

Interfaces: Security Levels and Authentication

2024-11-21T07:01:35Z

Odelice: /* Authentication */

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)<br>
Please make sure that the certificate chain in the provided certificate is complete.<br><br>
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.39''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Schnittstellen: Security Levels und Authentifizierung

2024-11-21T06:59:47Z

Odelice: /* Authentifizierung */

[[en:Interfaces:_Security_Levels_and_Authentication]]
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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>
Stellen Sie sicher, dass falls vorhanden die Zertifikatskette vollständig im Zertifikat hinterlegt ist.<br><br>
Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.39''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können die die ausgewählten Credentials entfernen.

Interfaces: Security Levels and Authentication

2024-11-19T10:17:07Z

Odelice: /* Authentication */

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.39''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Schnittstellen: Security Levels und Authentifizierung

2024-11-19T10:16:56Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]
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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>

Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.39''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können die die ausgewählten Credentials entfernen.

Interfaces: Security Levels and Authentication

2024-11-19T08:25:22Z

Odelice:

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)
The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.31''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Interfaces: Security Levels and Authentication

2024-11-19T08:19:59Z

Odelice:

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]
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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.31''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Schnittstellen: Security Levels und Authentifizierung

2024-11-19T08:19:52Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]
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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>

Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.31''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können die die ausgewählten Credentials entfernen.

Interfaces: Security Levels and Authentication

2024-11-19T08:19:43Z

Odelice:

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]

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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.31''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Schnittstellen: Security Levels und Authentifizierung

2024-11-19T08:19:20Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]

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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>

Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.31''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können die die ausgewählten Credentials entfernen.

Interfaces: Security Levels and Authentication

2024-11-19T08:18:46Z

Odelice:

[[null]]

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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

* '''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b
* '''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.31''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Interfaces: Security Levels and Authentication

2024-11-19T08:18:06Z

Odelice:

[[null]]

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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

For encryption, a certificate with the corresponding private key is required. The following certificate formats are supported:

'''Certificates:''' *.crt, *.cer, *.pem, *.der, or *.p7b

'''Private Key:''' *.der, *.pem, or *.ssh (OpenSSH)

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.31''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Schnittstellen: Security Levels und Authentifizierung

2024-11-19T08:16:36Z

Odelice:

[[null]]

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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.

Für die Verschlüsselung wird jeweils ein Zertifikat mit zugehörigem Private Key benötigt. Die folgenden Zertifikatsformate werden unterstützt:

* '''Zertifikate:''' *.crt, *.cer, *.pem, *.der oder *.p7b
* '''Private Key:''' *.der, *.pem, oder *.ssh (OpenSSH)<br>

Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.31''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

==Client Credentials im DGS verwalten==
Die Client Credentials werden im DataGatewayServer verwaltet. Dort können neue Zugangsdaten angelegt oder bestehende gelöscht werden.<br>
Dazu muss im Installationsverzeichnis des DataGatewayServer der Credentials-Configurator(.exe) gestartet werden.
===Config===
[[Datei:Authorization Credentials 001.png|mini|rechts|Credentials Configurator - config]]
Hier können allgemeine Konfigurationen vorgenommen werden.
* '''check invalid logins'''<br>Wenn diese Option aktiv ist, wird die Anzahl der ungültigen Authentifizierungen gezählt und nach '''max invalid logins''' innerhalb von '''timespan in seconds''' werden alle Credentials gesperrt
* '''execute CODE RED for OAuth2.0 CC'''<br>Wenn diese Option bei der Nutzung von OAuth2.0 CC aktiv ist, wird bei mehrfachen verwenden eines REFRESH TOKENS ein '''CODE RED''' ausgelöst. Hierbei werden alle ACCESS und REFRESH TOKENS deaktiviert und es müssen neue Tokens via Client Credentials angefordert werden. Zusätzlich kann im DGS Konfigurator das Versenden einer E-Mail bei einem CODE RED konfiguriert werden.
* '''Lock Credentials / Unlock credentials'''<br>Über diesen Button können alle Credentials gesperrt oder entsperrt werden. Wenn z.b. durch die Option '''check invalid logins''' alle Client Credentials gesperrt wurden, können diese somit wieder entsperrt werden. Diese Option greift sofort, ohne speichern.
* Save<br>Mit diesem Button werden die Einstellungen und Credentials persistent gespeichert. Erst nach dem Speichern werden die Optionen und Credentials aktiv. Ein DGS Neustart ist nicht notwendig.
===Credentials verwalten===
[[Datei:Authorization Credentials 002.png|mini|rechts|Credentials Configurator - OAuth2.0 CC]]
[[Datei:Authorization Credentials 003.png|mini|rechts|Enter Username / ClientID]]
[[Datei:Authorization Credentials 004.png|mini|rechts|Show Credentials Dialog]]
Um Ihre Credentials zu verwalten, wählen Sie den passenden Reiter zu Ihrer im DGS konfigurierten Authentifizierungs-Methode (z.B. OAuth2.0 CC)
* '''add'''<br>Hier können Sie neue Credentials anlegen. Beachten Sie, dass das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt wird. Kopieren Sie es daher in einen sicheren Platz und stellen Sie sicher, dass keine unautorisierten Personen darauf Zugriff haben.
* '''change secret''' bzw. '''change password'''<br>Hier können Sie ein neues Passwort bzw. Client Secret vergeben. Wie bei der add Funktion, wird das Passwort bzw. das Client-Secret nur einmalig in einem Dialog angezeigt.
* '''remove'''<br>Hier können die die ausgewählten Credentials entfernen.

HVS32 RESTv2 Schnittstelle (Automatik-Polling)

2024-07-04T07:11:26Z

Odelice: Die Seite wurde neu angelegt: „en:HVS32_RESTv2_Interface_(Polling) '''WORK IN PROGRESS!!!''' <!-- ------------------------------------------------------------------------------- Vorausse…“

[[en:HVS32_RESTv2_Interface_(Polling)]]
'''WORK IN PROGRESS!!!'''

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.8.32 oder höher
|-
| DGS-Plugins || HVS32Client, REST Server
|}


= OpenAPI / Swagger =
[https://interface.heidler-strichcode.de?version=v2 RESTv2]


= Funktionsbeschreibung =
Bei der RESTv2-Schnittstelle stellt der DataGatewayServer (DGS) einen-REST Server mit folgenden [[#Übersicht der Funktionen|Funktionen]] zur Verfügung.
Dieser ist in der Standardkonfiguration unter '''http://<Servername>:<Port>/v2/hsc/''' erreichbar. Dabei wird der Port 8081 verwendet, welcher bei Bedarf geändert werden kann.

Kommunikation / Schnittstellen

2024-07-04T06:58:25Z

Odelice:

[[en:Communication_Interfaces]]
= HVS32 Verarbeitungs-Schnittstellen =
Bitte beachten Sie, dass alle Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Feldnamen /-längen /-formate können prinzipiell abweichen (außer Automatik-Polling SOAP/REST), müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.

=== Automatik-Polling ===
Im Automatik-Polling Modus arbeitet das Versandsystem HVS32 komplett im Hintergrund und wird vom Vorsystem via Schnittstelle angesprochen.
Hierbei können Funktionen wie Versandlabeldruck, Packstückstorno, Tagesabschluss, etc. getriggert werden. Eine Benutzerseitige Eingabe von Daten ist nicht erforderlich.<br>

Die Daten können mittels folgenden Schnittstellen vom Vorsystem an das HVS32 übertragen werden:

*[[HVS32_File_Schnittstelle_(Automatik-Polling)|File (CSV, SDF, etc.)]]
*[[HVS32_REST_Schnittstelle_(Automatik-Polling)|RESTv1]]

*[https://interface.heidler-strichcode.de?version=v2 RESTv2]
*[[HVS32_SOAP_Schnittstelle_(Automatik-Polling)|SOAP]]

*[[HVS32_JDBC_Schnittstelle_(Automatik-Polling)|JDBC]]
*[[HVS32_SAP_RFC_Schnittstelle_(Automatik-Polling)|SAP RFC]]
*[[HVS32_SAP_IDOC_Schnittstelle_(Automatik-Polling)|SAP IDoc]]
*[[HVS32_Ehrhardt_%2B_Partner_LFS_Schnittstelle_(Automatik-Polling)|Ehrhardt + Partner LFS]]
*[[HVS32_PSI_REST_Schnittstelle_(Automatik-Polling)|PSI-REST]]


=== Interaktiv ===
Bei einer interaktiven Verarbeitung werden die Versand-Daten in einer Erfassungsmaske des HVS32 eingetragen. Die Versand-Daten können bei diversen [[HVS32_Funktionen_Interaktiv|interaktiven Aktionen]] am Vorsystem angefragt bzw. an das Vorsystem zurück gemeldet werden.<br>
Dadurch hat man zum Beispiel die Möglichkeit, eine Datenanfrage nach Scannen eines Lieferscheins, Rückmeldung nach Druck eines Etiketts, Rückmeldung nach Tagesabschluss, Rückmeldung nach Storno/Freigabe durchzuführen.<br>

Mit folgendenen Schnittstellen kann bei der interaktiven Verarbeitung auf die Versand-Daten des Vorsystems zugegriffen werden:


*[[HVS32_REST_Schnittstelle_(Interaktiv)|REST]]
*[[HVS32_SOAP_Schnittstelle_(Interaktiv)|SOAP]]
*[[HVS32_JDBC_Schnittstelle_(Interaktiv)|JDBC]]
*[[HVS32_SAP_RFC_Schnittstelle_(Interaktiv)|SAP RFC]]

=== Security Levels ===
Wenn das Versandsystem HVS32 ö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.<br>
*[[Schnittstellen:_Security_Levels_und_Authentifizierung|Schnittstellen: Security Levels und Authentifizierung]]

= Sonstige Schnittstellen =
*[[Statusdaten_Export_Standard_Schnittstelle|StatusdatenManager (SEM)]]

HVS32 SAP IDOC Schnittstelle (Automatik-Polling)

2024-05-27T08:34:06Z

Odelice:

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.6.0.550 oder höher
|-
| DGS-Plugins || HVS32Client, SAP IDoc Server, (optional für Rückmeldungen via IDoc: SAP IDoc Client)
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Die Daten werden im IDoc-Format über das auf TCP/IP basierende SAP-RFC-Protokoll (Remote Function Call) vom DGS empfangen. Je HVS32-Funktion muss ein eigener IDoc Type verwendet werden. Die IDoc-Typen können sowohl Basistypen, individualisierte Basistypen als auch komplett individuelle IDocs sein.<br>
<br>
Damit vom SAP-System IDocs an den DataGatewayServer gesendet werden können, registriert sich dieser selbständig als externes RFC-Server-Programm (unter einer Programm-ID) bei einem SAP-Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.<br>
<br>
Nach dem Erzeugen des IDoc, wird dieses über einen transaktionsbasierten RFC an den DataGatewayServer gesendet. Dabei wird nicht auf eine Antwort gewartet, das heißt der Aufruf erfolgt asynchron.<br>
Sobald das IDoc im DGS ankommt, wird anhand der enthaltenen Steuerinformationen eine passende HVS32-Station zur Verarbeitung gesucht. Falls keine Station zur Verfügung steht, wird das IDoc als fehlerhaft protokolliert und verworfen. Im anderen Fall werden die Daten in das spezielle HVS32-XML-Format umgesetzt, das schließlich an die ausgewählte HVS32-Station zur Verarbeitung weitergereicht wird.
Im HVS32 findet eine sequentielle Verarbeitung aller ankommenden Aufträge statt. Somit kann eine Station nicht mehrere Aufträge parallel verarbeiten. Anschließend werden die Rückmeldedaten an den DGS gegeben, welcher anhand dieser Information das IDoc als erledigt markiert.<br>
Wie im Ablauf zu sehen ist, wird keine direkte Rückmeldung an SAP geschickt. Der Grund dafür liegt bei der asynchronen Verarbeitung von IDocs, wodurch kein Anfrage-Antwort-Dialog zwischen dem Versandsystem und dem SAP-System zustande kommt. Dennoch besteht grundsätzlich die Möglichkeit die Rückmeldedaten (wie z.B. Paketnummer) über ein separates IDoc nach der Verarbeitung, ebenfalls asynchron, an SAP zu senden.

<gallery>
Sapidocablauf.jpg|Ablauf: DGS SAP/IDoc Server
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in 64Bit
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ (64bit) voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
**alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
**Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Server / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| IDocTypes || Liste von IDoc-Typen, die vom DataGatewayServer interpretiert werden sollen
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im IDoc als Untersegment des Packstück-Segments definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Die Kommunikation ist unidirektional, d.h. eine Rückmeldung aus dem HVS32 erfolgt nicht bzw. asynchron in einer eigenen Trasaktion<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
* DELVRY05, DELVRY07
* DESADV01

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

HVS32 SAP RFC Schnittstelle (Automatik-Polling)

2024-05-27T08:33:13Z

Odelice:

[[en:HVS32_SAP_RFC_Interface_(Polling)]]

= Voraussetzungen =
{| class="wikitable"
|-
| DGS-Version || 3.6.0.550 oder höher
|-
| DGS-Plugins || HVS32Client, SAP RFC Server
|}

= Funktionsbeschreibung =
Der DataGatewayServer (DGS) nutzt für die Kommunikation mit einem SAP System die SAP Bibliothek "JCo" und agiert beim Automatik Polling als JCo Server-Programm.<br>

Der DGS ist die zentrale Kommunikationseinheit, über die sämtliche Daten zwischen dem Versandsystem und dem SAP-System ausgetauscht werden. Er läuft in Form eines Dienstes auf einem Windows-Server.<br>

Es können beliebige RFC Funktionen im DGS implementiert werden, welche von einem RFC-Client (SAP) aus aufgerufen werden. <br>

Je HVS32 Funktion muss ein separater RFC Baustein genutzt werden. Die Struktur des RFC-Bausteins (Felder, Tabellen, Strukturen) ohne Implementierung muss im SAP System auf einem Applikationsserver für den DGS verfügbar sein - da die Metadaten der RFC Bausteine bei Systemstart abgerufen werden. <br>

Der DGS registriert sich selbst unter einer Programm-ID an einem SAP Gateway (nicht für ein spezifisches SAP-System) und wartet auf eingehende RFC-Aufrufe.<br>

Wenn ein RFC-Aufruf von einem beliebigen SAP-System an dieses SAP Gateway mit der Option "Verbindung mit einem bereits registrierten Programm" (mit der selben Programm-ID) übermittelt wird, findet die Verbindung mit dem DGS statt.<br>

Nach dem Ausführen einer RFC-Funktion wartet der DGS auf weitere RFC-Aufrufe vom selben oder einem anderen SAP-System.<br>

Im Falle einer unterbrochenen oder beendeten RFC-Verbindung registriert sich der DGS automatisch wieder am selben SAP Gateway unter der selben Programm-ID.

<gallery>
RFCServerCentralSAPGateway.png|DGS SAP/RFC Server an zentralem SAP Gateway
</gallery>

= Notwendige SAP-Komponenten/-Parameter =
* neueste Version 3 der SAP Bibliothek Java Connector "JCo" in '''64Bit''' (sapjco3.jar + sapjco3.dll)
** Die Verwendung vom SAP JCo 3.1 setzt die Installation vom Microsoft Visual Studio 2013 C/C++ '''64bit''' voraus.
* SAP GUI Installation auf dem HVS32 Server, auf welchem die Heidler Applikationen installiert sind
** alternativ eine manuelle Anpassung der %SystemRoot%\system32\drivers\etc\services und %SystemRoot%\system32\drivers\etc\hosts
** Die SAP GUI installiert unter anderem auch die Microsoft Visual Studio komponenente (nach Installation prüfen, ob für die korrekte Version für die eingesetzte SAP JCo vorhanden ist)
* eine definierte Destination mit Verbindungstyp T (TCP/IP-Verbindung) im SAP-System über die Transaktion SM59 ([[#Destination_.C3.BCber_SM59_definieren|siehe Destination über SM59 definieren]])
<br>
folgende Parameter werden vom DGS benötigt, um sich mit einer Programm-ID an einem SAP Gateway zu registrieren:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.server.gwhost || SAP-Gateway (Servername / IP) an welchem die Funktionsbausteine registriert werden
|-
| jco.server.gwserv || SAP-Gateway-Service (Port) der genutzt wird (z.B. sapgw00)
|-
| jco.server.progid || Programm-ID aus der SM59 unter welcher die Registrierung stattfindet
|-
| jco.server.connection_count || Anzahl gleichzeitiger Verbindungen, die später von SAP zum Aufruf genutzt werden können
|-
| jco.client.ashost || SAP-Applikation-Server (Servername / IP) auf welchem sich die Struktur des RFC Bausteins befindet
|-
| jco.client.sysnr || SAP System Nr (Zweistellig nummerisch)
|-
| jco.client.client || Mandanten ID (SAP)
|-
| jco.client.user || SAP-Benutzer mit Rechten zum Ausführen von RFC
|-
| jco.client.passwd || Passwort
|-
| rfcfunctions || Liste aller RFC-Funktionsbausteinen, welche im SAP bereitgestellt werden
|}
Falls für clientseitige RFC-Aufrufe eine Lastverteilung (SAP Message Server) auf Seiten von SAP genutzt wird, muss anstelle der Parameter ashost und sysnr folgendes konfiguriert werden:
{| class="wikitable"
|-
! Parameter !! Beschreibung
|-
| jco.client.mshost || IP oder Name des SAP Message Server
|-
| jco.client.r3name || System ID des SAP-Systems
|-
| jco.client.group || Name der SAP-Servergruppe
|}

= Verfügbare HVS32 Funktionen =
Artikel-Daten und Gefahrgut-Informationen müssen im RFC Baustein als Table oder Struct definiert werden, da diese in einer 1:n Beziehung zu den Packstückdaten stehen.<br>
Alle Parameter, welche an das HVS32 gesendet werden sollen, müssen in die Import-Parameter geschrieben werden. Die Rückmeldung aus dem HVS32 erfolgt in den Export-Parametern. Die Kommunikation ist bidirektional, d.h. die Rückmeldung erfolgt synchron in der gleichen Transaktion wie die Anfrage.<br>

Bitte beachten Sie, dass die Feld-Beschreibungen sich nur auf einen Standard beziehen, welcher als Vorschlag für die Schnittstelle dienen soll. Funktionsnamen, Feldnamen /-längen /-formate können prinzipiell abweichen, müssen in diesem Fall jedoch individuell betrachtet/analysiert werden.<br>
<br>
'''[[HVS32_Automatik-Polling_Funktionen|Verfügbare HVS32 Funktionen]]'''

= Beispiele =
<div class="toccolours mw-collapsible mw-collapsed" style="width:60%; overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für eine RFC Baustein Struktur für die VersandDatenAnfrage</div>
<div class="mw-collapsible-content">
<source>
'ZHVSVERSANDDATENANFRAGE'

IMPORTING
PACKSTUECK STRUCTURE
KUNDENNR CHAR(20)
ZIELADRNAME1 CHAR(50)
ZIELADRNAME2 CHAR(50)
ZIELADRNAME3 CHAR(50)
ZIELADRSTRASSE CHAR(50)
ZIELADRLKZ CHAR(5)
ZIELADRPLZ CHAR(10)
ZIELADRORT CHAR(50)
ZIELADRREGION CHAR(20)
ZIELADRBAHNHOF CHAR(30)
ANSPRECHPARTNER CHAR(20)
TELEFONNR CHAR(20)
FAXNR CHAR(20)
USTIDNR CHAR(20)
ILNNR CHAR(20)
AUFTRAGGEBERID CHAR(10)
VERSANDARTID CHAR(10)
AVISHINWEIS1 CHAR(30)
AVISHINWEIS2 CHAR(30)
AVISZUSATZ1 CHAR(20)
AVISZUSATZ2 CHAR(20)
LIEFERSCHEINNR CHAR(40)
AUFTRAGNR CHAR(20)
BESTELLNR CHAR(20)
WARENWERT CHAR(19)
WWWAEHRUNG CHAR(3)
NACHNAHME CHAR(19)
NNWAEHRUNG CHAR(3)
NNVERMERK CHAR(1)
NNVERWENDUNG CHAR(30)
VERSICHERUNGSWERT CHAR(19)
VWWAEHRUNG CHAR(3)
FRANKATURKENNUNG CHAR(10)
ZAHLUNGSBEDIGNUNG CHAR(10)
ZBZOLL CHAR(1)
FRACHTFUEHRERKDNR CHAR(10)
SONDERDIENSTE CHAR(30)
SENDUNGSINHALT CHAR(30)
TERMINART CHAR(1)
TERMINDATUM CHAR(10)
TERMINZEIT CHAR(5)
NEUTABSENDERNAME1 CHAR(30)
NEUTABSENDERNAME2 CHAR(30)
NEUTABSENDERNAME3 CHAR(30)
NEUTABSENDERSTRASSE CHAR(30)
NEUTABSENDERLKZ CHAR(3)
NEUTABSENDERPLZ CHAR(10)
NEUTABSENDERORT CHAR(30)
RECHNUNGSEMPFNAME1 CHAR(50)
RECHNUNGSEMPFNAME2 CHAR(50)
RECHNUNGSEMPFNAME3 CHAR(50)
RECHNUNGSEMPFSTRASSE CHAR(50)
RECHNUNGSEMPFLKZ CHAR(5)
RECHNUNGSEMPFPLZ CHAR(10)
RECHNUNGSEMPFORT CHAR(50)
POSTLEITCODE CHAR(15)
POSTZIELFRACHTZENT CHAR(5)
FRACHTBRIEF CHAR(20)
GEWICHT CHAR(9)
NETTOGEWICHT CHAR(9)
PACKSTKGES CHAR(10)
PACKSTKNR CHAR(10)
VERPACKUNGSART CHAR(6)
PACKSTUECKLAENGE CHAR(10)
PACKSTUECKBREITE CHAR(10)
PACKSTUECKHOEHE CHAR(10)
PACKPLATZ CHAR(10)
PACKSTUECKID CHAR(15)
ANZAHLARTIKEL CHAR(10)
ZUSATZZEILE1 CHAR(150)
ZUSATZZEILE2 CHAR(150)
FREIAVIS1 CHAR(62)
FREIAVIS2 CHAR(62)
HVELEKTRONIKARTIKEL CHAR(1)
EMPFEMAILADRESSE CHAR(100)
KOSTENSTELLE CHAR(30)
DRUCKERNAME CHAR(30)
DGPOSITIONS STRUCTURE
GEFAHRGUTUNNR CHAR(4)
GEFAHRGUTKLASSE CHAR(6)
GEFAHRGUTVPG CHAR(5)
GEFAHRGUTKCODE CHAR(5)
GEFAHRGUTBEZEICHNUNG CHAR(110)
GEFAHRGUTMENGE CHAR(9)
GEFAHRGUTBEGRENZTEMENGE CHAR(1)
GEFAHRGUTVERPANZAHL CHAR(10)
GEFAHRGUTVERPACKUNGSART CHAR(8)
GEFAHRGUTNEBENGEFAHR CHAR(20)
GEFAHRGUTBUCHST640 CHAR(1)
GEFAHRGUTMENGENEINHEIT CHAR(2)
GEFAHRGUTBEFOERDKAT CHAR(10)
GEFAHRGUTFAKTOR CHAR(10)
GEFAHRGUTNETTOEXPLMASSE CHAR(9)
GEFAHRGUTTUNNELBCODE CHAR(10)
GEFAHRGUTFREIGESTMENGE CHAR(1)
GEFAHRGUTFFCODE CHAR(20)
DELIVERYPOSITIONS STRUCTURE
ANZAHLPOSETIKETTEN CHAR()
ARTIKELBTNNR CHAR(25)
ARTIKELEAN CHAR(20)
ARTIKELEINHEIT CHAR(10)
ARTIKELGEWICHT CHAR(9)
ARTIKELMENGE CHAR(9)
ARTIKELSOLLMENGE CHAR(9)
ARTIKELTEXT1 CHAR(100)
ARTIKELTEXT2 CHAR(100)
ARTIKELTEXT3 CHAR(100)
ARTIKELTEXT4 CHAR(100)
ARTIKELWAEHRUNG CHAR(3)
ARTIKELWERT CHAR(9)
CHARGEFLAG CHAR(1)
KUNDENARTIKELNR CHAR(50)
KUNDENBESTELLNR CHAR(50)
POSAUFTRAGNR CHAR(50)
POSITIONNR CHAR(40)
POSLIEFERNR CHAR(40)
SERIENNR CHAR(30)
URSPRUNGLAND CHAR(2)
ARTIKELGRUPPE CHAR(50)
ARTIKELSERVICES CHAR(100)
ARTIKELVOLUMEN CHAR(9)

EXPORTING
PACKSTUECKRUECK STRUCTURE
TRACKINGNR CHAR(35)
VERSANDSENDUNGSNR CHAR(20)
DRUCKDATETIME CHAR(10)
AUSGANGDATETIME CHAR(10)
GEBUEHR CHAR(19)
GEBUEHRWAEHRUNG CHAR(3)
FEHLERTEXT1 CHAR(200)
FEHLERTEXT2 CHAR(200)

}
</source>
</div></div>

= FAQ / Troubleshooting =
=== Destination über SM59 definieren ===
Zur Einrichtung einer RFC-Verbindung im SAP, welche für die Anbindung des HVS32 Versandsystems gedacht ist, gehen Sie bitte wie folgt vor:
# Wechseln Sie zur Transaktion sm59
# Wählen Sie den Typ T (TCP/IP connections) '''[Abb.1]'''
# Erstellen Sie mit dem Button "create" eine neue Verbindung
# Geben Sie eine RFC Destination an (z.B. "RFC_HVS32")
# Stellen Sie den Aktivierungstyp auf "Registriertes Serverprogramm"
# Legen Sie eine Programm ID fest (z.B. "HVS32") '''[Abb.2]'''
# Öffnen Sie den Reiter "MDMP & Unicode"
# Stellen Sie dort die Art der Kommunikation auf "Unicode" '''[Abb.3]'''
# Speichern Sie die Einstellungen
# Sie können die Verbindung über "Connection Test" prüfen, sobald auf dem Zielsystem der DataGatewayServer installiert und als Dienst gestartet ist '''[Abb.4]'''

<gallery>
sm59_1.png|Abb.1
sm59_2.png|Abb.2
sm59_3.png|Abb.3
sm59_4.png|Abb.4
</gallery>

Schnittstellen: Security Levels und Authentifizierung

2024-04-08T07:03:28Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]

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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.<br>

Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]
<br>Es wird '''mindestens''' die DataGatewayServer Version '''3.8.31''' benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

Interfaces: Security Levels and Authentication

2024-04-08T07:02:37Z

Odelice:

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]

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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 RESTv2 interface].
<br>DataGatewayServer Version '''3.8.31''' or higher is needed.
==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Schnittstellen: Security Levels und Authentifizierung

2024-04-08T07:01:18Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]

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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.<br>

Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 RESTv2 Schnittstelle]

Es wird mindestens die DataGatewayServer Version 3.8.31 benötigt.
==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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

Interfaces: Security Levels and Authentication

2024-03-21T12:08:06Z

Odelice: /* Authorization Code */

[[de:Schnittstellen:_Security_Levels_und_Authentifizierung]]

'''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.<br><br>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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_cloud_system|IRIS Cloudsystem]].

Schnittstellen: Security Levels und Authentifizierung

2024-03-21T12:07:17Z

Odelice:

[[en:Interfaces:_Security_Levels_and_Authentication]]

'''''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.''<br><br>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.<br>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.<br>Dies impliziert, dass sowohl die Verbindung verschlüsselt als auch jede eingehende Verbindung authentifiziert werden muss.<br>

=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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Level (Infrastruktur) - LAN / vLAN / vNET / private cloud / VPN]]<br><br>

==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.
[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Level (Infrastruktur) - S2S (Server-to-Server)]]
==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.
[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Level (Infrastruktur) - Dead-End-Server]]

=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.<br>

Die folgenden Authentifizierungs-Optionen beziehen sich '''ausschließlich''' auf die [https://interface.heidler-strichcode.de?version=v2 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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
In diesem Beispiel wird der Benutzer ''heidler'' mit dem Passwort ''Wolfschlugen'' verwendet.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung aufgrund von ungültigen Benutzerdaten fehlschlagen, so wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"Unauthorized acces"'' im Body quittiert.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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.<br>

Bei der Digest-Authentifizierung sendet der Client eine Anfrage an den Server (ohne Authentifizierung im Header), der daraufhin eine "Nonce" (eine einmalige Zufallszahl) zurückgibt. Alternativ kann diese über den Enpoint ''v2/hsc/auth/digest'' abgerufen werden. 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.<br>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).

Für die Erstellung vom Digest wird aktuell nur der Algorithmus MD5 unterstützt. Weitere Algorithmusverfahren können nach Rücksprache implementiert werden.

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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage einer nonce für die Erstellung des Digest</div>
<div class="mw-collapsible-content">
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'''.<br>

Diese Anfrage wird mit dem HTTP-Code '''401 Unauthorized''' und der Fehlermeldung ''"Authentication required!"'' im Body quittiert.
<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Anfrage nach erhaltener nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<BENUTZERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>Der Parameter '''nc''' = "Nonce count" und '''cnonce''' = "Client nonce" wird jeweils vom Client generiert und muss für die Erstellung vom Digest genutzt werden.

<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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.<br>Der Server überprüft den empfangenen API-Key, um sicherzustellen, dass die Anfrage von einem authentifizierten Benutzer oder Anwendung stammt.<br>

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 oder bestehende gelöscht werden. Es können mehrere gültige API-Keys existieren.

'''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.

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für eine Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung</div>
<div class="mw-collapsible-content">
Bei einem falschen API-Key wird der HTTP-Code '''401 Unauthorized''' mit der Fehlermeldung ''"api key invalid!"'' im Body zurück gemeldet.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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.

<br>Das ERP wird am Server registriert und erhält eine eindeutige Client-ID und ein Client-Secret.<br>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.<br>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.<br>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.<br><br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispiel für die Token-Anfrage (Access- und Refreshtoken mit Client-ID + Client-Secret generieren)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Token-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Nutzung eines Accesstokens</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Beispielheader für die Refresh-Anfrage (Access- und Refreshtoken mit gültigem Refreshtoken erneuern)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung der Refresh-Anfrage</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Rückmeldung bei fehlgeschlagener Authentifizierung - 401 Unauthorized</div>
<div class="mw-collapsible-content">
Sollte die Authentifizierung fehlschlagen, so wird der HTTP-Code 401 Unauthorized mit einer entsprechenden Fehlermeldung im Body quittiert.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<FEHLERMELDUNG>
</syntaxhighlight>
</div></div>
<br><br>
===Authorization Code===
Diese Authentifizierungs-Methode ist ausschließlich über das Authentifzierungssystem [[IRIS_Cloudsystem|IRIS Cloudsystem]] möglich.

Interfaces: Security Levels and Authentication

2024-03-21T12:06:37Z

Odelice:

Interfaces: Security Levels and Authentication

2024-03-21T12:05:56Z

Odelice:

'''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.<br><br>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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_Cloudsystem|IRIS Cloudsystem]].

Interfaces: Security Levels and Authentication

2024-03-21T09:12:42Z

Odelice:

'''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.<br><br>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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
If an access token has expired and needs to be renewed, a new access token + refresh token can be generated 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 expires. If an invalid refresh token is used for authentication with the DataGatewayServer, for security reasons, all valid access and refresh tokens will be deactivated. Authentication must then be done again through the token request.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_Cloudsystem|IRIS Cloudsystem]].

Interfaces: Security Levels and Authentication

2024-03-21T07:25:57Z

Odelice:

'''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.<br><br>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.<br>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.<br>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.<br>[[Datei:Securitylevel infrastructure vpn.png|1000px|rahmenlos|Security Levels (Infrastructure) - LAN / vLAN / vNET / private cloud / VPN]]

==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.<br>[[Datei:Securitylevel infrastructure s2s.png|1000px|rahmenlos|Security Levels (Infrastructure) - S2S (Server-to-Server)]]
==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.<br>[[Datei:Securitylevel infrastructure des.png|1000px|rahmenlos|Security Levels (Infrastructure) - Dead-End-Server]]

=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).

<br>The following authentication options are specific to the [https://interface.heidler-strichcode.de?version=v2 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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;"><div style="font-weight:bold;line-height:1.6;">Example header for request</div>
<div class="mw-collapsible-content">
In this example user ''heidler'' and password ''Wolfschlugen'' is used.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Basic aGVpZGxlcjpXb2xmc2NobHVnZW4=
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
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
</syntaxhighlight>
</div></div>

==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."<br>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request for a nonce to create the digest</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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!
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Request after receiving nonce</div>
<div class="mw-collapsible-content">
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:<br>''Digest username="<USERNAME>", realm="<REALM>", nonce="<NONCE>", uri="<ENDPOINT>", algorithm="MD5", qop=<QOP>, nc=<NC>, cnonce="<CNONCE>", response="<DIGEST>", opaque="<OPAQUE>"''<br><br>The parameter '''nc''' = "Nonce count" and '''cnonce''' = "Client nonce" are both generated by the client and must be used for creating the digest.<syntaxhighlight lang="http">
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"
</syntaxhighlight>
</div></div>

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 10:45:40 GMT
Content-type: application/json
Content-length: 27

client credentials invalid!
</syntaxhighlight>
</div></div>

==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."

<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for a request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
x-api-key: apikey_heidler
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response on failed authentication</div>
<div class="mw-collapsible-content">
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.

<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 09:46:30 GMT
Content-type: application/json
Content-length: 16

api key invalid!
</syntaxhighlight>
</div></div>

==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."
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example of token request (generating access and refresh tokens with client ID + client secret)</div>
<div class="mw-collapsible-content">
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.
<syntaxhighlight lang="http">
POST /v2/hsc/auth/token HTTP/1.1
Accept: application/json
Authorization: Basic <ClientID>:<ClientSecret>
grant_type: client_credentials
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the token request</div>
<div class="mw-collapsible-content">
In the response of the token request, the access token (access_token), refresh token (refresh_token), token type (token_type), and validity 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 limited validity. 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:''' Regularly generating access tokens through the token request 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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for using an access token</div>
<div class="mw-collapsible-content">
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>''.
<syntaxhighlight lang="http">
POST <ENDPOINT> HTTP/1.1
Content-Type: application/json
Accept: application/json
Authorization: Bearer eyJ1c2FnZSI6IkFDQ0VTUyIsInR5cCI6IkpXVCIsImFsZyI6IkhTMjU2In0.eyJleHAiOjE3MDg5NDk3OTIsImp0aSI6ImM0ZDFkNTdiLWUzZTAtNDkwOC1hMDk4LWJiMjc2NmZmODdiMSIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.4zrctPAnBAlMj9CFUL6jQ33Gkou3V_bmcLBUrEsUKL0
Cache-Control: no-cache
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Example header for the refresh request (renewing access and refresh tokens with a valid refresh token)</div>
<div class="mw-collapsible-content">
If an access token has expired and needs to be renewed, a new access token + refresh token can be generated 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 expires. If an invalid refresh token is used for authentication with the DataGatewayServer, for security reasons, all valid access and refresh tokens will be deactivated. Authentication must then be done again through the token request.<syntaxhighlight lang="http">
POST /v2/hsc/auth/refresh HTTP/1.1
Accept: application/json
refresh_token: eyJ1c2FnZSI6IlJFRlJFU0giLCJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJleHAiOjE3MDk4MTMxOTIsImp0aSI6IjEwMGZmN2JiLTQ1MzItNDFlNi05NTZjLTBjZjE0YWIzYTljNCIsInV1SUQiOiI0NTJiNWE4Ni1iZDRlLTRlNjktOGYxOC1hOGM5YWFlZTE1YzkiLCJzdWIiOiJvZCIsImlzcyI6IkhTQy1ER1MiLCJpYXQiOjE3MDg5NDkxOTJ9.vAPo2Zobu2BNGNrUvmxKd5RVGWIn91sT83js33n2UUA
grant_type: refresh_token
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Response of the refresh request</div>
<div class="mw-collapsible-content">
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.<syntaxhighlight lang="http">
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
}
</syntaxhighlight>
</div></div>
<br>
<div class="toccolours mw-collapsible mw-collapsed" style="overflow:auto;">
<div style="font-weight:bold;line-height:1.6;">Feedback on failed authentication - 401 Unauthorized</div>
<div class="mw-collapsible-content">
If authentication fails, the HTTP status code '''401 Unauthorized''' will be returned along with an appropriate error message in the body.
<syntaxhighlight lang="http">
HTTP/1.1 401 Unauthorized
Date: Mon, 26 Feb 2024 12:38:59 GMT
Content-type: application/json
Content-length: <LÄNGE>

<ERRORMESSAGE>
</syntaxhighlight>
</div></div>
<br><br>

===Authorization Code===
This authentication method is exclusively available through the authentication system [[IRIS_Cloudsystem|IRIS Cloudsystem]].