From 54fb79669210144fdfda291cb58232a87e348f20 Mon Sep 17 00:00:00 2001 From: Matthias Neeracher Date: Wed, 11 Mar 2020 02:19:45 +0100 Subject: [PATCH] Add Imgur support --- Sources/Imperial/Services/Imgur/Imgur.swift | 24 ++++ .../Imperial/Services/Imgur/ImgurAuth.swift | 16 +++ .../Services/Imgur/ImgurCallbackBody.swift | 17 +++ .../Imperial/Services/Imgur/ImgurRouter.swift | 65 +++++++++++ .../Services/Imgur/Service+Imgur.swift | 6 + docs/Imgur/README.md | 105 ++++++++++++++++++ docs/Imgur/callback-url.png | Bin 0 -> 18370 bytes 7 files changed, 233 insertions(+) create mode 100644 Sources/Imperial/Services/Imgur/Imgur.swift create mode 100644 Sources/Imperial/Services/Imgur/ImgurAuth.swift create mode 100644 Sources/Imperial/Services/Imgur/ImgurCallbackBody.swift create mode 100644 Sources/Imperial/Services/Imgur/ImgurRouter.swift create mode 100644 Sources/Imperial/Services/Imgur/Service+Imgur.swift create mode 100644 docs/Imgur/README.md create mode 100644 docs/Imgur/callback-url.png diff --git a/Sources/Imperial/Services/Imgur/Imgur.swift b/Sources/Imperial/Services/Imgur/Imgur.swift new file mode 100644 index 0000000..17e360e --- /dev/null +++ b/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))?, + callback: String, + scope: [String] = [], + completion: @escaping (Request, String)throws -> (Future) + ) 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) + } +} diff --git a/Sources/Imperial/Services/Imgur/ImgurAuth.swift b/Sources/Imperial/Services/Imgur/ImgurAuth.swift new file mode 100644 index 0000000..412a5ee --- /dev/null +++ b/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) + } +} diff --git a/Sources/Imperial/Services/Imgur/ImgurCallbackBody.swift b/Sources/Imperial/Services/Imgur/ImgurCallbackBody.swift new file mode 100644 index 0000000..785248b --- /dev/null +++ b/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" + } +} diff --git a/Sources/Imperial/Services/Imgur/ImgurRouter.swift b/Sources/Imperial/Services/Imgur/ImgurRouter.swift new file mode 100644 index 0000000..52e3756 --- /dev/null +++ b/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) + 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)) 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 { + 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 { + 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) + } + } +} diff --git a/Sources/Imperial/Services/Imgur/Service+Imgur.swift b/Sources/Imperial/Services/Imgur/Service+Imgur.swift new file mode 100644 index 0000000..ff1634a --- /dev/null +++ b/Sources/Imperial/Services/Imgur/Service+Imgur.swift @@ -0,0 +1,6 @@ +extension OAuthService { + public static let imgur = OAuthService.init( + name: "imgur", + endpoints: [:] + ) +} diff --git a/docs/Imgur/README.md b/docs/Imgur/README.md new file mode 100644 index 0000000..245a588 --- /dev/null +++ b/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.] [Suggested fixes: `config.prefer(MemoryKeyedCache.self, for: KeyedCache.self)`. `config.prefer(FluentCache.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.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: "/")) +``` diff --git a/docs/Imgur/callback-url.png b/docs/Imgur/callback-url.png new file mode 100644 index 0000000000000000000000000000000000000000..4182361c0252c43289942f6535015a4be63b91b6 GIT binary patch literal 18370 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 literal 0 HcmV?d00001