CBSecurity

Class CBSecurity

lucee.Component
    models.CBSecurity

Copyright since 2016 by Ortus Solutions, Corp www.ortussolutions.com --- This service is in charge of offering security capabilties to your ColdBox applications It can be injected by using the `@cbSecurity` annotation

property name="cbSecurity" inject="@cbsecurity";

Or you can use the `cbSecure()` mixin

cbsecure().secure();

Class Attributes:

threadsafe

singleton

synchronized : false

accessors : true

persistent : false

Property Summary
type	property	default	serializable	required
`any`	DBLogger access = public returntype = any inject = DBLogger@cbsecurity		`true`	`false`
`any`	async access = public returntype = any inject = coldbox:asyncManager		`true`	`false`
`any`	authService The auth service in use according to the configuration file. access = public returntype = any		`true`	`false`
`any`	log access = public returntype = any inject = logbox:logger:{this}		`true`	`false`
`any`	moduleSettings access = public returntype = any inject = coldbox:setting:modules		`true`	`false`
`any`	settings access = public returntype = any inject = coldbox:moduleSettings:cbsecurity		`true`	`false`
`any`	userService The user service in use according to the configuration file. access = public returntype = any		`true`	`false`
`any`	wirebox access = public returntype = any inject = wirebox		`true`	`false`

Constructor Summary
init() Constructor.

Method Summary
`private any`	_when(boolean target, any success, [any failure]) TODO: Migrate from FlowHelpers once ColdBox 7 goes gold.
`boolean`	all(any permissions) Verify that ALL the permissions passed must exist within the authenticated user.
`private any`	arrayWrap(any items) convert one or a list of permissions to an array, if it's an array we don't touch it.
`any`	authenticate(any username, any password) Login Facade.
`any`	createPassword([numeric length='32'], [boolean letters='true'], [boolean numbers='true'], [boolean symbols='true']) Generate a random, secure password using several options.
`string`	getAsync()
`any`	getAuthService() Get the authentication service defined accordingly in the settings.
`string`	getDBLogger()
`struct`	getDefaultRuleSettings() Get the default rule settings structure.
`string`	getLog()
`string`	getModuleSettings()
`string`	getRealHost([boolean trustUpstream='true']) Get the real host by looking at the upstreams if trusted or not.
`string`	getRealIP([boolean trustUpstream='true']) Get Real IP, by looking at clustered, proxy headers and locally.
`string`	getSettings()
`any`	getUser() Get the authenticated user.
`any`	getUserService() Get the user service object defined accordingly in the settings.
`string`	getWirebox()
`any`	guard() Alias proxy if somebody is coming from cbguard, proxies to the secure() method.
`boolean`	has(any permissions) Verify if the incoming permissions exist in the currently authenticated user.
`boolean`	isLoggedIn() Verifies if a user is logged in.
`void`	logout() Logout Facade.
`boolean`	none(any permissions) Verify that NONE of the permissions passed must exist within the authenticated user.
`any`	onDIComplete()
`boolean`	sameUser(any user) Verify that the passed in user object must be the same as the authenticated user.
`CBSecurity`	secure(any permissions, [any message='[runtime expression]']) Verifies if the currently logged in user has any of the passed permissions.
`CBSecurity`	secureAll(any permissions, [any message='[runtime expression]']) Verifies if the currently logged in user has ALL of the passed permissions.
`CBSecurity`	secureNone(any permissions, [any message='[runtime expression]']) Verifies if the currently logged in user has NONE of the passed permissions.
`CBSecurity`	secureSameUser(any user, [any message='[runtime expression]']) Verifies that the passed in user object must be the same as the authenticated user.
`any`	secureView(any event, any permissions, any successView, [any failView]) This method is injected into all request contex's in order to allow you to easily.
`any`	secureViewProxy(any permissions, any successView, [any failView]) This is the method proxy injected into the request context that will act like the.
`CBSecurity`	secureWhen(any context, [any message='[runtime expression]']) Verifies the passed in context closure/lambda/udf to a boolean expression.
`any`	setAsync(any async)
`any`	setAuthService(any authService)
`any`	setDBLogger(any DBLogger)
`any`	setLog(any log)
`any`	setModuleSettings(any moduleSettings)
`any`	setSettings(any settings)
`any`	setUserService(any userService)
`any`	setWirebox(any wirebox)
`any`	when(any permissions, any success, [any fail]) This method will verify that any permissions must exist in the currently logged in user.
`any`	whenAll(any permissions, any success, [any fail]) This method will verify that ALL permissions must exist in the currently logged in user.
`any`	whenNone(any permissions, any success, [any fail]) This method will verify that NONE of the permissions must exist in the currently logged in user.

