Configure security and users

On this page you configure a simulator server that advertises secure endpoints only and requires a user name and password. Then you’ll see the options that give an SDK application the same security. Security explains the concepts.

Security settings of the simulator’s server

Configuration (`server`)	GUI	Effect
`allow_none`	Offer SecurityPolicy None	Advertises the None endpoint (security level 0).
`secure`	Offer signed and encrypted policies	Advertises Sign (20) and SignAndEncrypt (30) endpoints for the three policies.
`allow_anonymous`	Allow anonymous users	Advertises the anonymous token.
`user_name` + `password` of `server_start`	User name, Password	Advertises the user name token on secure endpoints, never on the None endpoint.
`certificate`, `private_key`	Project file	The server certificate and private key. When empty, a self-signed certificate for `localhost`, the listen IP address and `advertised_host` is created in memory.
`trust`	Project file	Client certificates to trust. The client certificate of the same simulator is trusted automatically.

The server accepts one account. The password isn’t stored in the configuration; you pass it each time you start the server. After five consecutive failed user authentications from the same client, that client is locked out for 10 minutes; restarting the server clears the lockout.

1. Start a secure-only server

Use the certificates from PKI and trust setup. In the first terminal, change to the $PKI folder and run the headless simulator:

cd "$PKI"
"$OPCUA_APPS/bin/pdcomm-opcua-headless"

Turn off the None endpoint and anonymous users, and set the certificates and the client certificate to trust:

{"action":"configure","config":{"server":{"address":"127.0.0.1:4841","allow_none":false,"allow_anonymous":false,"certificate":"server.cert.pem","private_key":"server.key.pem","trust":["client.der"]}}}

Start the server with a password. The user name keeps its default, operator.

{"action":"server_start","password":"Lab-password-1"}

{"ok":true,"result":{"audit":[],"endpoint":"opc.tcp://localhost:4841/pdcomm/simulator","error":null,"running":true,"secure":true,"sessions":0}}

2. Configure the client and check the endpoints

In the second terminal, also from the $PKI folder, start another simulator and configure its client:

cd "$PKI"
"$OPCUA_APPS/bin/pdcomm-opcua-headless"

{"action":"configure","config":{"client":{"url":"opc.tcp://localhost:4841/pdcomm/simulator","policy":"Aes256_Sha256_RsaPss","mode":"SignAndEncrypt","identity":"username","certificate":"client.cert.pem","private_key":"client.key.pem","trust":["server.der"]}}}

{"action":"discover"}

{"ok":true,"result":{"endpoints":[{"application_uri":"urn:pdcomm:opcua:server","has_certificate":true,"level":20,"mode":"Sign","policy":"Basic256Sha256","tokens":["username"],"url":"opc.tcp://localhost:4841/pdcomm/simulator"},{"application_uri":"urn:pdcomm:opcua:server","has_certificate":true,"level":30,"mode":"SignAndEncrypt","policy":"Basic256Sha256","tokens":["username"],"url":"opc.tcp://localhost:4841/pdcomm/simulator"},{"application_uri":"urn:pdcomm:opcua:server","has_certificate":true,"level":20,"mode":"Sign","policy":"Aes128_Sha256_RsaOaep","tokens":["username"],"url":"opc.tcp://localhost:4841/pdcomm/simulator"},{"application_uri":"urn:pdcomm:opcua:server","has_certificate":true,"level":30,"mode":"SignAndEncrypt","policy":"Aes128_Sha256_RsaOaep","tokens":["username"],"url":"opc.tcp://localhost:4841/pdcomm/simulator"},{"application_uri":"urn:pdcomm:opcua:server","has_certificate":true,"level":20,"mode":"Sign","policy":"Aes256_Sha256_RsaPss","tokens":["username"],"url":"opc.tcp://localhost:4841/pdcomm/simulator"},{"application_uri":"urn:pdcomm:opcua:server","has_certificate":true,"level":30,"mode":"SignAndEncrypt","policy":"Aes256_Sha256_RsaPss","tokens":["username"],"url":"opc.tcp://localhost:4841/pdcomm/simulator"}],"url":"opc.tcp://localhost:4841/pdcomm/simulator"}}

There’s no None endpoint, and every endpoint accepts the username token only.

3. Connect as the user

A wrong password is refused:

{"action":"connect","password":"wrong-password"}

{"error":"OPC UA status BadUserAccessDenied (0x801F0000)","ok":false}

Connect with the right password:

{"action":"connect","password":"Lab-password-1"}

