Update to security docs (#425)

Co-authored-by: Yaron Schneider <yaronsc@microsoft.com>

concepts/README.md

@@ -1,6 +1,6 @@
 # Dapr concepts
 
-This directory contains Dapr concepts. The goal of these documents provide an understanding of the key concepts used in the Dapr documentation.
+This directory contains Dapr concepts. The goal of these topics is to provide an understanding of the key concepts used in the Dapr documentation.
 
 ## Contents
 
@@ -47,12 +47,13 @@ Dapr uses a modular design where functionality is delivered as a component. Each
 * Service discovery
 * Middleware
 * State
-* Secret store
+* Secrets
 * Tracing exporters
 
 ### Middleware components
 
-Dapr allows custom [**middleware**](./middleware/README.md) to be plugged into the request processing pipeline. Middleware can perform additional actions on a request, such as authentication, encryption and message transformation before the request is routed to the user code, or before the request is returned to the client. The middleware components is used with the Service Invocation building block.
+Dapr allows custom [**middleware**](./middleware/README.md) to be plugged into the request processing pipeline. Middleware can perform additional actions on a request, such as authentication, encryption and message transformation before the request is routed to the user code, or before the request is returned to the client.
+ The middleware components are used with the [Service Invocation](./service-invocation/README.md) building block.
 
 ## Secrets
 

concepts/secrets/README.md

@@ -1,14 +1,42 @@
-# Dapr Secrets Management
+# Dapr secrets management
 
 Dapr offers developers a consistent way to extract application secrets, without needing to know the specifics of the secret store being used.
-Secret stores are components in Dapr. Dapr allows users to write new secret stores component implementations that can be used both to hold secrets for other Dapr components (for example secrets used by a state store components to read/write state) as well as serving the application with a dedicated secret building block API. Using the secrets building block API, you can easily read secrets that can be used by the application from the a named secrets store. 
+Secret stores are components in Dapr. Dapr allows users to write new secret stores component implementations that can be used both to hold secrets for other Dapr components (for example secrets used by a state store components to read/write state) as well as serving the application with a dedicated secret building block API. Using the secrets building block API, you can easily read secrets that can be used by the application from a named secrets store. 
 
-Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores)
+Some examples for secret stores include `Kubernetes`, `Hashicorp Vault`, `Azure KeyVault`. See [secret stores](https://github.com/dapr/components-contrib/tree/master/secretstores) for the list of supported stores.
+
+See [Setup secret stores](https://github.com/dapr/docs/tree/master/howto/setup-secret-store) for a HowTo guide for setting up and using secret stores.
+
+## Referencing secret stores in Dapr components
+
+Instead of including credentials directly within a Dapr component file, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. This is preferred approach and is a recommended best practice especially in production environments. 
+
+For more information read [Referencing Secret Stores in Components](./component-secrets.md)
+
+
+## Using secrets in your application
+
+Application code can call the secrets building block API to retrieve secrets from Dapr supported secret stores that can be used in your code.
+
+For example, the diagram below shows an application requesting the secret called "mysecret" from a secret store called "vault" from a configured cloud secret store.
+
+<img src="../../images/secrets_cloud_stores.png" width=800>
+
+Applications can use the secrets API to access secrets from a Kubernetes secret store. In the example below, the application retrieves the same secret "mysecret" from a Kubernetes secret store.  
+
+<img src="../../images/secrets_kubernetes_store.png" width=800>
+
+In Azure Dapr can be configured to use Managed Identities to authenticate with Azure Key Vault in order to retrieve secrets. In the example below, an Azure Kubernetes Service (AKS) cluster is configured to use managed identities. Then Dapr uses [pod identities](https://docs.microsoft.com/en-us/azure/aks/operator-best-practices-identity#use-pod-identities) to retrieve secrets from Azure Key Vault on behalf of the application. 
+
+<img src="../../images/secrets_azure_aks_keyvault.png" width=800>
+
+Notice that in all of the examples above the application code did not have to change to get the same secret. Dapr did all the heavy lifting here via the secrets building block API and using the secret components.
+
+See [Access Application Secrets using the Secrets API](https://github.com/dapr/docs/tree/master/howto/get-secrets) for a How To guide to use secrets in your application.
+
+
+For detailed API information read [Secrets API](https://github.com/dapr/docs/blob/master/reference/api/secrets_api.md).
 
-## Referencing Secret Stores in Dapr Components
 
-Instead of including credentials within a Dapr component, you can place the credentials within a Dapr supported secret store and reference the secret within the Dapr component. For more information read [Referencing Secret Stores in Components](./component-secrets.md)
 
-## Retrieving Secrets
 
-Service code can call the secrets building block API to retrieve secrets out of the Dapr supported secret store. Read [Secrets API Specification](https://github.com/dapr/docs/blob/master/reference/api/secrets_api.md) for more information.

concepts/security/README.md

@@ -2,11 +2,12 @@
 
 - [Dapr-to-App Communication](#dapr-to-app-communication)
 - [Dapr-to-Dapr Communication](#dapr-to-dapr-communication)
+- [Component namespace scopes and secrets](#Component-namespace-scopes-and-secrets)
 - [Network Security](#network-security)
 - [Bindings Security](#bindings-security)
 - [State Store Security](#state-store-security)
 - [Management Security](#management-security)
-- [Component Secrets](#component-secets)
+
 
 ## Dapr-to-app communication
 
@@ -43,6 +44,12 @@ Specific details for how to do that can be found [here](../../howto/configure-mt
 
 <a href="https://ibb.co/XWFYsfY"><img src="https://i.ibb.co/rQ5d6Kd/Screen-Shot-2020-02-10-at-8-34-33-PM.png" alt="Screen-Shot-2020-02-10-at-8-34-33-PM" border="0"></a>
 
+## Component namespace scopes and secrets
+
+Dapr components are namespaced. That means a Dapr runtime sidecar instance can only access the components that have been deployed to the same namespace. See the [components scope topic](../../howto/components-scopes) for more details.
+
+Dapr components uses Dapr's built-in secret management capability to manage secrets. See the [secret topic](../secrets/README.md) for more details.
+
 ## Network security
 
 You can adopt common network security technologies such as network security groups (NSGs), demilitarized zones (DMZs) and firewalls to provide layers of protections over your networked resources.
@@ -64,7 +71,3 @@ Dapr uses the configured authentication method to authenticate with the underlyi
 When deploying on Kubernetes, you can use regular [Kubernetes RBAC]( https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to control access to management activities.
 
 When deploying on Azure Kubernetes Service (AKS), you can use [Azure Active Directory (AD) service principals]( https://docs.microsoft.com/en-us/azure/active-directory/develop/app-objects-and-service-principals) to control access to management activities and resource management.
-
-## Component secrets
-
-Dapr components uses Dapr's built-in secret management capability to manage secrets. Please see the [secret topic](../secrets/README.md) for more details.