Authentication Services
ColdBox security can work with ANY authentication service provider.
You can register ANY authentication provider with cbsecurity by using the authenticationService setting. The value must be a valid WireBox Id and the object must adhere to the following interface. The authentication services can be used in conjunction with our JWT services and more features coming in the future.
1
// CB Security
2
cbSecurity : {
3
4
// The WireBox ID of the authentication service to use in cbSecurity which must adhere to the cbsecurity.interfaces.IAuthService interface.
5
"authenticationService" : "[email protected]"
6
7
}
Copied!
Please note that cbauth already implements this interface and is included with cbsecurity as a dependency.
If you are using cbauth as your authenticationService (the default), you also need to configure cbauth.

Authentication Service Interface

This interface has been provided by convenience and it is not mandatory at runtime (cbsecurity.interfaces.IAuthService)
cbsecurity.interfaces.IAuthService.cfc
1
/**
2
* Copyright since 2016 by Ortus Solutions, Corp
3
* www.ortussolutions.com
4
* ---
5
* If you register an authentication service with cbsecurity it must adhere to this interface
6
*/
7
interface{
8
9
/**
10
* Get the authenticated user
11
*
12
* @throws NoUserLoggedIn : If the user is not logged in
13
*
14
* @return User that implements IAuthUser
15
*/
16
any function getUser();
17
18
/**
19
* Verifies if a user is logged in
20
*/
21
boolean function isLoggedIn();
22
23
/**
24
* Try to authenticate a user into the system. If the authentication fails an exception is thrown, else the logged in user object is returned
25
*
26
* @username The username to log in with
27
* @password The password to log in with
28
*
29
* @throws InvalidCredentials
30
*
31
* @return User : The logged in user object
32
*/
33
any function authenticate( required username, required password );
34
35
/**
36
* Login a user into our persistent scopes
37
*
38
* @user The user object to log in
39
*
40
* @return The same user object so you can do functional goodness
41
*/
42
function login( required user );
43
44
/**
45
* Logs out the currently logged in user from the system
46
*/
47
function logout();
48
49
50
}
Copied!
You can find the information for cbauth in its own book:
Introduction
cbAuth
If you are using cbauth as your authenticationService (the default), you also need to configure cbauth.

User Interface

As you can see from above, the authentication services all expect a User object to model your user in the system. So your User object must also adhere to the following methods modeled by the cbsecurity.interfaces.IAuthUser interface. This will allow the validators and JWT services to get the appropriate data it needs.
cbsecurity.interfaces.IAuthUser.cfc
1
interface{
2
3
/**
4
* Return the unique identifier for the user
5
*/
6
function getId();
7
8
/**
9
* Verify if the user has one or more of the passed in permissions
10
*
11
* @permission One or a list of permissions to check for access
12
*
13
*/
14
boolean function hasPermission( required permission );
15
16
}
Copied!

User Services

If you will be using cbauth or any of our JWT features, then we will also require you register a user service class that can provide us with the right data to encapsulate security using the userService setting. We have provided this interface for your usage:
cbsecurity.interfaces.IUserService.cfc
1
interface{
2
3
/**
4
* Verify if the incoming username/password are valid credentials.
5
*
6
* @username The username
7
* @password The password
8
*/
9
boolean function isValidCredentials( required username, required password );
10
11
/**
12
* Retrieve a user by username
13
*
14
* @return User that implements JWTSubject and/or IAuthUser
15
*/
16
function retrieveUserByUsername( required username );
17
18
/**
19
* Retrieve a user by unique identifier
20
*
21
* @id The unique identifier
22
*
23
* @return User that implements JWTSubject and/or IAuthUser
24
*/
25
function retrieveUserById( required id );
26
}
Copied!
If using cbauth, you also have to specify the UserServiceClass key in the cbauth module settings.
Remember that the User Service setting is only required if you will be using JWT token security