{"ok":true,"result":{"connected":true,"identity":"username","items":[],"mode":"SignAndEncrypt","pending_cancelled":0,"policy":"Aes256_Sha256_RsaPss","session":"ns=1;s=pdcomm.diagnostics/session/f94df08c9e0d18293afc3eaa6b742393","subscription":null,"url":"opc.tcp://localhost:4841/pdcomm/simulator"}}

An authenticated user can read and write Simulator.Protected:

{"action":"read","nodes":["ns=2;s=Simulator.Protected"]}

{"ok":true,"result":{"values":[{"good":true,"node":"ns=2;s=Simulator.Protected","server_time":1791998271248,"source_time":1791998270971,"status":"Good (0x00000000)","type":"Int32","value":0}]}}

4. What gets refused

Disconnect, switch to anonymous and connect. The client sees that the endpoint offers no anonymous token and doesn’t try:

{"action":"disconnect"}

{"action":"configure","config":{"client":{"url":"opc.tcp://localhost:4841/pdcomm/simulator","policy":"Aes256_Sha256_RsaPss","mode":"SignAndEncrypt","identity":"anonymous","certificate":"client.cert.pem","private_key":"client.key.pem","trust":["server.der"]}}}

{"action":"connect"}

{"error":"OPC UA protocol: anonymous identity not supported","ok":false}

Request policy None, which the server doesn’t advertise, and the client doesn’t connect:

{"action":"configure","config":{"client":{"url":"opc.tcp://localhost:4841/pdcomm/simulator","policy":"None","mode":"None"}}}

{"action":"connect"}

{"error":"The server does not offer the selected security policy and mode","ok":false}

Fields you leave out of configure return to their defaults. The configuration above omits certificate and trust, so if you now switch only the security policy and connect, the client doesn’t trust the server certificate and you get OPC UA security CertificateUntrusted. When you change the configuration, edit the current one from state and pass it back.

The server records its side in the audit of server_status. A refused authentication looks like {"action":"user authentication rejected","channel":3,"status":"BadUserAccessDenied (0x801F0000)"}. To finish, type {"action":"shutdown"} in both terminals.

Use the same configuration in the GUI

The GUI has no fields for certificate files or trust lists. Configure them in the headless simulator, save the result of project_export as a JSON file and open it with Project > Open… in the GUI. Project files hold file paths only, and the GUI’s working folder depends on how you launch it, so use absolute paths for certificates and keys. Type the password into the GUI’s Password field.

Security options of the SDK

Client (pdcomm_opcua_client_options, .NET ClientOptions)

Field	Description
`policy`, `mode`	The policy and mode to request; the server must advertise the same combination, and there’s no fallback.
`flags`	`PDCOMM_OPCUA_ALLOW_NONE` (allow None) and `PDCOMM_OPCUA_USER_SECRET_HEADER_POLICY_ONLY` (omit the algorithm URI in EncryptedSecret passwords over 64 bytes)
`application_uri`	Must match the URI in the client certificate (default `urn:pdcomm:opcua:client`).
`certificate_der`, `private_key_pem`	The client identity, each up to 64 KiB. Wipe your copy of the key right after connecting.
`trusted_server_der`	The one server certificate to trust
`timeout_ms`	Timeout of each network exchange and each request (1 to 300000 ms, default 10000)

To activate a session with a user name, call pdcomm_opcua_client_activate_user_name. The user name is 1 to 1024 bytes and the password up to 16 KiB; the call fails on a secure channel with policy None. Wipe your password buffer after the call. The Qt and MFC workers activate with the user name when anonymous is false in their configuration.

Server (pdcomm_opcua_server_options, .NET ServerOptions)

Field	Description
`flags`	`PDCOMM_OPCUA_ALLOW_NONE` adds a None endpoint; by default only secure endpoints are advertised.
`endpoint`	The endpoint URL to advertise to clients
`application_uri`	Must match the URI in the server certificate (default `urn:pdcomm:opcua:server`).
`certificate_der`, `private_key_pem`	The server identity
`trusted_client_der`	The one client certificate to trust
`max_connections`, `max_sessions`	Concurrent secure channels (default 33) and sessions (default 32)

The SDK in-memory server accepts anonymous user tokens only. Add the variables remote clients should read and write with the PDCOMM_OPCUA_VARIABLE_PUBLIC flag. Variables without it return BadUserAccessDenied to anonymous sessions, and only the server application handles them, through pdcomm_opcua_server_set_value and pdcomm_opcua_server_read_value.