From d50c7d7433cfee399b79e90097509813666d442e Mon Sep 17 00:00:00 2001
From: Tanner Nelson <me@tanner.xyz>
Date: Thu, 22 Sep 2016 01:16:08 -0400
Subject: [PATCH] auth docs

---
 auth/middleware.md |  6 ++++
 auth/protect.md    |  6 ++++
 auth/user.md       | 69 ++++++++++++++++++++++++++++++++++++++++++++++
 couscous.yml       | 12 ++++++++
 4 files changed, 93 insertions(+)
 create mode 100644 auth/middleware.md
 create mode 100644 auth/protect.md
 create mode 100644 auth/user.md

diff --git a/auth/middleware.md b/auth/middleware.md
new file mode 100644
index 00000000..cdded46c
--- /dev/null
+++ b/auth/middleware.md
@@ -0,0 +1,6 @@
+---
+currentMenu: auth-middleare
+---
+
+# Auth Middleware
+
diff --git a/auth/protect.md b/auth/protect.md
new file mode 100644
index 00000000..800bd56d
--- /dev/null
+++ b/auth/protect.md
@@ -0,0 +1,6 @@
+---
+currentMenu: auth-protect
+---
+
+# Protect Middleware
+
diff --git a/auth/user.md b/auth/user.md
new file mode 100644
index 00000000..568f593d
--- /dev/null
+++ b/auth/user.md
@@ -0,0 +1,69 @@
+---
+currentMenu: auth-user
+---
+
+# Auth
+
+Authorization and authentication is focused around a the `Auth.User` protocol. Authorization is analagous with asking: "Who is this?", while authentication is analagous with asking: "What can they do?". Vapor includes an extensible authorization system that you can use as a base for more sophisticated authentication.
+
+## User Protocol
+
+Any type can conform to the `Auth.User` protocol, but they are commonly added onto Fluent `Model`s.
+
+```swift
+import Vapor
+import Auth
+
+final class User: Model, Auth.User {
+    var id: Node?
+    var name: String
+
+	...
+
+    static func authenticate(credentials: Credentials) throws -> Auth.User {
+
+    }
+
+    static func register(credentials: Credentials) throws -> Auth.User {
+
+    }
+}
+```
+
+Here is an example `User` class with the `Auth.User` protocol requirements stubbed. Note that the name of our class and the protocol are the same. This is why we use the `Auth.` prefix to differentiate the protocol from the `Auth` module from our `User` class.
+
+### Authenticate
+
+#### Credentials
+
+The credentials protocol is an empty protocol that any type can conform to. This gives great flexibility to your authorization model, but also requires that you properly handle the case of unsupported credential types.
+
+#### AccessToken
+
+One of the simplest credential types included is `AccessToken`. It carries a `String` based token that will be used to authenticate the user.
+
+Let's look at how we might support the access token type.
+
+```swift
+static func authenticate(credentials: Credentials) throws -> Auth.User {
+	if let accessToken = credentials as? AccessToken {
+		guard let user = try User.query().filter("access_token", accessToken.string).first() else {
+			throw Abort.custom(status: .forbidden, message: "Invalid access token.")	
+		}
+
+		return user
+	} else {
+		throw Abort.custom(status: .forbidden, message: "Unsupported credentials.")
+	}
+}
+```
+
+The first step is to cast the credentials to the type we want to support--in this case, `AccessToken`. If we do not have an access token, we will inform the client that the credentials are invalid.
+
+Once we have the access token, we will use it to query the `User` model for an entry with a matching access token. This is assuming the `users` table or collection has the access tokens stored on it. You may opt to store them somewhere else.
+
+Once we have found the user associated with the supplied access token, we simply return it.
+
+### Register
+
+Similar to the authenticate method, the register method takes credentials. But instead of fetching the user from the data store, it provides a convenient way to create the user. You are not required to register your users through this method.
diff --git a/couscous.yml b/couscous.yml
index 2d6e1cd9..4c3ba52f 100644
--- a/couscous.yml
+++ b/couscous.yml
@@ -92,6 +92,18 @@ menu:
                 fluent-relation:
                     text: Relation
                     relativeUrl: fluent/relation.html
+        auth:
+            name: Auth
+            items:
+                auth-user:
+                    text: User
+                    relativeUrl: auth/user.html
+                auth-middleware:
+                    text: Middleware
+                    relativeUrl: auth/middleware.html
+                auth-protect:
+                    text: Protect
+                    relativeUrl: auth/protect.html
         http:
             name: HTTP
             items: