From eecc1dc6310fa0d592ee37cf47716712ed4bab22 Mon Sep 17 00:00:00 2001 From: Elizabeth J Lee Date: Mon, 21 Aug 2023 17:00:42 -0700 Subject: [PATCH 1/2] docs: Add general uri4files feature description Closes #1193 Signed-off-by: Elizabeth J Lee --- docs_src/microservices/general/index.md | 32 +++++++++++++++++++++++++ 1 file changed, 32 insertions(+) diff --git a/docs_src/microservices/general/index.md b/docs_src/microservices/general/index.md index 0d3ebddbb0..f991655d5f 100644 --- a/docs_src/microservices/general/index.md +++ b/docs_src/microservices/general/index.md @@ -84,3 +84,35 @@ All services have the ability to collect the following common service metrics - **SecuritySecretsStored** - Count of secret stored to the service's Secret Store. - **SecurityConsulTokensRequested** - Count of Consul tokens been requested. - **SecurityConsulTokenDuration** - Duration of obtaining Consul token. + +## URI for Files + +Different files like load configuration, units of measurements, device profiles, device definitions, and provision watches can be loaded either from the local file system or from a remote location. +For the remote location, HTTP and HTTPS URIs are supported. When using HTTPS, certificate validation is performed using the system's built-in trust anchors. + +### Authentication + +#### username-password in URI (not recommended) + +Users can specify the username-password (`:@`) in the URI as plain text. +This is ok network wise when using HTTPS, but if the credentials are specified in configuration or other service files, this is not a good practice to follow. + +!!! example "Example - configuration file with plain text `username-password` in URI" + ``` + [UoM] + UoMFile = "https://myuser:mypassword@example.com/uom.yaml" + ``` + +#### Secure Credentials (preferred) + +The `edgexSecretName` query parameter can be specified in the URI as a secure way for users to specify credentials. +This parameter specifies a Secret Name from the service's Secret Store where the credentials reside. + +!!! example "Example - configuration file with `edgexSecretName` query parameter" +``` +[UoM] +UoMFile = "https://example.com/uom.yaml?edgexSecretName=mySecretName" +``` + +The authentication type and credentials are contained in the secret data specified by the Secret Name. +Only `httpheader` is currently supported. \ No newline at end of file From 1253496e78f41a29777e549ff05712ec96a0829d Mon Sep 17 00:00:00 2001 From: Elizabeth J Lee Date: Tue, 22 Aug 2023 16:07:01 -0700 Subject: [PATCH 2/2] fix: address pr comments Signed-off-by: Elizabeth J Lee --- docs_src/microservices/general/index.md | 29 ++++++++++++++++------ docs_src/security/SeedingServiceSecrets.md | 4 +-- 2 files changed, 23 insertions(+), 10 deletions(-) diff --git a/docs_src/microservices/general/index.md b/docs_src/microservices/general/index.md index f991655d5f..b56d077b40 100644 --- a/docs_src/microservices/general/index.md +++ b/docs_src/microservices/general/index.md @@ -87,7 +87,7 @@ All services have the ability to collect the following common service metrics ## URI for Files -Different files like load configuration, units of measurements, device profiles, device definitions, and provision watches can be loaded either from the local file system or from a remote location. +Different files like configurations, units of measurements, device profiles, device definitions, and provision watchers can be loaded either from the local file system or from a remote location. For the remote location, HTTP and HTTPS URIs are supported. When using HTTPS, certificate validation is performed using the system's built-in trust anchors. ### Authentication @@ -106,13 +106,26 @@ This is ok network wise when using HTTPS, but if the credentials are specified i #### Secure Credentials (preferred) The `edgexSecretName` query parameter can be specified in the URI as a secure way for users to specify credentials. -This parameter specifies a Secret Name from the service's Secret Store where the credentials reside. +When running in secure mode, this parameter specifies a Secret Name from the service's Secret Store where the credentials must be [seeded](../../security/SeedingServiceSecrets.md#seeding-service-secrets). +If insecure mode is running, `edgexSecretName` must be specified in the [InsecureSecrets](../configuration/CommonConfiguration.md#common-configuration-properties) section of the configuration. !!! example "Example - configuration file with `edgexSecretName` query parameter" -``` -[UoM] -UoMFile = "https://example.com/uom.yaml?edgexSecretName=mySecretName" -``` + ``` + [UoM] + UoMFile = "https://example.com/uom.yaml?edgexSecretName=mySecretName" + ``` -The authentication type and credentials are contained in the secret data specified by the Secret Name. -Only `httpheader` is currently supported. \ No newline at end of file +The authentication type and credentials are contained in the secret data specified by the Secret Name. +Only `httpheader` is currently supported. The `headername` specifies the authentication method (ie Basic Auth, API-Key, Bearer) + +!!! example "Example - secret data using `httpheader`" + ``` + type=httpheader + headername= + headercontents= + ``` + For a request header set as: + ``` + GET https://example.com/uom.yaml HTTP/1.1 + : + ``` \ No newline at end of file diff --git a/docs_src/security/SeedingServiceSecrets.md b/docs_src/security/SeedingServiceSecrets.md index e33bcfdb6c..3b683f0afc 100644 --- a/docs_src/security/SeedingServiceSecrets.md +++ b/docs_src/security/SeedingServiceSecrets.md @@ -78,10 +78,10 @@ During service start-up, after `SecretStore` initialization, the service's secre } ``` -The secrets marked with `imported=true` are ignored the next time the service starts up since they are already in the the service's `SecretStore`. If the Secret Store service's persistence is cleared, the original version of service's secrets file will need to be provided for the next time the service starts up. +The secrets marked with `imported=true` are ignored the next time the service starts up since they are already in the service's `SecretStore`. If the Secret Store service's persistence is cleared, the original version of service's secrets file will need to be provided for the next time the service starts up. !!! note - The secrets file must be have write permissions for the file to be scrubbed of the secret data. If not the service with fail to start-up with an error re-writing the file. + The secrets file must have write permissions for the file to be scrubbed of the secret data. If not the service will fail to start-up with an error re-writing the file. ## Disable Scrubbing