Authentication is tedious. Many projects need some sort of authentication system. And in many of these projects you will basically start from scratch. That's why cbauth was created.

cbauth is a library that handles creating user sessions for your app including authenticating users, logging users in and out, and retrieving the currently authenticated user. It is customizable to plug in to your existing authentication method and session storage.

These are some of the methods you can use in your project:

auth.authenticate( username, password );
auth.isLoggedIn();
auth.getUser();
auth.logout();

Requirements

• Lucee 5+

• Adobe ColdFusion 2016+

• Coldbox 4.3 +

Installation

cbauth can be installed with

box install cbauth

Configuration

cbauth needs a userServiceClass which has to be specified in the module settings. It should be a WireBox mapping that resolves to a component that implements the IUserService interface (though this implementation can be implicit.)

By default, cbauth uses sessionStorage@cbstorages and RequestStorage@cbstorages for the sessionStorage and requestStorage, respectively.

Your config settings will look like this:

	moduleSettings = {
			cbauth: {
				userServiceClass: "UserService",
				// optional, override when needed
				sessionStorage: "SessionStorage@cbstorages",
				requestStorage: "RequestStorage@cbstorages"
			},
			//..... other module settings 
	}

You can specify other requestStorage or sessionStorage (e.g distributed cache) as long as your new storages follow the Interface definitions as defined:

interface name="SessionStorageInterface" { // or "RequestStorageInterface"
	  public any function getVar( required string name, any defaultValue );
	  public void function setVar( required string name, required any value );
	  public boolean function deleteVar( required string name );
	  public boolean function exists( required string name );
}

Usage

interface {

	/**
	 * Verify if the incoming username/password are valid credentials.
	 *
	 * @username The username
	 * @password The password
	 */
	boolean function isValidCredentials( required username, required password );

	/**
	 * Retrieve a user by username
	 *
	 * @return User that implements IAuthUser
	 */
	function retrieveUserByUsername( required username );

	/**
	 * Retrieve a user by unique identifier
	 *
	 * @id The unique identifier
	 *
	 * @return User that implements IAuthUser
	 */
	function retrieveUserById( required id );
	
}

interface {

    /**
     * Return the unique identifier for the user
     */
    function getId();

}

When you have create your User and UserService and configured the moduleSettings you are ready to use the AuthenticationService. You can inject the authentication service using WireBox:

property name="auth" inject="authenticationService@cbauth";

// OR

var auth = wirebox.getInstance( "authenticationService@cbauth" );

Or, the quick way, you can just use the auth() helper method (which is actually just a shortcut to a wirebox injection). The auth() helper is very useful in views. And since Wirebox handles singleton management, you don't have to worry about calling auth()too many times.

The Authentication service provides you with all methods for handling user sessions, e.g:

auth.authenticate( username, password );
auth.isLoggedIn();
auth.getUser();
auth.logout();

After login your userID is stored in sessionstorage. Your user object will be cached in the requeststorage, so you only have to hit your database once per request to access user information.

v5.0.1

24 Apr 2020 — 03:47:00 UTC

other

v5.0.0

02 Apr 2020 — 22:10:08 UTC

BREAKING

v4.1.2

18 Feb 2020 — 17:27:02 UTC

other

v4.1.1

13 Feb 2020 — 17:36:32 UTC

other

v4.1.0

23 Dec 2019 — 18:06:36 UTC

feat

v4.0.0

02 Oct 2019 — 05:29:36 UTC

BREAKING

v3.0.3

24 Sep 2019 — 16:40:21 UTC

other

v3.0.2

22 Sep 2019 — 19:08:45 UTC

other

v3.0.1

22 Sep 2019 — 18:58:14 UTC

chore

v3.0.0

12 Jul 2019 — 20:14:17 UTC

BREAKING

v2.0.0

25 Oct 2018 — 06:56:50 UTC

BREAKING

chore

fix

other

v2.0.0

25 Oct 2018 — 06:40:06 UTC

BREAKING

chore

fix

other

cbauth is quite flexible. In your IUserService implementation you can define how you want to retrieve your IAuthUser implementation: from a database, LDAP or any other authentication provider. You can define any properties you want to store, permissions or roles, and additional data for your authenticated user.

The current user will be retrieved and cached in a configured requestStorage. The userID will be stored in a configured sessionStorage. Both sessionStorage and requestStorage can be anything you want, as long as they implement the required methods. A common scenario, for example, is when you don't want to use ColdFusion or Lucee sessions for API applications, but instead use a distributed cache.

The authentication service can be used by injecting it using WireBox:

property name="auth" inject="authenticationService@cbauth";

// OR

var auth = wirebox.getInstance( "authenticationService@cbauth" );

Or, the quick way, you can just use the auth() helper method (which is actually just a shortcut to a wirebox injection). The auth() helper is very useful in views. And since Wirebox handles singleton management, you don't have to worry about calling auth()too many times.

Methods

login

logout

Logs a user out of system. This method can be called regardless of if there is currently a logged in user.

authenticate

Attempts to log a user by calling the retrieveUserByUsername and isValidCredentials on the provided userServiceClass. If isValidCredentials returns false, it throws a InvalidCredentials exception.

If it succeeds, it returns the logged in user object. If it succeeds, it also sets the user id (obtained by calling getId() on the returned user component) in the configured sessionStorage and the returned user component in the configured requestStorage.

isLoggedIn

Returns boolean whether a user is logged in to the system.

check

Alias for isLoggedIn

guest

Returns whether a user is logged out of the system. Opposite of check() and isLoggedIn().

getUser

Returns the currently logged in user component.

If there is no logged in user, it throws a NoUserLoggedIn exception.

If there is a user object in the configured requestStorage, it is returned.

If the user object has not been fetched this request, it uses the id set in the configured sessionStorage to fetch the user (using retrieveUserById). It then sets the user in the configured requestStorage so subsequent calls to getUser don't re-fetch the user.

user

Alias for getUser

getUserId

Returns the currently logged in user id.

If there is no logged in user, it throws a NoUserLoggedIn exception.

Interceptions

cbauth announces several custom interception points. You can use these interception points to change request data or add additional values to session or request scopes. The preAuthentication and postAuthentication events fire during the standard authenticate() method call with a username and password. The preLogin and postLogin events fire during the login() method call. The preLogout and postLogout events fire during the logout() method call.

preAuthentication

InterceptData

Modifying the values in the interceptData will change what is passed to isValidCredentials and retrieveUserByUsername. This is the prime time to ignore certain requests or remove or pad usernames.

postAuthentication

InterceptData

This is the prime time to store additional values based on the user returned.

preLogin

InterceptData

postLogin

InterceptData

This is a good opportunity to store additional data if your application logged the user in manually without authenticating via a username/password like a "remember me" system.

preLogout

InterceptData

postLogout

InterceptData