OPC UA GDS-Push-Gerät registrieren

Diese Anleitung beschreibt, wie ein neues OPC UA-Gerät in IDIAL registriert und ein Zertifikat über den GDS-Push-Mechanismus ausgestellt wird. Die Anleitung führt Schritt für Schritt durch alle notwendigen API-Aufrufe — von der Vorbereitung bis zur Bestätigung einer erfolgreichen Registrierung.

Voraussetzungen

Bevor Sie beginnen, stellen Sie sicher, dass folgende Voraussetzungen erfüllt sind:

• IDIAL ist gestartet und über die REST API erreichbar
• Ein gültiger API-Key steht zur Verfügung (X-API-Key-Header)
• Das OPC UA-Gerät ist vom IDIAL-Container aus netzwerktechnisch erreichbar
• Das Gerät unterstützt den OPC UA Global Discovery Server (GDS) Push-Mechanismus

Informationen vorab vom Gerät sammeln

Information	Beschreibung	Beispiel
IP-Adresse oder FQDN	Eindeutige Netzwerkadresse des Geräts	192.168.1.10 oder plc-line1.example.com
OPC UA Port	OPC UA-Serverport des Geräts	4840 (Standard)
GDS-Zugangsdaten	Benutzername und Passwort für den GDS-Zugriff, falls das Gerät Authentifizierung erfordert	GDS_Admin / Siemens1!
Gerätename (optional)	Frei wählbarer Anzeigename für den Inventareintrag	PLC Linie 1

hinweis

Security Policy und Security Mode müssen nicht vorab bekannt sein — sie werden im ersten Schritt automatisch vom Gerät ermittelt.

---

Schritt 1: Konnektivität testen und Security-Einstellungen ermitteln

Bevor das Gerät ins Inventar aufgenommen wird, prüfen Sie die Erreichbarkeit und ermitteln Sie die ausgehandelte Security Policy und den Security Mode. Diese Werte werden in den folgenden Schritten benötigt.

curl -X POST https://idial.example.com/gds/monitor/crt \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "connection_security": true
  }'

Erwartete Antwort (200):

{
  "idial_time": "2026-03-30T10:00:00+00:00",
  "url": null,
  "security_policy": 8,
  "security_mode": 2
}

hinweis

url ist null, weil das Gerät noch nicht im Inventar eingetragen ist. Das ist an diesem Punkt korrekt.

Notieren Sie für die folgenden Schritte:

• security_policy: 8 (Basic256Sha256) — vollständige Wertetabelle: Parameter-Referenz → security_policy
• security_mode: 2 (SignAndEncrypt) — vollständige Wertetabelle: Parameter-Referenz → security_mode

Schlägt dieser Aufruf fehl, ist das Gerät nicht erreichbar oder die Verbindungsparameter sind falsch. Prüfen Sie Netzwerkkonnektivität und Port.

---

Schritt 2: Inventareintrag anlegen

Legen Sie den Inventareintrag mit den im vorherigen Schritt ermittelten Security-Einstellungen an. Der server-Wert ist der eindeutige Bezeichner — er darf kein zweites Mal im Inventar vorkommen.

curl -X POST https://idial.example.com/gds/inventory \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "name": "PLC Linie 1",
    "userinfo_name": "GDS_Admin",
    "userinfo_password": "Siemens1!",
    "security_policy": 8,
    "security_mode": 2,
    "device_status": 1
  }'

Feld	Beschreibung
server	IP-Adresse oder FQDN — wird als eindeutiger Schlüssel in der Datenbank verwendet
port	OPC UA Port des Geräts
name	Optionaler Anzeigename für das Inventar
userinfo_name / userinfo_password	GDS-Zugangsdaten des Geräts, falls erforderlich
security_policy	Bitmask aus Schritt 1 — siehe Parameter-Referenz
security_mode	Wert aus Schritt 1 — siehe Parameter-Referenz
device_status	1 = aktiv (erforderlich damit das Gerät vom Scheduler berücksichtigt wird)

Erwartete Antwort (200):

{
  "id": 42,
  "name": "PLC Linie 1",
  "url": "opc.tcp://192.168.1.10:4840",
  "server": "192.168.1.10",
  "port": 4840,
  "device_status": 1,
  "device_status_name": "active",
  "security_policy": 8,
  "security_mode": 2,
  "username": "GDS_Admin",
  "device_name": null,
  "firmware_version": null,
  "cert_subjectdn": "",
  "cert_validto": "",
  "cert_expdays": null,
  "cert_revoked": null
}

Notieren Sie für die folgenden Schritte:

