FORGEBOX Enterprise 🚀 - Take your ColdFusion (CFML) Development to Modern Times! Learn More...

cbauth

v3.0.0 Public

cbauth

Wrapper for authentication for ColdBox.

Installation

Requires ColdBox 4.3 for module parent settings.

box install cbauth

Specify a userServiceClass in your config/ColdBox.cfc inside moduleSettings.cbauth.userServiceClass. This component needs to have three methods:

  1. isValidCredentials( username, password )
  2. retrieveUserByUsername( username )
  3. retrieveUserById( id )

Additionally, the user component returned by the retrieve methods needs to respond to getId().

You can also specify a sessionStorage and a requestStorage WireBox mapping. These will be used inside AuthenticationService. By default, these are [email protected] and [email protected] respectively. Interfaces are provided in the models folder for reference when building your own. (Your storage classes do not need to formally implement the interface.)

Usage

You can inject the authenticationService using WireBox.

property name="auth" inject="[email protected]";

// OR

var auth = wirebox.getInstance( "[email protected]" );

Or, the quick way, using the auth() helper.

auth() == wirebox.getInstance( "[email protected]" );

This is very useful in views. And since WireBox handles singleton management, you don't need to worry about calling auth() too many times.

Methods

login

nametyperequireddefaultdescription
useranytrueThe user component to log in. The component must respond to the getId() method.

Logs a user in to the system. The user component must respond to the getId() method. Additionally, the user is cached in the request scope. If a user is already in the session, this will replace it with the given user.

logout

nametyperequireddefaultdescription
No arguments

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

authenticate

nametyperequireddefaultdescription
usernamestringtrueThe username to attempt to log in.
passwordstringtrueThe password to attempt to log in.

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

If it succeeds, it returns true. If it succeeds, it also sets the user id (obtained by calling getId() on the returned user component) in the session and the returned user component in the request.

isLoggedIn

nametyperequireddefaultdescription
No arguments

Returns whether a user is logged in to the system.

check

nametyperequireddefaultdescription
No arguments

Alias for isLoggedIn

guest

nametyperequireddefaultdescription
No arguments

Returns whether a user is logged out of the system.

getUser

nametyperequireddefaultdescription
No arguments

Returns the currently logged in user component.

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

Additionally, it sets the user in the request scope so subsequent calls to getUser don't re-fetch the user from the database or other permanent storage.

user

nametyperequireddefaultdescription
No arguments

Alias for getUser

getUserId

nametyperequireddefaultdescription
No arguments

Returns the currently logged in user id.

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

Interception Points — (preAuthentication & postAuthentication)

cbauth announces two custom interception points — preAuthentication and postAuthentication. You can use these interception points to change request data or add additional values to session or request scopes.

preAuthentication

interceptData

namedescription
usernameThe username passed in to cbauth.
passwordThe password passed in to cbauth.

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

namedescription
userThe user component to be logged in.
sessionStorageThe sessionStorage object to store additional values if needed.
requestStorageThe requestStorage object to store additional values if needed.

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

v3.0.0

12 Jul 2019 — 20:14: 17 UTC

BREAKING

  • Storages: Allow customizing of storages (b97a8ad)

v2.0.0

25 Oct 2018 — 06:56: 50 UTC

BREAKING

  • build: Trigger major release for prior commit (fca4bc5)

chore

fix

  • build: Update box.json references to elpete (76e416e)
  • build: Remove incompatible scripts for commandbox-semantic-release (252db7e)
  • tests: Fix MockBox expectation to match struct pattern (2e5fe23)

other

  • *: Merge pull request #3 from elpete/add_csr (74c4f63)
  • *: Merge pull request #2 from jclausen/master (8c71db8)

v2.0.0

25 Oct 2018 — 06:40: 06 UTC

BREAKING

  • build: Trigger major release for prior commit (fca4bc5)

chore

fix

  • build: Remove incompatible scripts for commandbox-semantic-release (252db7e)
  • tests: Fix MockBox expectation to match struct pattern (2e5fe23)

other

  • *: Merge pull request #3 from elpete/add_csr (74c4f63)
  • *: Merge pull request #2 from jclausen/master (8c71db8)

Here are all the versions for this package. Please note that you can leverage CommandBox package versioning to install any package you like. Please refer to our managing package version guide for more information.

Version Created Last Update Published By Stable Actions
Current
3.0.0 Jul 12 2019 03:14 PM Jul 12 2019 03:14 PM
Version History
2.0.0 Oct 25 2018 01:56 AM Oct 25 2018 01:56 AM
1.0.5 Oct 25 2016 06:17 PM Oct 25 2016 06:17 PM
1.0.4 Oct 25 2016 05:56 PM Oct 25 2016 05:56 PM
1.0.3 Oct 25 2016 01:06 PM Oct 25 2016 01:06 PM
1.0.2 Oct 25 2016 12:58 PM Oct 25 2016 12:58 PM
1.0.1 Oct 25 2016 12:54 PM Oct 25 2016 12:54 PM
1.0.0 Oct 21 2016 05:01 PM Oct 21 2016 05:01 PM

 

No collaborators yet.
  • Oct 21 2016 05:01 PM
  • Jul 12 2019 03:14 PM
  • 1636
  • 0
  • 1296