Allow setting api key as environment variable (secret) (#2182)

* Update docs and sample * Remove connect/disconnect API * Allow overriding of strict compliance with messaging mode (#2167)
Azure · Feb 7, 2024 · 9499501 · 9499501
1 parent a88f6ec
commit 9499501
Show file tree

Hide file tree

Showing 32 changed files with 90 additions and 833 deletions.
diff --git a/deploy/docker/docker-compose.yaml b/deploy/docker/docker-compose.yaml
@@ -47,8 +47,13 @@ services:
       "--npd=${NODES_PER_DATASET:-10000}"
       ]
     environment:
-      EdgeHubConnectionString:
+      ADDITIONAL_CONFIGURATION: /run/secrets/publisher-secrets
+    secrets:
+      - publisher-secrets
     volumes:
       - shared:/shared:rw
 volumes:
   shared:
+secrets:
+  publisher-secrets:
+    file: ./publisher_secrets.txt
diff --git a/deploy/docker/publisher_secrets.txt b/deploy/docker/publisher_secrets.txt
@@ -0,0 +1 @@
+ApiKey=myKey1
diff --git a/docs/opc-publisher/api.md b/docs/opc-publisher/api.md
@@ -1352,80 +1352,6 @@ Get a server endpoint's certificate and certificate chain if available.
 * `application/x-msgpack`
 
 
-<a name="connect"></a>
-#### Connect
-```
-POST /v2/connect
-```
-
-
-##### Description
-Connect to a server using the provided connection request information. The connection is established and held active until cancelled or the publisher process is restarted.
-
-
-##### Parameters
-
-|Type|Name|Description|Schema|
-|---|---|---|---|
-|**Body**|**body**  <br>*required*|The request payload and connection information identifying the server to connect to perform the operation on.|[ConnectRequestModelRequestEnvelope](definitions.md#connectrequestmodelrequestenvelope)|
-
-
-##### Responses
-
-|HTTP Code|Description|Schema|
-|---|---|---|
-|**200**|Success|[ConnectResponseModel](definitions.md#connectresponsemodel)|
-
-
-##### Consumes
-
-* `application/json`
-* `text/json`
-* `application/*+json`
-* `application/x-msgpack`
-
-
-##### Produces
-
-* `text/plain`
-* `application/json`
-* `text/json`
-* `application/x-msgpack`
-
-
-<a name="disconnect"></a>
-#### Disconnect
-```
-POST /v2/disconnect
-```
-
-
-##### Description
-Can be used to disconnect a previously established connection.
-
-
-##### Parameters
-
-|Type|Name|Description|Schema|
-|---|---|---|---|
-|**Body**|**body**  <br>*required*|The request payload and connection information identifying the server to connect to perform the operation on.|[DisconnectRequestModelRequestEnvelope](definitions.md#disconnectrequestmodelrequestenvelope)|
-
-
-##### Responses
-
-|HTTP Code|Description|Schema|
-|---|---|---|
-|**200**|Success|No Content|
-
-
-##### Consumes
-
-* `application/json`
-* `text/json`
-* `application/*+json`
-* `application/x-msgpack`
-
-
 <a name="historygetservercapabilities"></a>
 #### HistoryGetServerCapabilities
 ```

diff --git a/docs/opc-publisher/commandline.md b/docs/opc-publisher/commandline.md
@@ -4,11 +4,13 @@
 
 > This documentation applies to version 2.9
 
-The following OPC Publisher configuration can be applied by Command Line Interface (CLI) options or as environment variable settings. Any CamelCase options can also be provided using environment variables (without the preceding `--`).
+The following OPC Publisher configuration can be applied by Command Line Interface (CLI) options or as environment variable settings. Any CamelCase options can also be provided using environment variables (without the preceding `--`). When both environment variable and CLI argument are provided, the command line option will override the environment variable.
 
-> IMPORTANT The command line of OPC Publisher only understands below command line options. You cannot specify environment variables on the command line (e.g., like `env1=value env2=value`). All option names are **case-sensitive**!
+> IMPORTANT: The command line of OPC Publisher only understands below command line options. You cannot specify environment variables on the command line (e.g., like `env1=value env2=value`). All option names are **case-sensitive**!
 
-When both environment variable and CLI argument are provided, the command line option will override the environment variable.
+Secrets such as `EdgeHubConnectionString`, other connection strings, or the `ApiKey` should never be provided on the command line or as environment variables. It should be avoided at all cost. A file using the `.env` format can be specified using the `ADDITIONAL_CONFIGURATION` environment variable. The contents will be loaded before the command line arguments are evaluated. If a file name is not provided via said environment variable, OPC Publisher tries to load the `/run/secrets/.env` file. This approach integrates well with [docker secrets](https://github.com/compose-spec/compose-spec/blob/master/05-services.md#secrets). An example of this can be found [here](https://raw.githubusercontent.com/Azure/Industrial-IoT/main/deploy/docker/docker-compose.yaml).
+
+> Please note that rolling of secrets is not supported and that any errors loading secrets is silently discarded.
 
 ```text
  ██████╗ ██████╗  ██████╗    ██████╗ ██╗   ██╗██████╗ ██╗     ██╗███████╗██╗  ██╗███████╗██████╗
@@ -17,8 +19,7 @@ When both environment variable and CLI argument are provided, the command line o
 ██║   ██║██╔═══╝ ██║         ██╔═══╝ ██║   ██║██╔══██╗██║     ██║╚════██║██╔══██║██╔══╝  ██╔══██╗
 ╚██████╔╝██║     ╚██████╗    ██║     ╚██████╔╝██████╔╝███████╗██║███████║██║  ██║███████╗██║  ██║
  ╚═════╝ ╚═╝      ╚═════╝    ╚═╝      ╚═════╝ ╚═════╝ ╚══════╝╚═╝╚══════╝╚═╝  ╚═╝╚══════╝╚═╝  ╚═╝
-                                                   2.9.4 (.NET 8.0.1/win-x64/OPC Stack 1.5.373.3)
-
+                                                 2.9.4 (.NET 8.0.1/win-x64/OPC Stack 1.5.373.121)
 General
 -------
 
@@ -67,6 +68,11 @@ General
                                reports its runtime state using a restart
                                message.
                                Default: `False` (disabled)
+      --api-key, --ApiKey=VALUE
+                             Sets the api key that must be used to authenticate
+                               calls on the publisher REST endpoint.
+                               Default: `not set` (Key will be generated if not
+                               available)
       --doa, --disableopenapi, --DisableOpenApiEndpoint[=VALUE]
                              Disable the OPC Publisher Open API endpoint
                                exposed by the built-in HTTP server.
@@ -76,12 +82,14 @@ Messaging configuration
 -----------------------
 
   -c, --strict, --UseStandardsCompliantEncoding[=VALUE]
-                             Use strict UA compliant encodings. Default is '
-                               false' for backwards (2.5.x - 2.8.x)
-                               compatibility. It is recommended to run the
-                               publisher in compliant mode for best
-                               interoperability.
-                               Default: `False`
+                             Use strict OPC UA standard compliance. It is
+                               recommended to run the publisher in compliant
+                               mode for best interoperability.
+                               Be aware that explicitly specifying other
+                               command line options can result in non-
+                               comnpliance despite this option being set.
+                               Default: `False` for backwards compatibility (2.
+                               5.x - 2.8.x)
       --nf, --namespaceformat, --DefaultNamespaceFormat=VALUE
                              The format to use when serializing node ids and
                                qualified names containing a namespace uri into

diff --git a/docs/opc-publisher/definitions.md b/docs/opc-publisher/definitions.md
@@ -321,40 +321,6 @@ Condition handling options model
 |**updateInterval**  <br>*optional*|Time interval for sending pending interval updates in seconds.|integer (int32)|
 
 
-<a name="connectrequestmodel"></a>
-### ConnectRequestModel
-Connect request
-
-
-|Name|Description|Schema|
-|---|---|---|
-|**expiresAfter**  <br>*optional*|Connection automatically closes after a<br>specified duration.|string (date-span)|
-|**header**  <br>*optional*||[RequestHeaderModel](definitions.md#requestheadermodel)|
-
-
-<a name="connectrequestmodelrequestenvelope"></a>
-### ConnectRequestModelRequestEnvelope
-Wraps a request and a connection to bind to a
-body more easily for api that requires a
-connection endpoint
-
-
-|Name|Schema|
-|---|---|
-|**connection**  <br>*required*|[ConnectionModel](definitions.md#connectionmodel)|
-|**request**  <br>*optional*|[ConnectRequestModel](definitions.md#connectrequestmodel)|
-
-
-<a name="connectresponsemodel"></a>
-### ConnectResponseModel
-Connect response
-
-
-|Name|Description|Schema|
-|---|---|---|
-|**connectionHandle**  <br>*optional*|This handle can be used to disconnect the<br>connection ahead of expiration.|string|
-
-
 <a name="connectionmodel"></a>
 ### ConnectionModel
 Connection model
@@ -569,30 +535,6 @@ Diagnostics configuration
 |**timeStamp**  <br>*optional*|Timestamp of request.<br>(default: client generated)|string (date-time)|
 
 
-<a name="disconnectrequestmodel"></a>
-### DisconnectRequestModel
-Disconnect request
-
-
-|Name|Description|Schema|
-|---|---|---|
-|**connectionHandle**  <br>*required*|This handle can be used to disconnect the<br>connection ahead of expiration.  <br>**Minimum length** : `1`|string|
-|**header**  <br>*optional*||[RequestHeaderModel](definitions.md#requestheadermodel)|
-
-
-<a name="disconnectrequestmodelrequestenvelope"></a>
-### DisconnectRequestModelRequestEnvelope
-Wraps a request and a connection to bind to a
-body more easily for api that requires a
-connection endpoint
-
-
-|Name|Schema|
-|---|---|
-|**connection**  <br>*required*|[ConnectionModel](definitions.md#connectionmodel)|
-|**request**  <br>*optional*|[DisconnectRequestModel](definitions.md#disconnectrequestmodel)|
-
-
 <a name="discoverycancelrequestmodel"></a>
 ### DiscoveryCancelRequestModel
 Discovery cancel request