docs: secret store advantages (#279)

* docs: secret store advantages

* Update docs/preview/features/secret-store/index.md

Co-authored-by: Tom Kerkhove <[email protected]>

* Update docs/preview/features/secret-store/index.md

Co-authored-by: Tom Kerkhove <[email protected]>

* Update docs/preview/features/secret-store/index.md

Co-authored-by: Tom Kerkhove <[email protected]>

* Update docs/preview/features/secret-store/index.md

Co-authored-by: Tom Kerkhove <[email protected]>

* Update docs/preview/features/secret-store/index.md

Co-authored-by: Tom Kerkhove <[email protected]>

* pr-fix: update with design for security

* pr-fix: update with 'plug and play' title

* pr-fix: update with bullet points list

* pr-sug: keep using v for title

* pr-add: also add secret store advandates to current feature docs

Co-authored-by: Tom Kerkhove <[email protected]>

docs/features/secret-store/index.md

@@ -12,6 +12,24 @@ Once register, you can fetch all secrets by using `ISecretProvider` which will g
 
 > :bulb: See [this section](#using-secret-store-within-azure-functions) if you want to use the secret store functionality whitin Azure Functions.
 
+## Why would I use it?
+Why would you use our Arcus secret store instead of just using the Azure SDK directly to access Azure Key Vault secrets?
+
+The Arcus secret store has some advantages over using the Azure SDK or configuration directly:
+
+**✔ Caching**
+* We provide caching so the secret providers will not be called upon every secret retrieval. This helps you avoiding hitting service limitations and we provide [asynchronous cache invalidation](https://background-jobs.arcus-azure.net/features/security/auto-invalidate-secrets).
+
+**✔ Plug & play**
+* We support using multiple and combinations of secret providers so with a single secret retrieval can query multiple secret providers (also multiple Azure Key Vaults).
+
+**✔ Design for security** 
+* While using configuration for storing secrets can be good for development it is not a safe approach. With the secret store, we provide a single place to retrieve secrets instead of scattering the integration across the application. 
+* Seperating configuration data and sensitive secrets is key in developing secure projects. Vulnerabilities gets introduced when secrets are seen as data and are included in logs, for example. Or when expired secrets doesn't get transient handling upon retrieval.
+
+**✔ Extensibility**
+* Arcus secret store is highly extensible and can be extended with you own custom secret providers, in-memory secret providers for testing...
+
 ## Built-in secret providers
 Several built in secret providers available in the package.
 

docs/preview/features/secret-store/index.md

@@ -12,6 +12,24 @@ Once register, you can fetch all secrets by using `ISecretProvider` which will g
 
 > :bulb: See [this section](#using-secret-store-within-azure-functions) if you want to use the secret store functionality whitin Azure Functions.
 
+## Why would I use it?
+Why would you use our Arcus secret store instead of just using the Azure SDK directly to access Azure Key Vault secrets?
+
+The Arcus secret store has some advantages over using the Azure SDK or configuration directly:
+
+**✔ Caching**
+* We provide caching so the secret providers will not be called upon every secret retrieval. This helps you avoiding hitting service limitations and we provide [asynchronous cache invalidation](https://background-jobs.arcus-azure.net/features/security/auto-invalidate-secrets).
+
+**✔ Plug & play**
+* We support using multiple and combinations of secret providers so with a single secret retrieval can query multiple secret providers (also multiple Azure Key Vaults).
+
+**✔ Design for security** 
+* While using configuration for storing secrets can be good for development it is not a safe approach. With the secret store, we provide a single place to retrieve secrets instead of scattering the integration across the application. 
+* Seperating configuration data and sensitive secrets is key in developing secure projects. Vulnerabilities gets introduced when secrets are seen as data and are included in logs, for example. Or when expired secrets doesn't get transient handling upon retrieval.
+
+**✔ Extensibility**
+* Arcus secret store is highly extensible and can be extended with you own custom secret providers, in-memory secret providers for testing...
+
 ## Built-in secret providers
 Several built in secret providers available in the package.
 

docs/v1.5.0/features/secret-store/index.md

@@ -12,6 +12,24 @@ Once register, you can fetch all secrets by using `ISecretProvider` which will g
 
 > :bulb: See [this section](#using-secret-store-within-azure-functions) if you want to use the secret store functionality whitin Azure Functions.
 
+## Why would I use it?
+Why would you use our Arcus secret store instead of just using the Azure SDK directly to access Azure Key Vault secrets?
+
+The Arcus secret store has some advantages over using the Azure SDK or configuration directly:
+
+**✔ Caching**
+* We provide caching so the secret providers will not be called upon every secret retrieval. This helps you avoiding hitting service limitations and we provide [asynchronous cache invalidation](https://background-jobs.arcus-azure.net/features/security/auto-invalidate-secrets).
+
+**✔ Plug & play**
+* We support using multiple and combinations of secret providers so with a single secret retrieval can query multiple secret providers (also multiple Azure Key Vaults).
+
+**✔ Design for security** 
+* While using configuration for storing secrets can be good for development it is not a safe approach. With the secret store, we provide a single place to retrieve secrets instead of scattering the integration across the application. 
+* Seperating configuration data and sensitive secrets is key in developing secure projects. Vulnerabilities gets introduced when secrets are seen as data and are included in logs, for example. Or when expired secrets doesn't get transient handling upon retrieval.
+
+**✔ Extensibility**
+* Arcus secret store is highly extensible and can be extended with you own custom secret providers, in-memory secret providers for testing...
+
 ## Built-in secret providers
 Several built in secret providers available in the package.