• Die OPC UA URL: opc.tcp://192.168.1.10:4840 — oder kurz die IP 192.168.1.10 als host_or_url

warnung

device_name und firmware_version sind noch null. Sie werden im nächsten Schritt automatisch befüllt.

---

Schritt 3: Firmware-Informationen lesen

IDIAL liest die Firmware-Informationen des Geräts aus und legt fest, ob IDIAL das Gerät aus seiner internen Kompatibilitätsliste kennt (known_device) oder im generischen OPC UA Modus betreibt (generic_device). Das Ergebnis wird automatisch im Inventareintrag gespeichert.

curl -X GET "https://idial.example.com/gds/firmware/192.168.1.10" \
  -H "X-API-Key: your-api-key"

Erwartete Antwort (200):

{
  "url": "opc.tcp://192.168.1.10:4840",
  "gds_time": "2026-03-30T10:01:00+00:00",
  "product_name": "SIMATIC S7-1500 OPC UA",
  "product_uri": "urn:Siemens:SIMATIC.S7-1500.OPC-UA.Application",
  "manufacturer_name": "Siemens AG",
  "software_version": "V03.01.03",
  "known_device": true,
  "generic_device": false
}

Feld	Bedeutung
known_device: true	IDIAL hat spezifische Unterstützung für dieses Gerät — empfohlener Modus
known_device: false	Gerät unbekannt — IDIAL verwendet den generischen OPC UA GDS-Modus
generic_device: true	Gerät wird generisch behandelt (keine gerätespezifischen Anpassungen)

tipp

Wenn known_device: false zurückgegeben wird, prüfen Sie mit GET /supported-devices, welche Gerätekombinationen unterstützt werden. Das Gerät kann trotzdem im generischen Modus betrieben werden.

---

Schritt 4: GDS-Status und Provisioning Mode prüfen

Bevor der GDS Push ausgeführt wird, prüfen Sie ob das Gerät den Provisioning Mode aktiv hat. Ohne aktiven Provisioning Mode schlägt der GDS Push fehl.

curl -X GET "https://idial.example.com/gds/status/192.168.1.10" \
  -H "X-API-Key: your-api-key"

Erwartete Antwort (200):

{
  "url": "opc.tcp://192.168.1.10:4840",
  "gds_time": "2026-03-30T10:01:30+00:00",
  "gds_state": 1,
  "provisioning_mode_active": true,
  "provisioning_mode_enabled": true
}

Feld	Erwarteter Wert	Beschreibung
provisioning_mode_active	true	Pflicht für GDS Push — ist dies false, muss der Provisioning Mode am Gerät aktiviert werden
provisioning_mode_enabled	true	Provisioning Mode ist am Gerät konfiguriert
gds_state	1	GDS-Servicestatus des Geräts

gefahr

Wenn provisioning_mode_active: false zurückgegeben wird, brechen Sie hier ab. Aktivieren Sie zunächst den Provisioning Mode am Gerät (geräteabhängige Vorgehensweise, z. B. in der SPS-Projektierung).

---

Schritt 5: GDS Push — Zertifikat ausstellen

Führen Sie den GDS Push aus. IDIAL verbindet sich mit dem Gerät und stellt das OPC UA-Anwendungszertifikat aus. Die Ausstellung läuft serialisiert — parallele Push-Operationen werden intern sequenzialisiert.

curl -X GET "https://idial.example.com/gds/push/192.168.1.10" \
  -H "X-API-Key: your-api-key"

Alternativ über POST /gds/push mit zusätzlichen Optionen:

curl -X POST https://idial.example.com/gds/push \
  -H "X-API-Key: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "server": "192.168.1.10",
    "port": 4840,
    "security_policy": 8,
    "security_mode": 2,
    "issuer": true
  }'

tipp

issuer: true legt die CA als Aussteller-Zertifikat in der Trust List des Geräts ab. Dies wird empfohlen, da der Eintrag auch nach einer Zertifikatserneuerung erhalten bleibt. Mit trusted: true wird die CA als vertrauenswürdiges Zertifikat eingetragen — nach einer Erneuerung des CA-Zertifikats müsste dieser Eintrag jedoch manuell aktualisiert werden.

Erwartete Antwort (200):

{
  "success": true,
  "execution": "Connecting to opc.tcp://192.168.1.10:4840...\nCertificate issued successfully.\n",
  "error": "",
  "result": {
    "certificate": "MIID..."
  }
}

Bei "success": false enthält error die Fehlermeldung und execution das vollständige Protokoll des Ausführungsskripts.

