cbAuth
  • Introduction
  • What's New
  • Installation and Usage
  • Authentication Service
  • IUserService
  • IAuthUser
  • Customization Options
  • Interception points
  • External links
    • cbSecurity
    • cbGuard
Powered by GitBook
On this page
  • Requirements
  • Installation
  • Configuration
  • Usage

Was this helpful?

Edit on GitHub
Export as PDF

Installation and Usage

PreviousWhat's NewNextAuthentication Service

Last updated 2 years ago

Was this helpful?

Requirements

  • Lucee 5+

  • Adobe ColdFusion 2016+

  • Coldbox 4.3 +

Installation

cbauth requires ColdBox 4.3 or higher for .

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 );
}

You don't have to formally implement the interface in your code.

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 auth() helper is available in handlers, layouts, and views. You will need to use the injection if you need cbauth in other models.

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.

Before you can use cbauth you have to create a UserService which implement the .

You also have a User class which implements the interface.

If you use cbauth combined with or there are some additional method requirements for the User. Please check the corresponding docs for details.

The full list of methods is described in the section.

module parent settings
IUserService
IauthUser
cbsecurity
cbguard
Authentication Service