middleware doc (#274)

* middleware doc

* added oauth how-to

* typos and clarifications

concepts/README.md

@@ -16,22 +16,30 @@ This directory contains various Dapr concepts. The goal of these documents is to
   
   Dapr uses a modular design, in which functionalities are grouped and delivered by a number of *components*, such as  [pub/sub](./publish-subscribe-messaging/README.md) and [secrets](./components/secrets.md). Many of the components are pluggable so that you can swap out the default implementation with your custom implementations. 
 
+* [**Configuration**](./configuration/README.md)
+
+  Dapr configuration defines a policy that affects how a Dapr sidecar hebavies, such as [distributed tracing](distributed-tracing/README.md) and [custom pipeline](middleware/middleware.md).
+
 * [**Distributed Tracing**](./distributed-tracing/README.md)
 
   Distributed tracing collects and aggregates trace events by transactions. It allows you to trace the entire call chain across multiple services. Dapr integrates with [OpenTelemetry](https://opentelemetry.io/) for distributed tracing and metrics collection. 
 
+* [**Middleware**](./middleware/middleware.md)
+  
+  Dapr allows custom middleware 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.
+
 * [**Publish/Subscribe Messaging**](./publish-subscribe-messaging/README.md)
   
   Pub/Sub is a loosely coupled messaging pattern where senders (or publishers) publishes messages to a topic, to which subscribers subscribe. Dapr natively supports the pub/sub pattern.
 
-* [**Service Invocation**](./service-invocation/service-invocation.md)
-  
-  Service invocation enables applications to communicate with each other through well-known endpoints in the form of http or gRPC messages. Dapr provides an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling.
-
 * [**Secrets**](./components/secrets.md)
 
   In Dapr, a secret is any piece of private information that you want to guard against unwanted users. Dapr offers a simple secret API and integrates with secret stores such as Azure Key Vault and Kubernetes secret stores to store the secrets.
 
+* [**Service Invocation**](./service-invocation/service-invocation.md)
+  
+  Service invocation enables applications to communicate with each other through well-known endpoints in the form of http or gRPC messages. Dapr provides an endpoint that acts as a combination of a reverse proxy with built-in service discovery, while leveraging built-in distributed tracing and error handling.
+
 * [**State**](./state-management/state-management.md)
 
   Application state is anything an application wants to preserve beyond a single session. Dapr allows pluggable state stores behind a key/value-based state API.

concepts/configuration/README.md

@@ -0,0 +1,9 @@
+# Configuration
+
+Dapr configuration is a configuration file (in local mode) or a Kubernetes configuration object (in Kubernetes mode). A Dapr sidecar can apply a configuration by using a ```dapr.io/config``` annotation (in Kubernetes mode) or by using a ```--config``` switch with ```dapr run```.
+
+A Dapr configuration configures:
+
+* [distributed tracing](../distributed-tracing/README.md)
+* [custom pipeline](../middleware/middleware.md)
+

concepts/extending-dapr/extending-dapr.md

@@ -1,3 +0,0 @@
-# documentation 
-
-Content for this file to be added

concepts/middleware/middleware.md

@@ -0,0 +1,52 @@
+# Middleware 
+
+Dapr allows custom processing pipelines to be defined by chaining a series of custom middleware. A request goes through all defined middleware before it's routed to user code, and it goes through the defined middleware (in reversed order) before it's returned to the client, as shown in the following diagram.
+
+![Middleware](../../images/middleware.png)
+
+## Customize processing pipeline
+When launched, a Dapr sidecar contructs a processing pipeline. The pipeline consists of a [tracing middleware](../distributed-tracing/README.md) (when tracing is enabled) and a CORS middleware by default. Additional middleware, configured by a Dapr [configuration](../configuration/README.md), are added to the pipeline in the order as they are defined. The pipeline applies to all Dapr API endpoints, including state, pub/sub, direct messaging, bindings and others.
+
+> **NOTE:** Dapr provides a **middleware.http.uppercase** middleware that doesn't need any configurations. The middleware changes all texts in a request body to uppercase. You can use it to test/verify if your custom pipeline is in place.
+
+The following configuration defines a custom pipeline that uses a OAuth 2.0 middleware and an uppercase middleware. In this case, all requests are authorized through the OAuth 2.0 protocol, and transformed to uppercase texts, before they are forwarded to user code.
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: pipeline
+spec:
+  httpPipeline:
+    handlers:
+    - name: middleware.http.oauth2
+    - name: middleware.http.uppercase    
+```
+
+> **NOTE:** in future versions, a middleware can be conditionally applied by matching selectors.
+
+## Writing a custom middleware
+
+Dapr uses [FastHTTP](https://github.com/valyala/fasthttp) to implement it's HTTP server. Hence, your HTTP middleware needs to be written as a FastHTTP handler. Your middleware needs to implement a Middleware interface, which defines a **GetHandler** method that returns a **fasthttp.RequestHandler**:
+
+```go
+type Middleware interface {
+	GetHandler(metadata Metadata) (func(h fasthttp.RequestHandler) fasthttp.RequestHandler, error)
+}
+```
+Your handler implementation can include any inboud logic, outbound logic, or both:
+
+```go
+func GetHandler(metadata Metadata) fasthttp.RequestHandler {
+	return func(h fasthttp.RequestHandler) fasthttp.RequestHandler {
+		return func(ctx *fasthttp.RequestCtx) {
+			//inboud logic
+            h(ctx)  //call the downstream handler
+            //outbound logic
+		}
+    }
+}
+```
+Your code should be contributed to the https://github.com/dapr/components-contrib repository, under the */middleware* folder. Then, you'll need to submit another pull request against the https://github.com/dapr/dapr repository to register the new middleware type. You'll need to modify the **Load()** method under https://github.com/dapr/dapr/blob/master/pkg/components/middleware/http/loader.go to register your middleware using the **RegisterMiddleware** method.
+
+

howto/authorization-with-oauth/README.md

@@ -0,0 +1,100 @@
+# Authorization with oAuth
+
+Dapr OAuth 2.0 [middleware](../../concepts/middleware/middleware.md) allows you to enable [OAuth](https://oauth.net/2/) authorization on Dapr endpoints for your web APIs, using the [Authorization Code Grant flow](https://tools.ietf.org/html/rfc6749#section-4.1). When the middleware is enabled, any method invocation through Dapr needs to be authorized before getting passed to the user code.
+
+## Register your application with a authorization server
+
+Different authorization servers provide different application registration experiences. Here are some samples:
+
+* [Azure AAD](https://docs.microsoft.com/en-us/azure/active-directory/develop/v1-protocols-oauth-code)
+* [Facebook](https://developers.facebook.com/apps)
+* [Fitbit](https://dev.fitbit.com/build/reference/web-api/oauth2/)
+* [GitHub](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/)
+* [Google APIs](https://console.developers.google.com/apis/credentials/consen)
+* [Slack](https://api.slack.com/docs/oauth)
+* [Twitter](http://apps.twitter.com/)
+
+To figure the Dapr OAuth middleware, you'll need to collect the following information:
+
+* Client ID (see [here](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/))
+* Client secret (see [here](https://www.oauth.com/oauth2-servers/client-registration/client-id-secret/))
+* Scopes (see [here](https://oauth.net/2/scope/))
+* Authorization URL
+* Token URL
+
+Authorization/Token URLs of some of the popular authorization servers:
+
+|Server|Authorization URL|Token URL|
+|--------|--------|--------|
+|Azure AAD|https://login.microsoftonline.com/{tenant}/oauth2/authorize|https://login.microsoftonline.com/{tenant}/oauth2/token|
+|GitHub|https://github.com/login/oauth/authorize|https://github.com/login/oauth/access_token|
+|Google|https://accounts.google.com/o/oauth2/v2/auth|https://accounts.google.com/o/oauth2/token https://www.googleapis.com/oauth2/v4/token|
+|Twitter|https://api.twitter.com/oauth/authorize|https://api.twitter.com/oauth2/token|
+
+## Define the middleware component definition
+
+An OAuth middleware is defined by a component:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Component
+metadata:
+  name: oauth2
+spec:
+  type: middleware.http.oauth2
+  metadata:
+  - name: clientId
+    value: "<your client ID>"
+  - name: clientSecret
+    value: "<your client secret>"
+  - name: scopes
+    value: "<comma-separated scope names>"
+  - name: authURL
+    value: "<authroziation URL>"
+  - name: tokenURL
+    value: "<token exchange URL>"
+  - name: redirectURL
+    value: "<redirect URL>"
+  - name: authHeaderName
+    value: "<header name under which the secret token is saved>"
+```
+
+## Define a custom pipeline
+
+To use the OAuth middleware, you should create a [custom pipeline](../../concepts/middleware/middleware.md) using [Dapr configuration](../../concets/../concepts/configuration/README.md), as shown in the following sample:
+
+```yaml
+apiVersion: dapr.io/v1alpha1
+kind: Configuration
+metadata:
+  name: pipeline
+spec:
+  httpPipeline:
+    handlers:
+    - name: middleware.http.oauth2
+```
+
+## Apply the configuration
+
+To apply the above configuration to your Dapr sidecar, add a ```dapr.io/config``` annotation to your pod spec:
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+...
+spec:
+  ...
+  template:
+    metadata:
+      ...
+      annotations:
+        dapr.io/enabled: "true"
+        ...
+        dapr.io/config: "pipeline"
+...
+```
+## Accessing the access token
+
+Once everything is in place, whenever a client tries to invoke an API method through Dapr sidecar (such as calling the *v1.0/invoke/* endpoint), it will be reidrected to the authorization's consent page if an access token is not found. Otherwise, the access token is written to the **authHeaderName** header and made available to the app code. 
+
+