Custom

This page provides some guidance on how to define your own custom Authenticator class for use within the Application Server.

Implementation Class

We recommend extending the AbstractAuthenticator class. The basic skeleton of the class might look like this:

var AbstractAuthenticator = require("cloudcms-server/middleware/authentication/authenticators/abstract");

class CustomAuthenticator extends AbstractAuthenticator {

    constructor(req, config) {
        super(req, config);
    }

    identify(req, callback) {
        super.identify(req, callback);
    }
}

module.exports = CustomProvider;

In your app.js file, you can then register this custom authenticator like this:

server.init(function(app, callback) {
    auth.registerAuthenticator("customAuthenticator", require("./customAuthenticator"));
    callback();
});

And you can then register it via config:

server.start({
    "auth": {
        ...,
        "authenticators": {
            "myAuthenticator": {
                "type": "customAuthenticator"
            }
        }            
    }
});

Implementation Details

Here are some notes to aid in your implementation.

constructor

In this section, you will generally want to initialize any configuration options ahead of calling into the super method. The config that was provided in the server.start() call for the authenticator is available in the config variable.

For example, you might do this:

constructor(req, config)
{
    if (typeof(config.strict) === "undefined") {
        config.strict = true;
    }

    super(req, config);
}

Where strict is completely contrived example of setting a default. You could later access this setting to, say, adjust how the login method works. See below.

The config is a member variable and can be accessed from the other methods, allowing everything to be configuration driven. The other methods can simply reference this.config to get at configuration settings.

login

This method is called per-request and is responsible for "logging in" the identified user.

At a minimum, this means setting the user onto the request. The req.user property should hold the user so that downstream middleware and routes may reference it.

Other frameworks may have slightly different requirements. For example, with Express, you might call the req.logIn() method with the user.

Here is an example where we set the user and log the event:

login(req, res, gitanaUser, callback)
{
    req.user = gitanaUser;
    console.log("login() for user: "+ req.user.name);
    
    callback();
}

<a class='named-link' name='`logout''>

`logout'

This method is called once when the user clicks Log Out on the web site (or for any other reason that the application deems it necessary to tear down authentication for the user).

This method should do whatever is necessary to un-authenticate the user. This will mean different things depending on the scenario.

For example, if the token is an SSO token that was externally issue, then this method may not be able to directly remove the token. It may need to call out to an external service to cancel the token.

On the other hand, if the authenticated state is something that can be modified via response headers (such as removing a cookie), then that could be done here.

logout(req, res, callback)
{
    super.logout(req, res, callback);
}

isAuthenticated

Determines whether the current request is already authenticated for the given set of identifying properties.

This is called during an SSO filter's execution to determine whether the SSO identifier information should be used to authenticate the user. If the user is already authenticated, the process is skipped.

isAuthenticated(req, properties)
{
    return false;
}