Registering an OPC UA GDS Push Device

This guide describes how to register a new OPC UA device in IDIAL and issue a certificate via the GDS Push mechanism. It walks through all required API calls step by step — from preparation to confirmation of a successful registration.

Prerequisites

Before you begin, ensure the following prerequisites are met:

IDIAL is running and reachable via the REST API
A valid API key is available (X-API-Key header)
The OPC UA device is network-reachable from the IDIAL container
The device supports the OPC UA Global Discovery Server (GDS) Push mechanism

Information to collect from the device in advance

Information	Description	Example
IP address or FQDN	Unique network address of the device	`192.168.1.10` or `plc-line1.example.com`
OPC UA port	OPC UA server port of the device	`4840` (default)
GDS credentials	Username and password for GDS access, if the device requires authentication	`GDS_Admin` / `Siemens1!`
Device name (optional)	Freely chosen display name for the inventory entry	`PLC Line 1`

note

The Security Policy and Security Mode do not need to be known in advance — they are determined automatically from the device in the first step.

Step 1: Test connectivity and determine security settings

Before adding the device to the inventory, verify reachability and determine the negotiated Security Policy and Security Mode. These values are required in the following steps.

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

Expected response (200):

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

note

url is null because the device has not yet been added to the inventory. This is correct at this point.

Note for the following steps:

security_policy: 8 (Basic256Sha256) — full value table: Parameter Reference → security_policy
security_mode: 2 (SignAndEncrypt) — full value table: Parameter Reference → security_mode

If this call fails, the device is unreachable or the connection parameters are incorrect. Check network connectivity and the port.

Step 2: Create an inventory entry

Create the inventory entry using the security settings determined in the previous step. The server value is the unique identifier — it must not appear more than once in the inventory.

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 Line 1",
    "userinfo_name": "GDS_Admin",
    "userinfo_password": "Siemens1!",
    "security_policy": 8,
    "security_mode": 2,
    "device_status": 1
  }'

Field	Description
`server`	IP address or FQDN — used as the unique key in the database
`port`	OPC UA port of the device
`name`	Optional display name for the inventory
`userinfo_name` / `userinfo_password`	GDS credentials of the device, if required
`security_policy`	Bitmask from Step 1 — see Parameter Reference
`security_mode`	Value from Step 1 — see Parameter Reference
`device_status`	`1` = active (required for the device to be considered by the scheduler)

Expected response (200):

{
  "id": 42,
  "name": "PLC Line 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
}

Note for the following steps:

The OPC UA URL: opc.tcp://192.168.1.10:4840 — or simply the IP 192.168.1.10 as host_or_url

warning

device_name and firmware_version are still null. They will be populated automatically in the next step.

Step 3: Read firmware information

IDIAL reads the firmware information from the device and determines whether IDIAL recognizes the device from its internal compatibility list (known_device) or operates it in generic OPC UA mode (generic_device). The result is automatically saved in the inventory entry.

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

Expected response (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
}

Field	Meaning
`known_device: true`	IDIAL has specific support for this device — recommended mode
`known_device: false`	Device unknown — IDIAL uses generic OPC UA GDS mode
`generic_device: true`	Device is handled generically (no device-specific adaptations)

tip

If known_device: false is returned, use GET /supported-devices to check which device combinations are supported. The device can still be operated in generic mode.

Step 4: Check GDS status and Provisioning Mode

Before executing the GDS Push, verify that the device has Provisioning Mode active. Without active Provisioning Mode, the GDS Push will fail.

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

Expected response (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
}

Field	Expected value	Description
`provisioning_mode_active`	`true`	Required for GDS Push — if `false`, Provisioning Mode must be activated on the device
`provisioning_mode_enabled`	`true`	Provisioning Mode is configured on the device
`gds_state`	`1`	GDS service status of the device

danger

If provisioning_mode_active: false is returned, stop here. First activate Provisioning Mode on the device (device-specific procedure, e.g. in the PLC engineering tool).

Step 5: GDS Push — issue certificate

Execute the GDS Push. IDIAL connects to the device and issues the OPC UA application certificate. Issuance runs serialized — concurrent Push operations are internally sequentialized.

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

Alternatively via POST /gds/push with additional options:

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

tip

issuer: true places the CA as an issuer certificate in the device's trust list. This is recommended because the entry persists even after a certificate renewal. With trusted: true, the CA is added as a trusted certificate — however, after a CA certificate renewal this entry would need to be updated manually.

Expected response (200):

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

If "success": false, the error field contains the error message and execution contains the full log of the execution script.

Step 6: Verify the issued certificate

Read the certificate stored in the inventory and check its validity, issuer, and CRL status.

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

Expected response (200) — excerpt of the most important fields:

{
  "name": "PLC Line 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
}

Checklist for a successful registration:

Check	Expected value
`certificate.self_signed`	`false` — certificate was issued by a CA
`certificate.issuer_dn`	Contains the configured CA
`certificate.remaining_days`	Positive value (certificate valid)
`certificate_revocation.name`	`"not_revoked"`

Step 7: Confirm inventory status as final check

Retrieve the full inventory entry and confirm that all fields are correctly populated.

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

Expected response (200):

{
  "id": 42,
  "name": "PLC Line 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"
}

The device is successfully registered when:

device_name and firmware_version are populated (from Step 3)
cert_expdays has a positive value
cert_revoked is false
device_status_name is "active"

Process overview

Step 1  POST /gds/monitor/crt        → determine security_policy, security_mode
    ↓
Step 2  POST /gds/inventory           → create inventory entry (host_or_url available)
    ↓
Step 3  GET  /gds/firmware/{host}     → read firmware info & save to DB
    ↓
Step 4  GET  /gds/status/{host}       → check Provisioning Mode (must be active = true)
    ↓
Step 5  GET  /gds/push/{host}         → issue certificate
    ↓
Step 6  GET  /gds/inventory/crt/{host}→ verify certificate & CRL status
    ↓
Step 7  GET  /gds/inventory/{host}    → final check of the inventory entry

Troubleshooting

Symptom	Possible cause	Solution
Step 1 fails (`500`)	Device unreachable	Check network connection, firewall, and port
Step 4: `provisioning_mode_active: false`	Provisioning Mode not active	Activate on the device (device-specific)
Step 5 fails (`success: false`)	GDS credentials incorrect or CA not configured	Check `userinfo_name`/`userinfo_password`, check PKI configuration
`cert_revoked: true` in Step 6	Issued certificate is already revoked	Check PKI configuration and CRL endpoint
`known_device: false` in Step 3	Device not in the compatibility list	Device runs in generic mode — use `GET /supported-devices` for an overview

Prerequisites​

Information to collect from the device in advance​

Step 1: Test connectivity and determine security settings​

Step 2: Create an inventory entry​

Step 3: Read firmware information​

Step 4: Check GDS status and Provisioning Mode​

Step 5: GDS Push — issue certificate​

Step 6: Verify the issued certificate​

Step 7: Confirm inventory status as final check​

Process overview​

Troubleshooting​

Prerequisites

Information to collect from the device in advance

Step 1: Test connectivity and determine security settings

Step 2: Create an inventory entry

Step 3: Read firmware information

Step 4: Check GDS status and Provisioning Mode

Step 5: GDS Push — issue certificate

Step 6: Verify the issued certificate

Step 7: Confirm inventory status as final check

Process overview

Troubleshooting