Deploying to gh-pages from @ 26da33c 🚀

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

@@ -0,0 +1 @@
+{"abstract":[{"text":"Request authentication middleware","type":"text"}],"primaryContentSections":[{"kind":"content","content":[{"level":2,"anchor":"Overview","type":"heading","text":"Overview"},{"inlineContent":[{"type":"text","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":"codeVoice","code":"HBAuthenticator"},{"type":"text","text":". This requires you implement the function "},{"type":"codeVoice","code":"authenticate(request: HBRequest) -> EventLoopFuture<Value?>"},{"type":"text","text":" where "},{"type":"codeVoice","code":"Value"},{"type":"text","text":" is the authentication data and conforms to the protocol "},{"type":"codeVoice","code":"HBAuthenticatable"},{"type":"text","text":"."}],"type":"paragraph"},{"anchor":"Usage","level":2,"text":"Usage","type":"heading"},{"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"},{"syntax":"swift","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"},{"inlineContent":[{"text":"An authenticator is middleware so can be added to your application like any other middleware","type":"text"}],"type":"paragraph"},{"syntax":"swift","code":["app.middleware.add(BasicAuthenticator())"],"type":"codeListing"},{"inlineContent":[{"text":"Then in your request handler you can access your authentication data with ","type":"text"},{"type":"codeVoice","code":"request.authGet"},{"text":".","type":"text"}],"type":"paragraph"},{"syntax":"swift","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"},{"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"},{"syntax":"swift","code":["app.middleware.add(BasicAuthenticator())","app.middleware.add(IsAuthenticatedMiddleware<User>())"],"type":"codeListing"},{"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"}]}],"hierarchy":{"paths":[["doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth"]]},"metadata":{"modules":[{"name":"HummingbirdAuth"}],"roleHeading":"Article","role":"article","title":"Authenticators"},"kind":"article","schemaVersion":{"minor":3,"patch":0,"major":0},"seeAlsoSections":[{"title":"Related Documentation","identifiers":["doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticator","doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticatable","doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/IsAuthenticatedMiddleware"]},{"title":"Articles","generated":true,"identifiers":["doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/Sessions","doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/OneTimePasswords"]}],"sections":[],"identifier":{"url":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/Authenticators","interfaceLanguage":"swift"},"references":{"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth":{"kind":"symbol","url":"\/documentation\/hummingbirdauth","abstract":[{"text":"Authentication framework and extensions for Hummingbird.","type":"text"}],"role":"collection","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth","type":"topic","title":"HummingbirdAuth"},"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth/IsAuthenticatedMiddleware":{"kind":"symbol","navigatorTitle":[{"kind":"identifier","text":"IsAuthenticatedMiddleware"}],"url":"\/documentation\/hummingbirdauth\/isauthenticatedmiddleware","role":"symbol","type":"topic","abstract":[{"type":"text","text":"Middleware returning 404 for unauthenticated requests"}],"fragments":[{"text":"struct","kind":"keyword"},{"text":" ","kind":"text"},{"kind":"identifier","text":"IsAuthenticatedMiddleware"}],"identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/IsAuthenticatedMiddleware","title":"IsAuthenticatedMiddleware"},"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth/HBAuthenticator":{"identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticator","url":"\/documentation\/hummingbirdauth\/hbauthenticator","abstract":[{"type":"text","text":"Middleware to check if a request is authenticated and then augment the request with"},{"text":" ","type":"text"},{"text":"authentication data.","type":"text"}],"role":"symbol","kind":"symbol","navigatorTitle":[{"text":"HBAuthenticator","kind":"identifier"}],"title":"HBAuthenticator","fragments":[{"text":"protocol","kind":"keyword"},{"text":" ","kind":"text"},{"text":"HBAuthenticator","kind":"identifier"}],"type":"topic"},"doc://com.opticalaberration.hummingbird/documentation/Hummingbird/OneTimePasswords":{"url":"\/documentation\/hummingbird\/onetimepasswords","type":"topic","role":"article","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/OneTimePasswords","kind":"article","title":"One Time Passwords","abstract":[{"text":"A one time password (OTP) valid for only one login session.","type":"text"}]},"doc://com.opticalaberration.hummingbird/documentation/Hummingbird/Sessions":{"title":"Sessions","url":"\/documentation\/hummingbird\/sessions","kind":"article","role":"article","type":"topic","abstract":[{"text":"Session based authentication","type":"text"}],"identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/Hummingbird\/Sessions"},"doc://com.opticalaberration.hummingbird/documentation/HummingbirdAuth/HBAuthenticatable":{"fragments":[{"text":"protocol","kind":"keyword"},{"kind":"text","text":" "},{"text":"HBAuthenticatable","kind":"identifier"}],"title":"HBAuthenticatable","identifier":"doc:\/\/com.opticalaberration.hummingbird\/documentation\/HummingbirdAuth\/HBAuthenticatable","url":"\/documentation\/hummingbirdauth\/hbauthenticatable","abstract":[{"text":"Protocol for objects that can be returned by an ","type":"text"},{"code":"HBAuthenticator","type":"codeVoice"},{"text":".","type":"text"}],"type":"topic","role":"symbol","kind":"symbol","navigatorTitle":[{"text":"HBAuthenticatable","kind":"identifier"}]}}}