Methods inherited from class `lucee.Component`
None

Constructor Detail

init

public init()

Constructor

Property Detail

DBLogger

property any DBLogger

Attributes:: access - public; required - false; returntype - any; inject - DBLogger@cbsecurity; serializable - true

async

property any async

Attributes:: access - public; required - false; returntype - any; inject - coldbox:asyncManager; serializable - true

authService

property any authService

The auth service in use according to the configuration file

Attributes:: access - public; required - false; returntype - any; serializable - true

log

property any log

Attributes:: access - public; required - false; returntype - any; inject - logbox:logger:{this}; serializable - true

moduleSettings

property any moduleSettings

Attributes:: access - public; required - false; returntype - any; inject - coldbox:setting:modules; serializable - true

settings

property any settings

Attributes:: access - public; required - false; returntype - any; inject - coldbox:moduleSettings:cbsecurity; serializable - true

userService

property any userService

The user service in use according to the configuration file

Attributes:: access - public; required - false; returntype - any; serializable - true

wirebox

property any wirebox

Attributes:: access - public; required - false; returntype - any; inject - wirebox; serializable - true

Method Detail

_when

private any _when(boolean target, any success, [any failure])

TODO: Migrate from FlowHelpers once ColdBox 7 goes gold. This function evaluates the target boolean expression and if `true` it will execute the `success` closure else, if the `failure` closure is passed, it will execute it.

Parameters:: target - The boolean evaluator, this can be a boolean value; success - The closure/lambda to execute if the boolean value is true; failure - The closure/lambda to execute if the boolean value is false

Returns:: Returns itself

all

public boolean all(any permissions)

Verify that ALL the permissions passed must exist within the authenticated user

Parameters:: permissions - One, a list or an array of permissions

Throws:: NoUserLoggedIn

arrayWrap

private any arrayWrap(any items)

convert one or a list of permissions to an array, if it's an array we don't touch it

Parameters:: items - One, a list or an array

authenticate

public any authenticate(any username, any password)

Parameters:: username - The username to log in with; password - The password to log in with

Returns:: User : The logged in user object

Throws:: InvalidCredentials

createPassword

public any createPassword([numeric length='32'], [boolean letters='true'], [boolean numbers='true'], [boolean symbols='true'])

Generate a random, secure password using several options

Parameters:: length - The length of the password. Defaults to 32 characters; letters - Use letters; numbers - Use numbers; symbols - Use symbols

Returns:: A secure random password

getAsync

public string getAsync()

getAuthService

public any getAuthService()

Get the authentication service defined accordingly in the settings

Returns:: cbsecurity.interfaces.IAuthService

Throws:: IncompleteConfiguration

getDBLogger

public string getDBLogger()

getDefaultRuleSettings

public struct getDefaultRuleSettings()

Get the default rule settings structure

getLog

public string getLog()

getModuleSettings

public string getModuleSettings()

getRealHost

public string getRealHost([boolean trustUpstream='true'])

Get the real host by looking at the upstreams if trusted or not

Parameters:: trustUpstream - If true, we check the forwarded headers first, else we don't

getRealIP

public string getRealIP([boolean trustUpstream='true'])

Get Real IP, by looking at clustered, proxy headers and locally.

Parameters:: trustUpstream - If true, we check the forwarded headers first, else we don't

getSettings

public string getSettings()

getUser

public any getUser()

Get the authenticated user Change to delegates on CB7

Returns:: User that implements IAuthUser

Throws:: NoUserLoggedIn : If the user is not logged in

getUserService

public any getUserService()

Get the user service object defined accordingly in the settings

Returns:: cbsecurity.interfaces.IUserService

Throws:: IncompleteConfiguration

getWirebox

public string getWirebox()

guard

public any guard()

Alias proxy if somebody is coming from cbguard, proxies to the secure() method

has

public boolean has(any permissions)

Verify if the incoming permissions exist in the currently authenticated user. All permissions are Or'ed together

Parameters:: permissions - One, a list or an array of permissions

Throws:: NoUserLoggedIn

isLoggedIn

public boolean isLoggedIn()

Verifies if a user is logged in

logout

public void logout()

Logout Facade

none

public boolean none(any permissions)

Verify that NONE of the permissions passed must exist within the authenticated user

Parameters:: permissions - One, a list or an array of permissions

Throws:: NoUserLoggedIn

onDIComplete

public any onDIComplete()

sameUser

public boolean sameUser(any user)

Verify that the passed in user object must be the same as the authenticated user Equality is done by evaluating the `getid()` method on both objects.

Parameters:: user - The user to test for equality

Throws:: NoUserLoggedIn

secure

public CBSecurity secure(any permissions, [any message='[runtime expression]'])

