Installation and Usage
- Lucee 5+
- Adobe ColdFusion 2016+
- Coldbox 4.3 +
cbauth can be installed withbox install cbauth
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
[email protected] and [email protected] for the sessionStorage and requestStorage, respectively.Your config settings will look like this:
moduleSettings = {
cbauth: {
userServiceClass: "UserService",
// optional, override when needed
sessionStorage: "[email protected]",
requestStorage: "[email protected]"
},
//..... 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.
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();
}
If you use
cbauth combined with cbsecurity or cbguard there are some additional method requirements for the User. Please check the corresponding docs for details.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="[email protected]";
// OR
var auth = wirebox.getInstance( "[email protected]" );
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.
Last modified 8mo ago