Deploying to gh-pages from @ 196ebad 🚀

docs/1.0/data/documentation/hummingbird/authenticators.json

@@ -0,0 +1 @@
+{"hierarchy":{"paths":[["doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth"]]},"schemaVersion":{"minor":3,"patch":0,"major":0},"metadata":{"title":"Authenticators","modules":[{"name":"HummingbirdAuth"}],"role":"article","roleHeading":"Article"},"primaryContentSections":[{"kind":"content","content":[{"anchor":"Overview","text":"Overview","type":"heading","level":2},{"inlineContent":[{"text":"Authenticators are middleware that are used to check if a request is authenticated and then augment the request with the authentication data. Authenticators should conform to protocol ","type":"text"},{"code":"HBAuthenticator","type":"codeVoice"},{"text":". This requires you implement the function ","type":"text"},{"code":"authenticate(request: HBRequest) -> EventLoopFuture<Value?>","type":"codeVoice"},{"text":" where ","type":"text"},{"code":"Value","type":"codeVoice"},{"type":"text","text":" is the authentication data and conforms to the protocol "},{"type":"codeVoice","code":"HBAuthenticatable"},{"type":"text","text":"."}],"type":"paragraph"},{"anchor":"Usage","text":"Usage","type":"heading","level":2},{"inlineContent":[{"type":"text","text":"A simple username, password authenticator could be implemented as follows. If the authenticator is successful it returns a "},{"type":"codeVoice","code":"User"},{"type":"text","text":" struct, otherwise it returns "},{"type":"codeVoice","code":"nil"},{"type":"text","text":"."}],"type":"paragraph"},{"code":["struct BasicAuthenticator: HBAuthenticator {","    func authenticate(request: HBRequest) -> EventLoopFuture<User?> {","        \/\/ Basic authentication info in the \"Authorization\" header, is accessible","        \/\/ via request.auth.basic","        guard let basic = request.authBasic else { return request.success(nil) }","","        \/\/ check if user exists in the database and then verify the entered password","        \/\/ against the one stored in the database. If it is correct then login in user","        return database.getUserWithUsername(basic.username, on: request.eventLoop).flatMap { user in","            \/\/ did we find a user","            guard let user = user else { return request.success(nil) }","            \/\/ verify password against password hash stored in database. If valid","            \/\/ return the user. HummingbirdAuth provides an implementation of Bcrypt. ","            return Bcrypt.verify(basic.password, hash: user.passwordHash, for: request).map { success in","                guard success else { return nil }","                return user","            }","        }","    }","}"],"type":"codeListing","syntax":"swift"},{"inlineContent":[{"text":"An authenticator is middleware so can be added to your application like any other middleware","type":"text"}],"type":"paragraph"},{"code":["app.middleware.add(BasicAuthenticator())"],"type":"codeListing","syntax":"swift"},{"inlineContent":[{"type":"text","text":"Then in your request handler you can access your authentication data with "},{"type":"codeVoice","code":"request.authGet"},{"type":"text","text":"."}],"type":"paragraph"},{"code":["\/\/\/ Get current logged in user","func current(_ request: HBRequest) throws -> User {","    \/\/ get authentication data for user. If it doesnt exist then throw unauthorized error","    guard let user = request.authGet(User.self) else { throw HBHTTPError(.unauthorized) }","    return user","}"],"type":"codeListing","syntax":"swift"},{"inlineContent":[{"type":"text","text":"You can require that that authentication was successful and authentication data is available by either adding the middleware "},{"identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/IsAuthenticatedMiddleware","isActive":true,"type":"reference"},{"type":"text","text":" after your authentication middleware"}],"type":"paragraph"},{"code":["app.middleware.add(BasicAuthenticator())","app.middleware.add(IsAuthenticatedMiddleware<User>())"],"type":"codeListing","syntax":"swift"},{"inlineContent":[{"type":"text","text":"Or you can use "},{"type":"codeVoice","code":"request.requireAuth"},{"type":"text","text":" to access the authentication data. In both of these cases if data is not available a unauthorised error is thrown and a 404 response is returned by the server."}],"type":"paragraph"}]}],"sections":[],"identifier":{"interfaceLanguage":"swift","url":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/Authenticators"},"seeAlsoSections":[{"identifiers":["doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticator","doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAsyncAuthenticator","doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticatable","doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/IsAuthenticatedMiddleware"],"title":"Related Documentation"},{"identifiers":["doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/Sessions","doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/OneTimePasswords"],"title":"Articles","generated":true}],"abstract":[{"type":"text","text":"Request authentication middleware"}],"kind":"article","references":{"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth":{"kind":"symbol","title":"HummingbirdAuth","abstract":[{"text":"Authentication framework and extensions for Hummingbird.","type":"text"}],"url":"\/documentation\/hummingbirdauth","type":"topic","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth","role":"collection"},"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth/HBAsyncAuthenticator":{"abstract":[{"type":"text","text":"Async version of Middleware to check if a request is authenticated and then augment the request with"},{"type":"text","text":" "},{"type":"text","text":"authentication data."}],"type":"topic","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAsyncAuthenticator","url":"\/documentation\/hummingbirdauth\/hbasyncauthenticator","kind":"symbol","navigatorTitle":[{"kind":"identifier","text":"HBAsyncAuthenticator"}],"role":"symbol","fragments":[{"kind":"keyword","text":"protocol"},{"kind":"text","text":" "},{"kind":"identifier","text":"HBAsyncAuthenticator"}],"title":"HBAsyncAuthenticator"},"doc://com.opticalaberration.hummingbird/documentation/Hummingbird/Sessions":{"abstract":[{"type":"text","text":"Session based authentication"}],"type":"topic","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/Sessions","url":"\/documentation\/hummingbird\/sessions","kind":"article","role":"article","title":"Sessions"},"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth/HBAuthenticatable":{"identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticatable","url":"\/documentation\/hummingbirdauth\/hbauthenticatable","title":"HBAuthenticatable","fragments":[{"kind":"keyword","text":"protocol"},{"kind":"text","text":" "},{"kind":"identifier","text":"HBAuthenticatable"}],"abstract":[{"text":"Protocol for objects that can be returned by an ","type":"text"},{"code":"HBAuthenticator","type":"codeVoice"},{"text":".","type":"text"}],"navigatorTitle":[{"kind":"identifier","text":"HBAuthenticatable"}],"kind":"symbol","role":"symbol","type":"topic"},"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth/IsAuthenticatedMiddleware":{"abstract":[{"type":"text","text":"Middleware returning 404 for unauthenticated requests"}],"type":"topic","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/IsAuthenticatedMiddleware","url":"\/documentation\/hummingbirdauth\/isauthenticatedmiddleware","kind":"symbol","navigatorTitle":[{"kind":"identifier","text":"IsAuthenticatedMiddleware"}],"role":"symbol","fragments":[{"kind":"keyword","text":"struct"},{"kind":"text","text":" "},{"kind":"identifier","text":"IsAuthenticatedMiddleware"}],"title":"IsAuthenticatedMiddleware"},"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth/HBAuthenticator":{"abstract":[{"type":"text","text":"Middleware to check if a request is authenticated and then augment the request with"},{"type":"text","text":" "},{"type":"text","text":"authentication data."}],"type":"topic","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticator","url":"\/documentation\/hummingbirdauth\/hbauthenticator","kind":"symbol","navigatorTitle":[{"kind":"identifier","text":"HBAuthenticator"}],"role":"symbol","fragments":[{"kind":"keyword","text":"protocol"},{"kind":"text","text":" "},{"kind":"identifier","text":"HBAuthenticator"}],"title":"HBAuthenticator"},"doc://com.opticalaberration.hummingbird/documentation/Hummingbird/OneTimePasswords":{"abstract":[{"type":"text","text":"A one time password (OTP) valid for only one login session."}],"type":"topic","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/OneTimePasswords","url":"\/documentation\/hummingbird\/onetimepasswords","kind":"article","role":"article","title":"One Time Passwords"}}}