[docs] Web encryption configuration documentation (#1177)

* [docs] Web encryption configuration documentation

* remove condition from config

---------

Co-authored-by: Irina Southwell <irinasouthwell@gmail.com>

backend/mr/src/main/kotlin/io/featurehub/mr/resources/SystemConfigResource.kt

@@ -27,9 +27,6 @@ class SystemConfigResource @Inject constructor(
     if (!authManagerService.isOrgAdmin(from)) {
       throw ForbiddenException()
     }
-    if (!WebhookEncryptionFeature.isWebhookEncryptionEnabled) {
-      throw NotFoundException()
-    }
 
     try {
       return SystemConfigs().configs(systemConfigApi.updateConfigs(updatedSystemConfigs.configs, from.id!!.id, false))
@@ -70,10 +67,6 @@ class SystemConfigResource @Inject constructor(
   ): SystemConfigs {
     if (!SystemConfigApi.systemConfigEnabled) throw NotFoundException()
 
-    if (!WebhookEncryptionFeature.isWebhookEncryptionEnabled) {
-      throw NotFoundException()
-    }
-
     if (!authManagerService.isOrgAdmin(authManagerService.from(securityContext))) {
       throw ForbiddenException()
     }

docs/modules/ROOT/pages/configuration.adoc

@@ -104,7 +104,7 @@ Edge publishes on the following channels (and consumed by MR):
 
 - `featurehub/mr-updates-queue` - configured using `cloudevents.edge-mr.nats.channel-name`. This sends
 back updates from PUT requests on the FeatureApi by valid ApiKeys who have write permissions, and also
-any other traffic (e.g. webhook status data). 
+any other traffic (e.g. webhook status data).
 
 Edge publishes on the Stats channel only if you have turned it on:
 - `featurehub/edge-stats` - configured using `cloudevents.stats.nats.channel-name`
@@ -175,7 +175,7 @@ Note, internally webhooks are dependent on enrichment pipeline, see below for `e
 200 range (including 0 - where a connection is refused) then the FeatureHub app begins a
 countdown, where after n number of retries, it will automatically disable the webhook. Default value is 5. To change, set to the desired number: `webhook.features.max-fails=10`
 - `enricher.enabled` - The enricher pipeline, currently only required to be enabled for webhooks to work. True by default. To reduce unnecessary "load" if you do not use webhooks, disable as follows: `enricher.enabled=false`
-- `ga.tracking-id` - If provided, this will enable tracking on the usage of your Admin UI and tell you what features people are using. 
+- `ga.tracking-id` - If provided, this will enable tracking on the usage of your Admin UI and tell you what features people are using.
 - `mr.dacha2.api-keys` - This swaps the Dacha2 endpoint to the public interface and protects it to expect a `key` header with one of the keys listed here. See Dacha2 below for more details.
 
 ==== SDK Feature Extension Properties
@@ -186,7 +186,7 @@ using the Service Accounts. Each Service Account has Read/Unlock/Lock/Change Val
  - `sdk.feature.properties` - In the Management Repository (and Party Server/Party-Server-ish) you can define this environment variable or system property and it is a *name/value* pair of data which will appear in your "Feature Properties" section in your SDK (if the associated Service Account is given permission). It is an advanced feature and it requires understanding of the Object model of Feature Hub - and it is available only in the Open Source version.
 - `sdk.feature.properties.size` - this controls the cache size. If you are using metadata (see below), the system will hold onto the JSON parsed metadata to speed up publishing, it will hold onto this many features. It is set by default to 100.
 
-The *name/value* pairs are pairs of names and https://github.com/jknack/handlebars.java?tab=readme-ov-file#helpers[Handlebars templates]. The templates feature lets you walk the tree of data provided. 
+The *name/value* pairs are pairs of names and https://github.com/jknack/handlebars.java?tab=readme-ov-file#helpers[Handlebars templates]. The templates feature lets you walk the tree of data provided.
 
 The values in the name/value pair can be actual templates, or if the value starts with a `#` then a reference to an absolute file location. The latter is useful if you wish to store your definitions in files as part of your Kubernetes deployment. We recommend experimenting with a local copy of FeatureHub to get your templates just the way you want them.
 
@@ -196,7 +196,7 @@ An example:
 sdk.feature.properties=appName={{{feature.parentApplication.name}}},portfolio={{{feature.parentApplication.portfolio.name}}},category={{{metadata.category}}}
 ----
 
-If you curl your SDK endpoint, you will see something like: 
+If you curl your SDK endpoint, you will see something like:
 
 ----
 "fp":{"appName":"D2nbUfr8LH1i","portfolio":"D2nbUfr8LH1i","category":"shoes"}
@@ -217,7 +217,7 @@ In addition to these we give you:
 - `pubFeatureValue` - this is the value of the feature (if any) that is about to be published, can be null and is also https://github.com/featurehub-io/featurehub/blob/main/infra/api-bucket/files/webhooks/1.2.1.yaml#L152[documented in the API].
 - `fgStrategies` - these are the strategies coming from feature groups this feature is associated with. They are RolloutStrategies and basically follow the same https://github.com/featurehub-io/featurehub/blob/main/infra/api-bucket/files/webhooks/1.2.1.yaml#L187[API pattern].
 
-A few things to note 
+A few things to note
 
 - in Handlebars if you don't want it to _HTML escape_ your data, you need to use triple braces, e.g. `{{{feature.parentApplication.name}}}`.
 - null values are safe to navigate, Handlebars will just return an empty value
@@ -309,7 +309,7 @@ cache any headers. It is on by default. See also the `cache-control.web` configu
 - `opentelemetry.valid-baggage-headers` - this allows you to filter out the valid W3C Baggage headers that you will accept from incoming clients. The Web UI adds its own (the request-id for that session) and the
 server adds in the UUID of the user who is performing the action. Your clients can add anything further
 they wish to baggage headers, but you need to specify them here to allow them to be added to the baggage.
-The side effect of this is that _all baggage_ will be logged in the logs. This gives you very good 
+The side effect of this is that _all baggage_ will be logged in the logs. This gives you very good
 OpenTelemetry and log level tracebility for actions from clients.
 
 .Config
@@ -347,6 +347,43 @@ audit.logging.user=true
 
 ----
 
+==== Encryption
+
+To enable link:slack-integration.adoc[Slack integration] or URL and header encryption for Webhooks,
+you will need to specify an encryption key/password to be used for these items which are encrypted at
+rest (i.e. they are encrypted until they are explicitly used, in Slack's case they are encrypted
+until the system is about to POST to Slack, in Webhooks the same is true).
+
+Config options to enable encryption:
+
+- `webhooks.encryption.password` - this is encryption key/password. Required for Slack integration to work. This can
+be set to anything, we recommend using a randomiser or password generator to set a reasonably long
+key (16+ characters). 
+- `webhooks.decryption.enabled` - this defaults to `false` - which means
+1) Once Slack Bot User OAuth Token is set in the Admin app, it cannot be viewed again and will show as hidden. Set this to `true` to be able to view or change the token.
+2) Once webhook URL or header value is set and an option to "Encrypt" is checked in the Admin app, they cannot be viewed again and will be shown as hidden. Set this to `true` to be able to view, delete or reset the webhook URL or header values.
+
+NOTE: *If you are migrating from v1.8.0 to 1.8.1 only, earlier version not affected.* +
+The `webhooks.encryption.password` property was set at a default value in `1.8.0` but it was removed as a security precaution in `1.8.1`. It will affect your Slack integration if you used it in 1.8.0. You will need to: +
+1. Set this property with your own generated value, e.g. `webhooks.encryption.password=foobar`, then set `webhooks.decryption.enabled=true` +
+2. Go to FeatureHub Admin UI System Config page, select disable Slack checkbox, reveal and copy Slack Bot User OAuth Token then clear it and Save. Re-enter Slack Bot User OAuth Token and Save. This should re-enable Slack with new encryption key. +
+If you cannot view and copy Slack Bot User OAuth Token, go to Slack Workspace settings here https://api.slack.com/apps and find FeatureHub app. Go to OAuth and Permissions screen and find your Slack Bot User OAuth Token.   
+
+
+===== Kubernetes
+
+The official helm chart has configuration to support supplying an external secret which is your
+key. Please refer to the Helm chart documentation.
+
+===== Removing the existing Slack Bot User OAuth Token from the database
+
+To remove your Slack token from the database use:
+
+[source,sql]
+----
+delete from fh_sysconfig where code='slack.bearerToken';
+----
+
 ==== OpenTelemetry AutoConfiguration
 
 OpenTelemetry configuration is done using

docs/modules/ROOT/pages/evaluation.adoc

@@ -17,6 +17,10 @@ docker run --network host --user 999:999 -p 8085:8085 -v $HOME/party:/db feature
 
 NOTE: `$HOME/tmp` is where you wish to store the database (h2).
 
+If you wish to enable Slack integration or use encryption in your local database, add the
+option: `-e webhooks.encryption.password=<random-password>` - where `random-long-password` is a made up key, like you would get from a password generator. This is used to ensure secure third-party
+tokens are encrypted when in the database. See link:configuration.adoc#_encryption[configuration documentation] for more details.
+
 An alternative is to use the link:installation{outfilesuffix}#_evaluation_deployment[Docker Compose] based
 evaluation example.
 

docs/modules/ROOT/pages/slack-integration.adoc

@@ -2,6 +2,8 @@
 
 You can integrate FeatureHub with Slack to receive feature updates directly into a Slack channel.
 
+IMPORTANT: For Open Source version there is a pre-condition to set an link:configuration.adoc#_encryption[encryption key]
+
 image::slack-message-example.png[Slack install to workspace, 800]
 
 == FeatureHub Slack Integration
@@ -48,6 +50,26 @@ IMPORTANT:  If you are sending Slack updates to a private channel, you may need
 
 You should now be able to receive Slack updates. Message delivery status log is available to indicate any errors in the case of unsuccessful message delivery.
 
+== Configuring your own message
+
+The Slack message is a transformed variant of the "Difference Payload" that FeatureHub emits when
+a feature changes. This payload is documented using https://github.com/featurehub-io/featurehub/blob/main/backend/messaging-api/messaging-api.yaml#L18[OpenAPI here].
+
+The payload is transformed and the format used is the `DEFAULT_MESSAGE_FORMAT` https://github.com/featurehub-io/featurehub/blob/main/backend/messaging-delivery/src/main/kotlin/io/featurehub/messaging/slack/SlackInternalDeliveryListener.kt[documented in the
+code].
+
+If there is a demand we can provide an in-situ override capability, but the best way to get flexibility in the message to Slack is to use the Offloading capability below.
+
 == Offloading Slack delivery to an external app (FeatureHub Open Source only)
 
 If you would like to customise Slack messages or perform any other additional operations with raw FeatureHub events, there is an option to use an external service that you can build yourself. You can connect your service by providing a URL and additional headers on the Slack System Config page.
+
+FeatureHub provides a sample stack that would allow you to run an external service such as:
+
+- an AWS lambda
+- a GCP cloud function
+- a Knative express service
+
+You get complete control over how messages are formatted and delivered if you do this.
+
+The sample repository and code is https://github.com/featurehub-io/featurehub-messaging[here].

docs/modules/ROOT/pages/system-configuration.adoc

@@ -12,6 +12,9 @@ image::fh-website-url-config.png[FeatureHub system config website URL, 1500]
 
 This is a global Slack setup page, which will help you to connect FeatureHub organisation (or deployed instance of Open Source version) with Slack. See more details on link:slack-integration.adoc[Slack integration] page.
 
+link:configuration.adoc#_encryption[Encryption needs to be enabled and configured] to allow for Slack to be
+enabled. Slack will not appear if and encryption key is not configured.
+
 image::slack-system-config.png[Slack system config, 1500]
 
 

docs/modules/ROOT/pages/webhooks-configuration.adoc

@@ -2,10 +2,13 @@
 
 This section explains if additional configuration is needed to support webhooks functionality.
 
-NOTE: If your installation is using NATS, you are not required to do any additional configuration, NATS will automatically start
+== NATS
+If your installation is using NATS, you are not required to do any additional configuration, NATS will automatically start
 processing updates for environments/features relevant to the webhooks.
 
-If your installation is using Pub/Sub, you will need to do additional configuration as described below.
+== Google(TM) Pub/Sub
+
+If your installation is using *Google(TM) Pub/Sub*, you will need to do additional configuration as described below.
 
 == Dacha2
 
@@ -16,7 +19,7 @@ Webhooks use the new Feature Enrichment pipeline, which will take the single
 feature update (e.g. a feature changed, was added or was deleted), and pull all of the environment's
 data out of the cache and then publish the complete set of Feature data for that environment. But
 you only want *one* of the Dacha2 instances processing that. As such, you need to a new subscriber
-just for the enrichment pipeline.
+just for the enrichment channel. This will allow the Dacha2 instances to balance the load between each other. 
 
 ----
 cloudevents.enricher.pubsub.subscription-name=enricher-updates-sub

docs/modules/ROOT/pages/webhooks.adoc

@@ -1,6 +1,6 @@
 = Webhooks
 
-Webhooks is a powerful mechanism that allows you to subscribe to feature flag events and changes. For example, this can be useful when integrating with other systems and workflows to enable actions based on feature flags updates, this could be CI/CD pipelines, deployment systems, notification systems and so on. 
+Webhooks is a powerful mechanism that allows you to subscribe to feature flag events and changes. For example, this can be useful when integrating with other systems and workflows to enable actions based on feature flags updates, this could be CI/CD pipelines, deployment systems, notification systems and so on.
 
 FeatureHub allows you to configure a URL endpoint and appropriate authorisation or configuration headers, to which it will deliver the complete
 set of feature flags changes. Such as changes of feature values, feature strategies, adding or deleting features.
@@ -10,10 +10,10 @@ To access Webhooks Configuration, select "Integrations" from the main menu and s
 
 image:webhook-config.png[Webhook Config]
 
-Webhooks configuration is designed to be per environment for a given application - you can have one webhook per environment. 
+Webhooks configuration is designed to be per environment for a given application - you can have one webhook per environment.
 
-You can enable/disable a webhook, configure the url destination and any extra headers you need. Options to encrypt URL and headers are available. Once you have
-saved configuration, you can test it out. Test button will only appear if webhook is enabled. Switch to the Webhooks History sub-tab to see the webhook history results/logs. 
+You can enable/disable a webhook, configure the url destination and any extra headers you need. Optionally you can enable encryption for URL and headers in the system config, see link:configuration.adoc#_encryption[encryption]. Once you have
+saved webhook settings, you can test it out. Test button will only appear if webhook is enabled. Switch to the Webhooks History sub-tab to see the webhook history results/logs.
 
 image:webhook_history.png[Webhook History]