Merge pull request #55 from microtherion/Imgur

Add Imgur support

Sources/Imperial/Services/Imgur/Imgur.swift

@@ -0,0 +1,24 @@
+import Vapor
+
+public class Imgur: FederatedService {
+    public var tokens: FederatedServiceTokens
+    public var router: FederatedServiceRouter
+
+    @discardableResult
+    public required init(
+        router: Router,
+        authenticate: String,
+        authenticateCallback: ((Request)throws -> (Future<Void>))?,
+        callback: String,
+        scope: [String] = [],
+        completion: @escaping (Request, String)throws -> (Future<ResponseEncodable>)
+    ) throws {
+        self.router = try ImgurRouter(callback: callback, completion: completion)
+        self.tokens = self.router.tokens
+
+        self.router.scope = scope
+        try self.router.configureRoutes(withAuthURL: authenticate, authenticateCallback: authenticateCallback, on: router)
+
+        OAuthService.register(.imgur)
+    }
+}

Sources/Imperial/Services/Imgur/ImgurAuth.swift

@@ -0,0 +1,16 @@
+import Vapor
+
+public class ImgurAuth: FederatedServiceTokens {
+    public static var idEnvKey: String = "IMGUR_CLIENT_ID"
+    public static var secretEnvKey: String = "IMGUR_CLIENT_SECRET"
+    public var clientID: String
+    public var clientSecret: String
+
+    public required init() throws {
+        let idError = ImperialError.missingEnvVar(ImgurAuth.idEnvKey)
+        let secretError = ImperialError.missingEnvVar(ImgurAuth.secretEnvKey)
+
+        self.clientID = try Environment.get(ImgurAuth.idEnvKey).value(or: idError)
+        self.clientSecret = try Environment.get(ImgurAuth.secretEnvKey).value(or: secretError)
+    }
+}

Sources/Imperial/Services/Imgur/ImgurCallbackBody.swift

@@ -0,0 +1,17 @@
+import Vapor
+
+struct ImgurCallbackBody: Content {
+    let code: String
+    let clientId: String
+    let clientSecret: String
+    let grantType: String = "authorization_code"
+
+    static var defaultContentType: MediaType = .urlEncodedForm
+
+    enum CodingKeys: String, CodingKey {
+        case code = "code"
+        case clientId = "client_id"
+        case clientSecret = "client_secret"
+        case grantType = "grant_type"
+    }
+}

Sources/Imperial/Services/Imgur/ImgurRouter.swift

@@ -0,0 +1,65 @@
+import Vapor
+import Foundation
+
+public class ImgurRouter: FederatedServiceRouter {
+    public let tokens: FederatedServiceTokens
+    public let callbackCompletion: (Request, String)throws -> (Future<ResponseEncodable>)
+    public var scope: [String] = []
+    public var callbackURL: String
+    public let accessTokenURL: String = "https://api.imgur.com/oauth2/token"
+
+    public required init(callback: String, completion: @escaping (Request, String)throws -> (Future<ResponseEncodable>)) throws {
+        self.tokens = try ImgurAuth()
+        self.callbackURL = callback
+        self.callbackCompletion = completion
+    }
+
+    public func authURL(_ request: Request) throws -> String {
+        return "https://api.imgur.com/oauth2/authorize?" +
+            "client_id=\(self.tokens.clientID)&" +
+            "response_type=code"
+    }
+
+    public func fetchToken(from request: Request)throws -> Future<String> {
+        let code: String
+        if let queryCode: String = try request.query.get(at: "code") {
+            code = queryCode
+        } else if let error: String = try request.query.get(at: "error") {
+            throw Abort(.badRequest, reason: error)
+        } else {
+            throw Abort(.badRequest, reason: "Missing 'code' key in URL query")
+        }
+
+        let body = ImgurCallbackBody(code: code, clientId: self.tokens.clientID, clientSecret: self.tokens.clientSecret)
+        return try body.encode(using: request).flatMap(to: Response.self) { request in
+            guard let url = URL(string: self.accessTokenURL) else {
+                throw Abort(.internalServerError, reason: "Unable to convert String '\(self.accessTokenURL)' to URL")
+            }
+            request.http.method = .POST
+            request.http.url = url
+            return try request.make(Client.self).send(request)
+        }.flatMap(to: String.self) { response in
+            let session = try request.session()
+
+            return response.content.get(String.self, at: ["refresh_token"])
+            .flatMap { refresh in
+                session.setRefreshToken(refresh)
+
+                return response.content.get(String.self, at: ["access_token"])
+            }
+        }
+    }
+
+    public func callback(_ request: Request)throws -> Future<Response> {
+        return try self.fetchToken(from: request).flatMap(to: ResponseEncodable.self) { accessToken in
+            let session = try request.session()
+
+            session.setAccessToken(accessToken)
+            try session.set("access_token_service", to: OAuthService.imgur)
+
+            return try self.callbackCompletion(request, accessToken)
+        }.flatMap(to: Response.self) { response in
+            return try response.encode(for: request)
+        }
+    }
+}