Verifies if the currently logged in user has any of the passed permissions.

Parameters:: permissions - One, a list or an array of permissions; message - The error message to throw in the exception

Returns:: CBSecurity

Throws:: NotAuthorized

secureAll

public CBSecurity secureAll(any permissions, [any message='[runtime expression]'])

Verifies if the currently logged in user has ALL of the passed permissions.

Parameters:: permissions - One, a list or an array of permissions; message - The error message to throw in the exception

Returns:: CBSecurity

Throws:: NotAuthorized

secureNone

public CBSecurity secureNone(any permissions, [any message='[runtime expression]'])

Verifies if the currently logged in user has NONE of the passed permissions.

Parameters:: permissions - One, a list or an array of permissions; message - The error message to throw in the exception

Returns:: CBSecurity

Throws:: NotAuthorized

secureSameUser

public CBSecurity secureSameUser(any user, [any message='[runtime expression]'])

Verifies that the passed in user object must be the same as the authenticated user. Equality is done by evaluating the `getid()` method on both objects. If the equality check fails, a `NotAuthorized` exception is thrown.

Parameters:: user - The user to test for equality; message - The error message to throw in the exception

Throws:: NotAuthorized

secureView

public any secureView(any event, any permissions, any successView, [any failView])

This method is injected into all request contex's in order to allow you to easily switch between views if the permissions are not found in the user.

Parameters:: event - The proxied request context; permissions - One, a list or an array of permissions; successView - The view to set in the request context if the permissions pass; failView - The view to set in the request context if the permissions fails, optional

secureViewProxy

public any secureViewProxy(any permissions, any successView, [any failView])

This is the method proxy injected into the request context that will act like the `secureView()` method velow

Parameters:: permissions - One, a list or an array of permissions; successView - The view to set in the request context if the permissions pass; failView - The view to set in the request context if the permissions fails, optional

secureWhen

public CBSecurity secureWhen(any context, [any message='[runtime expression]'])

Verifies the passed in context closure/lambda/udf to a boolean expression. If the context is true, then the exception is thrown. The context must be false in order to pass. The context udf/closure/lambda must adhere to the following signature

function( user ){}
( user ) => {}

It receives the currently logged in user

Parameters:: context - A closure/lambda/udf that returns boolean, or a boolean expression; message - The error message to throw in the exception

Returns:: CBSecurity

Throws:: NotAuthorized

setAsync

public any setAsync(any async)

Parameters:: async

setAuthService

public any setAuthService(any authService)

Parameters:: authService

setDBLogger

public any setDBLogger(any DBLogger)

Parameters:: DBLogger

setLog

public any setLog(any log)

Parameters:: log

setModuleSettings

public any setModuleSettings(any moduleSettings)

Parameters:: moduleSettings

setSettings

public any setSettings(any settings)

Parameters:: settings

setUserService

public any setUserService(any userService)

Parameters:: userService

setWirebox

public any setWirebox(any wirebox)

Parameters:: wirebox

when

public any when(any permissions, any success, [any fail])

This method will verify that any permissions must exist in the currently logged in user. - If the result is true, then it will execute the success closure/lambda or udf. - If the restul is false, then it will execute the fail closure/lambda or udf The success or fail closures/lambdas/udfs must match the following signature

function( user, permissions ){}
( user, permissions ) => {}

They receive the currently logged in user and the permissions that where evaluated

Parameters:: permissions - One, a list, an array of permissions or boolean evaluation; success - The closure/lambda/udf that executes if the context passes; fail - The closure/lambda/udf that executes if the context fails

whenAll

public any whenAll(any permissions, any success, [any fail])

This method will verify that ALL permissions must exist in the currently logged in user. - If the result is true, then it will execute the success closure/lambda or udf. - If the restul is false, then it will execute the fail closure/lambda or udf The success or fail closures/lambdas/udfs must match the following signature

function( user, permissions ){}
( user, permissions ) => {}

They receive the currently logged in user and the permissions that where evaluated

Parameters:: permissions - One, a list or an array of permissions; success - The closure/lambda/udf that executes if the context passes; fail - The closure/lambda/udf that executes if the context fails

whenNone

public any whenNone(any permissions, any success, [any fail])

This method will verify that NONE of the permissions must exist in the currently logged in user. - If the result is true, then it will execute the success closure/lambda or udf. - If the restul is false, then it will execute the fail closure/lambda or udf The success or fail closures/lambdas/udfs must match the following signature

function( user, permissions ){}
( user, permissions ) => {}

They receive the currently logged in user and the permissions that where evaluated

Parameters:: permissions - One, a list or an array of permissions; success - The closure/lambda/udf that executes if the context passes; fail - The closure/lambda/udf that executes if the context fails