docs: Wrote basic developer guide

book.json

@@ -0,0 +1,5 @@
+{
+    "root": "./docs",
+    "author": "Aeneas Rekkas",
+    "gitbook": ">=3.2.0"
+}

cmd/serve.go

@@ -23,16 +23,8 @@ import (
 // serveCmd represents the serve command
 var serveCmd = &cobra.Command{
 	Use:   "serve",
-	Short: "A brief description of your command",
-	Long: `A longer description that spans multiple lines and likely contains examples
-and usage of using your command. For example:
-
-Cobra is a CLI library for Go that empowers applications.
-This application is a tool to generate the needed files
-to quickly create a Cobra application.`,
 	Run: func(cmd *cobra.Command, args []string) {
-		// TODO: Work your own magic here
-		fmt.Println("serve called")
+		fmt.Println(cmd.UsageString())
 	},
 }
 

docs/README.md

@@ -0,0 +1,13 @@
+# ORY Oathkeeper
+
+## Introduction
+
+Welcome to the ORY Oathkeeper documentation!
+
+ORY Oathkeeper is a reverse proxy which evaluates incoming HTTP requests based on a set of rules. This capability
+is referred to as an Identity and Access Proxy (IAP) in the context of [BeyondCorp and ZeroTrust](https://www.beyondcorp.com).
+
+In principal, ORY Oathkeeper inspects the `Authorization` header and the full request url (e.g. `https://mydomain.com/api/foo`)
+of incoming HTTP requests, applies a given rule, and either grants access to the requested url or denies access. The
+decision of whether to allow or deny the access request is made using ORY Hydra. Please keep in mind that ORY Oathkeeper
+is a supplement to ORY Hydra. It is thus imperative to be familiar with the core concepts of ORY Hydra.

docs/SUMMARY.md

@@ -0,0 +1,11 @@
+- [Concepts](concepts.md#concepts)
+  - [Terminology](concepts.md#terminology)
+  - [Rules](concepts.md#rules)
+    - [Rules REST API](concepts.md#rules-rest-api)
+    - [Rules CLI API](#rules-cli-api)
+- [Deployment](deployment.md#deployment)
+  - [Gateway](deployment.md#gateway)
+  - [Sidecar](deployment.md#sidecar)
+- [Security](security.md#security)
+  - [Stateless Authorization](security.md#stateless-authorization)
+  - [The ID Token](security.md#the-id-token)

docs/concepts.md

@@ -0,0 +1,50 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**  *generated with [DocToc](https://github.com/thlorenz/doctoc)*
+
+- [Concepts](#concepts)
+  - [Terminology](#terminology)
+  - [Rules](#rules)
+    - [Rules REST API](#rules-rest-api)
+    - [Rules CLI API](#rules-cli-api)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Concepts
+
+This section covers core concepts of ORY Oathekeeper.
+
+## Terminology
+
+* Access credentials: The credentials used to access an endpoint. This is typically an OAuth 2.0 access token supplied
+    by ORY Hydra.
+* Backend URL: The URL (backend) where requests will be forwarded to, if access is granted. Typically an API Gateway
+    such as Mashape Kong.
+* Scopes: An OAuth 2.0 Scope.
+* Access Control Policies: These are JSON documents similar to AWS and Google Cloud Policies. Read more about them [here](https://ory.gitbooks.io/hydra/content/security.html#how-does-access-control-work-with-hydra).
+
+## Rules
+
+ORY Oathkeeper has a configurable set of rules. Rules are applied to all incoming requests and based on the rule definition,
+an action is taken. There are four types of rules:
+
+1. **Passthrough**: Forwards the original request to the backend url without any modification to its headers.
+2. **Anonymous**: Tries to extract user information from the given access credentials. If that fails, or no access
+    credentials have been provided, the request is forwarded and the user is marked as "anonymous".
+3. **Basic Authorization**: Requires valid access credentials and optionally checks for a set of OAuth 2.0 Scopes. If
+    the supplied access credentials are invalid (expired, malformed, revoked) or do not fulfill the requested scopes,
+    access is denied.
+4. **Policy Authorization**: Requires valid access credentials as defined in 3. and additionally validates if the user
+    is authorized to make the request, based on access control policies.
+
+The exact payloads are explained in detail in the REST API (see next section).
+
+### Rules REST API
+
+For more information on available fields and exemplary payloads of rules, as well as rule management using HTTP
+please refer to the [REST API docs](https://oathkeeper.docs.apiary.io/#)
+
+### Rules CLI API
+
+Management of rules is not only possible through the REST API, but additionally using the ORY Oathkeeper CLI.
+For help on how to manage the CLI, type `oathkeeper help rules`.

docs/deployment.md

@@ -0,0 +1,46 @@
+<!-- START doctoc generated TOC please keep comment here to allow auto update -->
+<!-- DON'T EDIT THIS SECTION, INSTEAD RE-RUN doctoc TO UPDATE -->
+**Table of Contents**
+
+- [Deployment](#deployment)
+  - [Gateway](#gateway)
+  - [Sidecar](#sidecar)
+
+<!-- END doctoc generated TOC please keep comment here to allow auto update -->
+
+# Deployment
+
+ORY Oathkeeper is developed as a native cloud application. As such, it is completely stateless, does not require
+configuration files and does not persist anything to disk. It is possible to restart ORY Oathkeeper without any side-effects
+as ORY Oathkeeper supports graceful HTTP shutdown.
+
+ORY Oathkeeper works natively with Load Balancers and auto-scaling groups. It is configured using environment variables
+and relies on a PostgreSQL / MySQL database instance. To answer access requests quickly, rules are cached in-memory
+and refreshed within a given interval (e.g. 30 seconds).
+
+ORY Oathkeeper has a tiny footprint as it is compiled to native bytecode. The docker image is a mere 5 MB, the memory
+footprint similarly low and the CPU usage is, on average, close to zero.
+
+Thus, two possible deployment layouts are possible for ORY Oathkeeper, which are covered in the next two sections.
+
+## Gateway
+
+In the gateway deployment scenario, ORY Oathkeeper is the single point of entry for all API endpoints. Oathkeeper might
+sit behind a load balancer, but is generally deployed in front of the API router. Any incoming requests first
+pass ORY Oathkeeper, then the API router, and finally reach the API endpoint service.
+
+![Gateway Oathkeeper Deployment Layout](images/gateway_deployment.svg)
+
+The advantage of this deployment layout is that there is only one deployment of ORY Oathkeeper that needs to be maintained.
+The disadvantage is that it is not possible to talk to API endpoints directly without going through the full
+reverse proxy chain.
+
+## Sidecar
+
+In the sidecar deployment scenario, ORY Oathkeeper is deployed alongside each API endpoint service, probably even
+within the same logical unit (e.g. Docker Container or VM) as the service itself.
+
+![Gateway Oathkeeper Deployment Layout](images/sidecar_layout.svg)
+
+The advantage of this deployment layout is that requests to the API endpoints are possible without passing through
+the API router. The disadvantage is that multiple instances of ORY Oathkeeper have to be maintained.

docs/diagrams/api_router_layout.mermaid

@@ -0,0 +1,8 @@
+graph LR
+
+    UA[User Agent] --- FW[ORY Oathkeeper]
+
+    FW --- APIR[API Router]
+    APIR --- API1[API Endpoint 1]
+    APIR --- API2[API Endpoint 2]
+    APIR --- API3[API Endpoint 3]

docs/diagrams/id_token.mermaid

@@ -0,0 +1,8 @@
+sequenceDiagram
+    participant UA as User Agent
+    participant FW as ORY Oathkeeper
+    participant API as API Endpoint
+
+    UA->>FW: Authorization: bearer Opaque.Token
+    FW->>API: Authorization: bearer JWT.ID.Token
+    API->>API: Decodes & validates JWT.ID.Token using Oathkeeper's public key

docs/diagrams/invalid_access_request.mermaid

@@ -0,0 +1,15 @@
+sequenceDiagram
+    participant UA as User Agent
+    participant FW as ORY Oathkeeper
+    participant OA2 as ORY Hydra
+    participant API as API Endpoint
+
+    UA->>FW: HTTP Request with opaque access token
+    activate FW
+    FW->>OA2: Ask for access request validation
+    activate OA2
+    OA2->>OA2: Process access request
+    OA2->>FW: Forbid access request
+    deactivate OA2
+    FW->>UA: HTTP 403 Forbidden
+    deactivate FW

docs/diagrams/sidecar_layout.mermaid

@@ -0,0 +1,18 @@
+graph LR
+
+    UA[User Agent] --- APIR[API Router]
+
+    APIR ---  FW1[ORY Oathkeeper]
+    subgraph Service 1
+    FW1 --- API1[API Endpoint 1]
+    end
+
+    APIR ---  FW2[ORY Oathkeeper]
+    subgraph Service 2
+    FW2 --- API2[API Endpoint 2]
+    end
+
+    APIR ---  FW3[ORY Oathkeeper]
+    subgraph Service 3
+    FW3 --- API3[API Endpoint 3]
+    end

docs/diagrams/valid_access_request.mermaid

@@ -0,0 +1,21 @@
+sequenceDiagram
+    participant UA as User Agent
+    participant FW as ORY Oathkeeper
+    participant OA2 as ORY Hydra
+    participant API as API Endpoint
+
+    UA->>FW: HTTP Request with opaque access token
+    activate FW
+    FW->>OA2: Ask for access request validation
+    activate OA2
+    OA2->>OA2: Process access request
+    OA2->>FW: Approve request and return identity information
+   deactivate OA2
+    FW->>FW: Generate JWT ID Token
+    FW->>API: Forward request with ID Token
+    activate API
+    API->>API: Process request with user info from ID token
+    API->>FW: Return response
+    deactivate API
+    FW->>UA: Forward response
+    deactivate FW