Sources/Imperial/Services/Imgur/Service+Imgur.swift

@@ -0,0 +1,6 @@
+extension OAuthService {
+    public static let imgur = OAuthService.init(
+        name: "imgur",
+        endpoints: [:]
+    )
+}

docs/Imgur/README.md

@@ -0,0 +1,105 @@
+# Federated Login with Imgur
+
+Start by going to the [Imgur App registration page](https://api.imgur.com/oauth2/addclient). Select the authorization type "OAuth 2 authorization with a callback URL". Fill in the rest of the app information, particularly the Authorization callback URL:
+
+![Redirect URI](callback-url.png)
+
+Note that, as opposed to most other services, Imgur allows only one callback URL per app — if you would like multiple URLs (e.g. for test and production), you'll have to register multiple apps. Now that we have an OAuth application registered with Imgur, we can add Imperial to our project (We will not be going over how to create the project, as I will assume that you have already done that).
+
+Add the following line of code to your `dependencies` array in your package manifest file:
+
+```swift
+.package(url: "https://github.com/vapor-community/Imperial.git", from: "0.5.3")
+```
+
+**Note:** There might be a later version of the package available, in which case you will want to use that version.
+
+You will also need to add the package as a dependency for the targets you will be using it in:
+
+```swift
+.target(name: "App", dependencies: ["Vapor", "Imperial"],
+               exclude: [
+                   "Config",
+                   "Database",
+                   "Public",
+                   "Resources"
+               ]),
+```
+
+Then run `vapor update` or `swift package update`. Make sure you regenerate your Xcode project afterwards if you are using Xcode.
+
+Now that Imperial is installed, we need to add `SessionMiddleware` to our middleware configuration:
+
+```swift
+public func configure(
+    _ config: inout Config,
+    _ env: inout Environment,
+    _ services: inout Services
+) throws {
+    //...
+
+    // Register middleware
+    var middlewares = MiddlewareConfig() // Create _empty_ middleware config
+	// Other Middleware...
+    middlewares.use(SessionsMiddleware.self)
+    services.register(middlewares)
+
+	//...
+}
+
+```
+
+Now, when you run your app and you are using `FluentSQLite`, you will probably get the following error:
+
+```
+⚠️ [ServiceError.ambiguity: Please choose which KeyedCache you prefer, multiple are available: MemoryKeyedCache, FluentCache<SQLiteDatabase>.] [Suggested fixes: `config.prefer(MemoryKeyedCache.self, for: KeyedCache.self)`. `config.prefer(FluentCache<SQLiteDatabase>.self, for: KeyedCache.self)`.]
+```
+
+Just pick one of the listed suggestions and place it at the top of your `configure` function. If you want your data to persist across server reboots, use `config.prefer(FluentCache<SQLiteDatabase>.self, for: KeyedCache.self)`
+
+Imperial uses environment variables to access the client ID and secret to authenticate with Imgur. To allow Imperial to access these tokens, you will create these variables, called `IMGUR_CLIENT_ID` and `IMGUR_CLIENT_SECRET`, with the App key and App secret assigned to them. Imperial can then access these vars and use their values to authenticate with Imgur.
+
+Now, all we need to do is register the Imgur service in your main router method, like this:
+
+```swift
+try router.oAuth(from: Imgur.self, authenticate: "imgur-login", callback: "https://example.com/imgur-auth-complete") { (request, token) in
+    print(token)
+    return Future(request.redirect(to: "/"))
+}
+```
+
+If you just want to redirect, without doing anything else in the callback, you can use the helper `Route.oAuth` method that takes in a redirect string:
+
+```swift
+try router.oAuth(from: Imgur.self, authenticate: "imgur-login", callback: "https://example.com/imgur-auth-complete", redirect: "/")
+```
+
+The `authenticate` argument is the path you will go to when you want to authenticate the user. The `callback` argument has to be the same path that you entered when you registered your application on Imgur.
+
+![The callback path for Imgur OAuth](callback-url.png)
+
+The completion handler is fired when the callback route is called by the OAuth provider. The access token is passed in and a response is returned.
+
+If you ever want to get the `access_token` in a route, you can use a helper method for the `Request` type that comes with Imperial:
+
+```swift
+let token = try request.accessToken()
+```
+
+Now that you are authenticating the user, you will want to protect certain routes to make sure the user is authenticated. You can do this by adding the `ImperialMiddleware` to a router group (or maybe your middleware config):
+
+```swift
+let protected = router.grouped(ImperialMiddleware())
+```
+
+Then, add your protected routes to the `protected` group:
+
+```swift
+protected.get("me", handler: me)
+```
+
+The `ImperialMiddleware` by default passes the errors it finds onto `ErrorMiddleware` where they are caught, but you can initialize it with a redirect path to go to if the user is not authenticated:
+
+```swift
+let protected = router.grouped(ImperialMiddleware(redirect: "/"))
+```