Add docs for scoping secrets (#799)

* Add docs for scoping secrets

* add uniqueness doc.

* Rephrase

Co-authored-by: Mark Chmarny <mchmarny@users.noreply.github.com>

concepts/configuration/README.md

@@ -44,6 +44,7 @@ The following configuration settings can be applied to Dapr sidecars;
 
 * [Observability distributed tracing](../observability/traces.md)
 * [Middleware pipelines](../middleware/README.md)
+* [Scoping secrets](../../howto/secrets-scopes/README.md)
 
 ### Tracing configuration
 
@@ -102,6 +103,35 @@ spec:
       type: middleware.http.oauth2
 ```
 
+### Scoping secrets
+
+In addition to scoping which application can access given secret store component, the secret store component itself can be scoped to one or more secrets. By defining `allowedSecrets` and/or `deniedSecrets` list, applications can be restricted access to specific secrets.
+
+The `secrets` section under the `Configuration` spec contains the following properties:
+
+```yml
+secrets:
+  scopes:
+    - storeName: kubernetes
+      defaultAcess: allow
+      allowedSecrets: ["redis-password"]
+    - storeName: localstore
+      defaultAccess: allow
+      deniedSecrets: ["redis-password"]
+```
+
+The following table lists the different properties.
+
+Property | Type | Description
+---- | ------- | -----------
+storeName  | string | name of the secret store component. storeName must be unique within the list.
+defaultAccess  | string | access modifier. Accepted values "allow"(default) or "deny".
+allowedSecrets | list   | list of secret keys that can be accessed. 
+deniedSecrets  | list   | list of secret keys that cannot be accessed.
+
+When an `allowedSecrets` list is present with at least one element, only those secrets defined in the list can be accessed by the application.
+
+
 ## Kubernetes control plane configuration
 There is a single configuration file called `default` installed with the control plane system services that applies global settings.  
 

howto/secrets-scopes/README.md

@@ -0,0 +1,88 @@
+# Limit the secrets that can be read from secret stores 
+
+Follow [these instructions](../setup-secret-store) to configure secret store for an application. Once configured, any secret defined within that store will be accessible from the Dapr application.
+
+To limit the secrets to which the Dapr application has access, users can define secret scopes by augmenting existing configuration CRD with restrictive permissions.
+
+Follow [these instructions](../../concepts/configuration/README.md) to define a configuration CRD.
+
+## Scenario 1 : Deny access to all secrets for a secret store
+
+In Kubernetes cluster, the native Kubernetes secret store is added to Dapr application by default. In some scenarios it may be necessary to deny access to Dapr secrets for a given application. To add this configuration follow the steps below:
+
+Define the following `appconfig.yaml` and apply it to the Kubernetes cluster using the command `kubectl apply -f appconfig.yaml`.
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: appconfig
+spec:
+  secrets:
+    scopes:
+      - storeName: kubernetes
+        defaultAcess: deny
+```
+
+For applications that need to be deined access to the Kubernetes secret store, follow [these instructions](../configure-k8s/README.md), and add the following annotation to the application pod. 
+
+```yaml
+dapr.io/config: appconfig
+```
+
+With this defined, the application no longer has access to Kubernetes secret store. 
+
+## Scenario 2 : Allow access to only certain secrets in a secret store
+
+To allow a Dapr application to have access to only certain secrets, define the following `config.yaml`:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: appconfig
+spec:
+  secrets:
+    scopes:
+      - storeName: vault
+        defaultAcess: deny
+        allowedSecrets: ["secret1", "secret2"]
+```
+
+This example defines configuration for secret store named vault. The default access to the secret store is `deny`, whereas some secrets are accessible by the application based on the `allowedSecrets` list. Follow [these instructions](../../concepts/configuration/README.md) to apply configuration to the sidecar.
+
+## Scenario 3: Deny access to certain senstive secrets in a secret store
+
+Define the following `config.yaml`:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: appconfig
+spec:
+  secrets:
+    scopes:
+      - storeName: vault
+        defaultAcess: allow # this is the default value, line can be omitted
+        deniedSecrets: ["secret1", "secret2"]
+```
+
+The above configuration explicitly denies access to `secret1` and `secret2` from the secret store named vault while allowing access to all other secrets. Follow [these instructions](../../concepts/configuration/README.md) to apply configuration to the sidecar.
+
+## Permission priority
+
+The `allowedSecrets` and `deniedSecrets` list values take priorty over the `defaultAccess`.
+
+Scenarios | defaultAccess | allowedSecrets | deniedSecrets | permission
+---- | ------- | -----------| ----------| ------------
+1 - Only default access  | deny/allow | empty | empty | deny/allow
+2 - Default deny with allowed list | deny | ["s1"] | empty | only "s1" can be accessed
+3 - Default allow with deneied list | allow | empty | ["s1"] | only "s1" cannot be accessed
+4 - Default allow with allowed list  | allow | ["s1"] | empty | only "s1" can be accessed
+5 - Default deny with denied list  | deny | empty | ["s1"] | deny
+6 - Default deny/allow with both lists  | deny/allow | ["s1"] | ["s2"] | only "s1" can be accessed
+
+
+
+