Tutorial: Security Context: Request-Level Security

Every request that comes into the server is assigned a security context. This context provides helpers for managing the request's lifecycle from a security perspective.

These contexts are provided by the auth:Utility global middleware (and are available regardless of whether a user is authenticated or not). The main purpose of this context is either preventing a request from accessing resources, or generating KeyActions.

For more info on KeyActions, see this page: Using KeyActions.

Using Security Contexts

The global middleware makes a request's security context available on the request.security field. This context is an instance of module:flitter-auth/SecurityContext~SecurityContext. Here are a few examples of its usage:

Deny Access to a Resource

See: module:flitter-auth/SecurityContext~SecurityContext#deny

some_controller_method(req, res) {
	if ( !req.user.can('some:permission:check') ) {
		return req.security.deny()
	}

	// Other code here...
}

This uses the deny() method on the security context. This stops the request and returns the 401 error page. Optionally, you can pass a message along as an argument:

some_controller_method(req, res) {
	if ( !req.user.can('some:permission:check') ) {
		return req.security.deny('You do not have access!')
	}

	// Other code here...
}

Kickout a User

See: module:flitter-auth/SecurityContext~SecurityContext#kickout

Similar to denying a request access to a resource, the kickout() method can be used to protect your application. Like deny(), it sends the client to a 401 error page, however if there is a user signed in to the session, they will be forcibly logged out. This can be useful if you reach a condition where you need to lock down a user's account:

some_controller_method(req, res) {
	if ( some_security_check_fails ) {
		return req.security.kickout('What are you doing...?')
	}
}

If there is not a user authenticated in the session, it behaves identically to deny().

Ban a User

See: module:flitter-auth/SecurityContext~SecurityContext#ban

Much like kickout() is a harsher version of deny(), ban() is a harsher version of kickout(). In addition to displaying a 401 error page and forcibly logging out the user, the ban() method sets the block_login flag on the user model to true. This flag is checked by all first-party Flitter Auth providers. If it is set, the user will not be allowed to sign in to the application.

some_controller_method(req, res) {
	if ( something_fishy_going_on ) {
		return req.security.ban('That is not okay!!')
	}
}

Again, if no user is authenticated in the session, it behaves identically to deny().

Get the Auth Provider

In rare cases, you may need to access the user's authentication provider class directly. Realistically, this only happens if you're doing something complicated, but it is possible through the provider() method. This method returns the instance of module:flitter-auth/Provider~Provider associated with the user.

async some_controller_method(req, res) {
	// Programmatically log out the user, quietly:
	await req.security.provider().logout(req)
	return res.send('You have been manually signed out!')
}

KeyActions

You can also use the security context to generate key actions. For more information on that, see Using KeyActions.