---

Schritt 6: Ausgestelltes Zertifikat prüfen

Lesen Sie das im Inventar gespeicherte Zertifikat aus und prüfen Sie Gültigkeit, Aussteller und CRL-Status.

curl -X GET "https://idial.example.com/gds/inventory/crt/192.168.1.10" \
  -H "X-API-Key: your-api-key"

Erwartete Antwort (200) — Auszug der wichtigsten Felder:

{
  "name": "PLC Linie 1",
  "url": "opc.tcp://192.168.1.10:4840",
  "device_status": 1,
  "certificate": {
    "subject_dn": "CN=plc-line1,O=ExampleCorp,C=DE",
    "issuer_dn": "CN=Issuing CA,O=ExampleCorp,C=DE",
    "valid_from": "2026-03-30T10:02:00",
    "valid_to": "2027-03-30T10:02:00",
    "remaining_days": 365,
    "self_signed": false,
    "sha1_thumbprint": "A1B2C3D4E5F6789012345678901234567890ABCD"
  },
  "certificate_revocation": {
    "id": 1,
    "name": "not_revoked",
    "description": "certificate was checked against a CRL and is not revoked"
  },
  "certificate_revocation_reason": null
}

Checkliste für eine erfolgreiche Registrierung:

Prüfpunkt	Erwarteter Wert
certificate.self_signed	false — Zertifikat wurde von einer CA ausgestellt
certificate.issuer_dn	Enthält die konfigurierte CA
certificate.remaining_days	Positiver Wert (Zertifikat gültig)
certificate_revocation.name	"not_revoked"

---

Schritt 7: Inventarstatus abschließend bestätigen

Rufen Sie den vollständigen Inventareintrag ab und bestätigen Sie, dass alle Felder korrekt befüllt sind.

curl -X GET "https://idial.example.com/gds/inventory/192.168.1.10" \
  -H "X-API-Key: your-api-key"

Erwartete Antwort (200):

{
  "id": 42,
  "name": "PLC Linie 1",
  "url": "opc.tcp://192.168.1.10:4840",
  "server": "192.168.1.10",
  "port": 4840,
  "device_status": 1,
  "device_status_name": "active",
  "device_name": "SIMATIC S7-1500 OPC UA",
  "firmware_version": "V03.01.03",
  "cert_subjectdn": "CN=plc-line1,O=ExampleCorp,C=DE",
  "cert_validto": "2027-03-30T10:02:00",
  "cert_expdays": 365,
  "cert_revoked": false,
  "security_policy": 8,
  "security_mode": 2,
  "pki_endpoint": "https://pki.example.com/ca"
}

Das Gerät ist erfolgreich registriert wenn:

• device_name und firmware_version befüllt sind (aus Schritt 3)
• cert_expdays einen positiven Wert hat
• cert_revoked false ist
• device_status_name "active" ist

---

Ablauf-Übersicht

Schritt 1  POST /gds/monitor/crt        → security_policy, security_mode ermitteln
    ↓
Schritt 2  POST /gds/inventory           → Inventareintrag anlegen (host_or_url verfügbar)
    ↓
Schritt 3  GET  /gds/firmware/{host}     → Firmware-Info lesen & in DB speichern
    ↓
Schritt 4  GET  /gds/status/{host}       → Provisioning Mode prüfen (muss active = true sein)
    ↓
Schritt 5  GET  /gds/push/{host}         → Zertifikat ausstellen
    ↓
Schritt 6  GET  /gds/inventory/crt/{host}→ Zertifikat & CRL-Status prüfen
    ↓
Schritt 7  GET  /gds/inventory/{host}    → Abschlussprüfung des Inventareintrags

---

Fehlerbehebung

Symptom	Mögliche Ursache	Lösung
Schritt 1 schlägt fehl (500)	Gerät nicht erreichbar	Netzwerkverbindung, Firewall und Port prüfen
Schritt 4: provisioning_mode_active: false	Provisioning Mode nicht aktiv	Am Gerät aktivieren (geräteabhängig)
Schritt 5 schlägt fehl (success: false)	GDS-Zugangsdaten falsch oder CA nicht konfiguriert	userinfo_name/userinfo_password prüfen, PKI-Konfiguration prüfen
cert_revoked: true in Schritt 6	Ausgestelltes Zertifikat ist bereits widerrufen	PKI-Konfiguration und CRL-Endpunkt prüfen
known_device: false in Schritt 3	Gerät nicht in der Kompatibilitätsliste	Gerät läuft im generischen Modus — GET /supported-devices zur Übersicht