From 55f201a2aa5e095718e0845a18f8b917253ff9de Mon Sep 17 00:00:00 2001 From: Richard Hansen Date: Thu, 27 Aug 2020 14:06:27 -0400 Subject: [PATCH] docs: Document the authFailure hook --- doc/api/hooks_server-side.md | 29 ++++++++++++++++++++++++++++- 1 file changed, 28 insertions(+), 1 deletion(-) diff --git a/doc/api/hooks_server-side.md b/doc/api/hooks_server-side.md index 2d9b66e8f..55b457433 100644 --- a/doc/api/hooks_server-side.md +++ b/doc/api/hooks_server-side.md @@ -336,7 +336,34 @@ Things in context: 2. res - the response object 3. next - ? -This is useful for modifying the way authentication is done. +This hook is called to handle an authentication or authorization failure. + +Plugins that supply an authenticate function should probably also supply an +authFailure function unless falling back to HTTP basic authentication is +appropriate upon authentication failure. + +A plugin's authFailure function is only called if all of the following are true: + +* There was an authentication or authorization failure. +* The failure was not already handled by an authFailure function from another + plugin. + +Calling the provided callback with `[true]` tells Etherpad that the failure was +handled and no further error handling is required. Calling the callback with +`[]` or `undefined` defers error handling to the next authFailure plugin (if +any, otherwise fall back to HTTP basic authentication). + +Example: + +``` +exports.authFailure = (hookName, context, cb) => { + if (notApplicableToThisPlugin(context)) { + return cb([]); // Let the next plugin handle the error + } + context.res.redirect(makeLoginURL(context.req)); + return cb([true]); +}; +``` ## handleMessage Called from: src/node/handler/PadMessageHandler.js