BoxLang 🚀 A New JVM Dynamic Language Learn More...

cbauth

v6.1.0 Modules

cbauth

Authentication services for ColdBox Applications.

Requirements

  • Lucee 5+
  • Adobe ColdFusion 2018+

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 )

We have provided an interface to implement and can be found at cbauth.interfaces.IUserService.

Additionally, the user component returned by the retrieve methods needs to respond to getId(). We have also provided a nice interface for you to follow: cbauth.interfaces.IAuthUser

You can also specify a sessionStorage and a requestStorage WireBox mapping. These will be used inside AuthenticationService. By default, these are SessionStorage@cbstorages and RequestStorage@cbstorages 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="authenticationService@cbauth";

// OR

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

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

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

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
useranytrue The 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. This method returns the passed in user object.

logout

nametyperequireddefaultdescription
quietbooleanfalsefalseSkips firing interception events if true

Logs a user out of system. This method can be called regardless of if there is currently a logged in user. This method fires two interception events: preLogout and postLogout. The preLogout event recieves the currently logged-in user, if there is one.

quietLogout

nametyperequireddefaultdescription
No arguments

Logs a user out of system without firing interception events. Useful in testing situations where the "logged in" user may no longer exist in your database.

authenticate

nametyperequireddefaultdescription
usernamestringtrue The username to attempt to log in.
passwordstringtrue The 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 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 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

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.

Note: the preLogin and postLogin interception points will be called during the course of authenticate(). The order of the calls then are preAuthentication -> preLogin -> postLogin -> postAuthentication.

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.

preLogin

interceptData

namedescription
userThe user component to be logged in.

postLogin

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 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

namedescription
userThe user component that is logged in if you are logged in, else null

postLogout

interceptData

namedescription

v6.1.0

13 May 2024 — 16:34: 33 UTC

feat

  • AuthenticationService: Make getUserService publically available (4f83978)

v5.0.3

25 Aug 2020 — 16:56: 30 UTC

fix

  • CI: Ensure coldbox is not added as a dependency from CI (132adc4)

v5.0.2

19 May 2020 — 05:46: 52 UTC

other

  • *: fix: Removing session key if there is a problem retrieving the user (799211b)

v5.0.1

24 Apr 2020 — 03:47: 00 UTC

other

  • *: fix: Allow any dsl to be the user service (7cfb533)

v5.0.0

02 Apr 2020 — 22:10: 08 UTC

BREAKING

  • *: feat: Added interception points and return user from authorize (778cd73)

v4.1.2

18 Feb 2020 — 17:27: 02 UTC

other

  • *: Adjust gitignore file for better directory matching (a2d0ba3)

v4.1.1

13 Feb 2020 — 17:36: 32 UTC

other

  • *: chore: Use forgeboxStorage (7ac6965)

v4.1.0

23 Dec 2019 — 18:06: 36 UTC

feat

  • Login: Add new preLogin and postLogin interception points (495d516)

v4.0.0

02 Oct 2019 — 05:29: 36 UTC

BREAKING

  • cbstorages: Upgrade cbstorages to 2.0.0 (10b3156)

v3.0.3

24 Sep 2019 — 16:40: 21 UTC

other

  • *: chore: Transfer cbauth to coldbox-modules namespace (2616896)

v3.0.2

22 Sep 2019 — 19:08: 45 UTC

other

  • *: docs: Fixed Coldbox 4.3 docs link (d4252ce)

v3.0.1

22 Sep 2019 — 18:58: 14 UTC

chore

  • build: Use openjdk8 on Travis (0ba288b)

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

  • ci: Add commandbox-semantic-release (d9a0411)
  • formatting: Clean up spacing at end of lines (ba8f1d3)
  • server.json: Default to adobe@11 servers (a73da29)
  • tests: Remove Gulpfile and npm dependencies (031a697)

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

  • ci: Add commandbox-semantic-release (d9a0411)
  • formatting: Clean up spacing at end of lines (ba8f1d3)
  • server.json: Default to adobe@11 servers (a73da29)
  • tests: Remove Gulpfile and npm dependencies (031a697)

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)

$ box install cbauth

  • {{ getFullDate("2016-10-21T17:01:19Z") }}
  • {{ getFullDate("2024-05-13T16:34:35Z") }}
  • 13,206
  • 111,585