GDS Push — Certificate Enrollment
GDS Push is the primary mechanism for certificate enrollment on OPC UA devices managed by IDIAL. IDIAL connects to the OPC UA Global Discovery Server (GDS) interface of the target device, issues a certificate via the configured PKI endpoint, and transfers it into the device's certificate store. The trust list (CA chain and CRL) is provisioned on the device at the same time.
Before the first enrollment, IDIAL verifies the connection to the device and stores the credentials for subsequent automated operations.
POST /gds/push
Issues a certificate and transfers it to a GDS-capable OPC UA endpoint. If the device is not yet in the inventory, it is registered automatically. Submitted credentials are stored for future automated renewals.
Authentication: Required (X-API-Key header)
Request
curl -X POST http://localhost:5000/gds/push \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"server": "192.168.1.10",
"port": 4840,
"name": "PLC Line 1",
"subject": "CN=plc-line1,O=ExampleCorp,C=DE",
"username": "admin",
"password": "secret",
"issuer": true,
"trusted": false,
"security_policy": 8,
"security_mode": 2,
"debug": false
}'
Request Fields
| Field | Type | Required | Default | Description |
|---|---|---|---|---|
server | string | Yes | — | IP address or FQDN of the target device. The unique identifier of the endpoint within IDIAL. |
port | integer | No | 4840 | OPC UA port. |
name | string | No | — | Display name for the endpoint. Does not affect the certificate content. |
subject | string | No | — | Desired Subject DN for the target certificate. If omitted, IDIAL evaluates available defaults for the certificate subject. |
username | string | No | — | Username IDIAL uses to connect to the GDS endpoint. Updates the stored username for future operations. |
password | string | No | — | Password for the GDS connection. Stored encrypted for future automated operations. |
issuer | boolean | No | false | When true, the issuer CA certificate of the IDIAL OPC UA client certificate is added to the device truststore. |
trusted | boolean | No | false | When true, the IDIAL OPC UA client certificate itself is added to the device truststore. |
security_policy | integer | No | 31 | Security policy bitmask. See reference-parameters. |
security_mode | integer | No | 0 | Security mode. See reference-parameters. |
debug | boolean | No | false | When true, additional process information is included in the response. |
Use issuer: true (instead of or in addition to trusted: true) so the device continues to accept the IDIAL connection even after the client certificate is renewed. This prevents unintentional connection lockouts.
Response 200
{
"success": true,
"execution": "GDS Push completed successfully",
"error": "",
"result": {}
}
Response Fields
| Field | Type | Description |
|---|---|---|
success | boolean | Whether the operation succeeded. |
execution | string | Execution status message. |
error | string | Error message if the operation failed. |
result | object | null | Additional result data. |
Response 422
Returned when validation of the certificate request failed — the certificate could not be provisioned.
Response 500
{"error": "string"}
GET /gds/push/{host_or_url}
Returns the GDS Push status for a specific inventory entry.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/gds/push/192.168.1.10 \
-H "X-API-Key: your-api-key"
Response 200
Response format matches POST /gds/push.
Response 404
{"error": "string"}
POST /gds/push/onboarding
Performs the GDS Push onboarding workflow for a new endpoint. This establishes the initial trust relationship and registers the device's credentials in the inventory.
Authentication: Required (X-API-Key header)
Request
curl -X POST http://localhost:5000/gds/push/onboarding \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"server": "192.168.1.10",
"port": 4840,
"username": "admin",
"password": "secret"
}'
Request Fields
Same fields as POST /gds/push.
Response 200
Response format matches POST /gds/push.
GET /gds/push/onboarding/{host_or_url}
Returns the onboarding status for a specific GDS inventory entry.
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/gds/push/onboarding/192.168.1.10 \
-H "X-API-Key: your-api-key"
Response 200
Response format matches POST /gds/push.
Response 404
{"error": "string"}
POST /gds/push/change
Triggers a certificate change operation for one or more GDS inventory entries. Used to force certificate renewal outside the normal scheduler cycle.
Authentication: Required (X-API-Key header)
Request
curl -X POST http://localhost:5000/gds/push/change \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{
"server": "192.168.1.10",
"port": 4840
}'
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
server | string | Yes | Hostname or IP of the target endpoint. |
port | integer (1–65535) | No | Port (default: 4840). |
Response 200
Response format matches POST /gds/push.
POST /gds/firmware (deprecated)
Reads firmware version from a GDS endpoint. Use GET /gds/monitor/firmware/{host_or_url} instead.
Authentication: Required (X-API-Key header)
Request
curl -X POST http://localhost:5000/gds/firmware \
-H "X-API-Key: your-api-key" \
-H "Content-Type: application/json" \
-d '{"server": "192.168.1.10", "port": 4840}'
Request Fields
| Field | Type | Required | Description |
|---|---|---|---|
server | string | Yes | Hostname or IP of the target device. |
port | integer | No | OPC UA port (default: 4840). |
username | string | No | Authentication username. |
password | string | No | Authentication password. |
security_policy | integer | No | Security policy bitmask. |
security_mode | integer | No | Security mode bitmask. |
allow_insecure_connection | boolean | No | Allow connection without security. |
Response 200
{
"url": "opc.tcp://192.168.1.10:4840",
"firmware_version": "V03.01.03",
"device_name": "SIMATIC S7-1500 OPC UA"
}
GET /gds/crt
Returns the IDIAL OPC UA client certificate (the certificate IDIAL uses when connecting to GDS endpoints).
Authentication: Required (X-API-Key header)
Request
curl -X GET http://localhost:5000/gds/crt \
-H "X-API-Key: your-api-key"
Response 200
Binary certificate file (PEM or DER format). Add ?format=pem or ?format=der to the URL to specify the format.
Response 404
{"error": "OPCUA client certificate not found"}