/lift-mongoauth

Auth module for Lift using MongoDB

Primary LanguageScalaApache License 2.0Apache-2.0

MongoAuth Lift Module

Build Status

Authentication and Authorization module for Lift-MongoDB-Record.

Installation

Releases use the Lift "edition" in the name. For example, if you use any of 2.5-SNAPSHOT, 2.5-RC4, or 2.5 the Lift edition is 2.5.

Note: some of the versions published had a '-' in the edition instead of a '.'. I.e mongoauth_2-5 instead of mongoauth_2.3.

To include this module in your Lift project change build.sbt to include:

libraryDependencies += "net.liftmodules" %% "mongoauth_3.3" % "1.4.3"

Previous releases

Lift Version Scala Version Module Version
3.4.3+ 2.12, 2.13 1.4.4
3.3 2.12, 2.11 1.4.3
3.2 2.12, 2.11 1.4.3
3.1 2.12, 2.11 1.4.0
3.0 2.12, 2.11 1.2
2.6 2.10, 2.9 0.7
2.5 2.10, 2.9 0.5

Configuration

You must set the MongoAuth.authUserMeta object that you will be using (see below). Most likely in boot:

// init mongoauth
MongoAuth.authUserMeta.default.set(User)
MongoAuth.indexUrl.default.set(Sitemap.home.path)

See MongoAuth 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
) :_*))

Creating a User Data Model

This module provides several traits for constructing user model classes, which include roles and permissions.

There are several ways you can utilize this module:

SimpleUser

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

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

MongoAuthUser

MongoAuthUser is a trait for defining a MongoRecord of AuthUser (provides authorization functionality). This can be used to build a user class from scratch. It only requires id and email fields.

ProtoAuthUserMeta

ProtoAuthUserMeta is a combination of AuthUserMeta and UserLifeCycle traits. These provide authorization functionality and login/logout functionality for MongoMetaRecord objects. No matter which version you use for the MongoRecord user class, you can use this trait to define your MongoMetaRecord, 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 ObjectId) on the url. When they click on it they can be handled appropriately. The implementation is left up to you.

Roles and Permissions

Permissions are defined using 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.

PermissionListField provides a way to store permissions for a user. It stores them as a list of strings.

Example:

user.permissions(List(Permission("printer", "print"), Permission("user", "edit", "123")))

assert(User.hasPermission(Permission("printer", "manage")) == false)

Role is a MongoRecord 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.createRecord.id("superuser").permissions(List(Permission.all)).save

user.roles(List("superuser"))

assert(User.hasRole("superuser")) == true)
assert(User.lacksRole("superuser")) == false)
assert(User.lacksRole("admin")) == true)

SiteMap LocParams

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(Permission("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.

Localization

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.

Example Implementation

The lift-mongo giter8 template provides a fully functioning implementation of a basic user system.

License

Apache v2.0. See LICENSE.txt