Authentication and Authorization module for Lift-SQL-Mapper.
MapperAuth is a port of Tim Nelson's MongoAuth module to SQL/Mapper.
Jars are available via the liftmodules.net repo.
SBT 0.12
For Lift 2.5.x (Scala 2.9 and 2.10):
libraryDependencies += "net.liftmodules" %% "mapperauth_2.5" % "0.4-SNAPSHOT"
For Lift 3.0 M0 (Scala 2.10):
libraryDependencies += "net.liftmodules" %% "mapperauth_3.0" % "0.4-SNAPSHOT"
You must set the MapperAuth.authUserMeta object that you will be using (see below). Most likely in boot:
// init mapperauth
MapperAuth.authUserMeta.default.set(User)
MapperAuth.indexUrl.default.set(Sitemap.home.path)
See MapperAuth for other settings that can be overriden.
You will also probably want to add the logout and login-token menus.
LiftRules.setSiteMap(SiteMap(List(
Locs.buildLogoutMenu,
Locs.buildLoginTokenMenu
) :_*))
This module provides several traits for constructing user model classes, which include roles and permissions.
There are several ways you can utilize this module:
model.SimpleUser is a fully implemented user model, but is not extensible in any way. This is only useful for testing and demos. This shows what is necessary to create a user from ProtoAuthUser.
ProtoAuthUser and ProtoAuthUserMeta are a pair of traits that can be used to build a user model class and meta object. ProtoAuthUser has some standard fields. You can add fields to it, but you can't modify the ones provided. This is a good place to start. If you find you need to modify the provided fields, you can copy and paste them into your user class and use MapperAuthUser.
MapperAuthUser is a trait for defining a Mapper class of AuthUser (provides authorization functionality). This can be used to build a user class from scratch. It only requires id and email fields.
ProtoAuthUserMeta is a combination of AuthUserMeta and UserLifeCycle traits. These provide authorization functionality and login/logout functionality for MetaMapper objects. No matter which version you use for the Mapper user class, you can use this trait to define your MetaMapper, if it provides sufficient functionality.
"Remember Me" functionality is provided by ExtSession.
LoginToken provides a way for users that forgot their password to log in and change it. Users are sent a link with a token (an UUID) on the url. When they click on it they can be handled appropriately. The implementation is left up to you.
Permissions are stored in its own table, "permissions". To access them use APermission, a simple case class. They have three parts; domain, actions, entities. This was heavily influenced by Apache Shiro's WildcardPermission. Please see the JavaDoc for WildcardPermission for detailed information.
See PermissionSpec for examples.
You can either attach permissions directly to a user or create roles with permissions attached and then add these roles to the user.
Example:
Permission.createUserPermission(user, APermission("printer", "print")).save
Permission.createUserPermission(user, APermission("user", "edit", "123")).save
assert(User.hasPermission(APermission("printer", "manage")) == false)
Role is a Mapper instance that provides a way to group a set of permissions. A user's full set of permissions is calculated using the permissions from any roles assigned to them and the individual permissions assigned to them. There are also LocParams as well as the User-Meta-Singleton that can be used to check for roles.
Example:
val superuser = Role.findOrCreateAndSave("superuser", "a category", Permission.fromAPermission(APermission.all))
user.userRoles.addRole("superuser").saveMe
assert(User.hasRole("superuser")) == true)
assert(User.lacksRole("superuser")) == false)
assert(User.lacksRole("admin")) == true)
The Locs trait and companion object provide some useful LocParams that use can use when defing your SiteMap.
This code was inspired by the lift-shiro module.
Examples:
Meun.i("Settings") / "settings" >> RequireLoggedIn
Meun.i("Password") / "password" >> RequireAuthentication
Meun.i("Admin") / "admin" >> HasRole("admin")
Meun.i("EditEntitiy") / "admin" / "entity" >> HasPermission(APermission("entity", "edit"))
"Authenticated" means the user logged in by supplying their password. "Logged In" means the user was logged in by either an ExtSession or LoginToken, or they are Authenticated.
A default localization is provided and can be found here. If you require another language or would prefer different text, copy the default and subtitute your values. See the Localization page on the Liftweb wiki for more information.
The lift-bootstrap giter8 template provides a fully functioning implementation of a basic user system.
MapperAuth as well as lift-bootstrap are ported from Tim Nelson's lift-mongoauth and lift-mongo.
Apache v2.0. See LICENSE.txt