1 Introduction

Nimble can save you months of development cost by providing common components that most of web applications require. Nimble provides beautiful UI and ready to use functionality for login, user registration, password reset, Users, Roles, Groups and permission management. Nimble provides administration portal from where all of the above stuff can be managed. Its possible to extends nimble administration portal to add other administration functionality for your application.

1.1 Overview

Authentication

Fine grained access control

2 Installation

Step 1: Install nimble plugin

plugins {
      compile ":nimble:0.5.1"
    }

For new projects, we recommend that you use the latest release of plugin. See Nimble plugin for latest version.

Step 2: Inject nimble into host application

grails jack-be-nimble <package> <User Class Name> <Profile Class Name>
Example:
grails jack-be-nimble com.example.domain User Profile

This is a very non-invasive procedure as far as the host application is concerned. One of the main goals of the Nimble project is to make it as invisible as possible when installed in a host application so as not to clutter up your business logic. Once complete, You will have following files in your copied into your project.

1. conf/NimbleConfig.groovy
2. conf/NimbleBootStrap.groovy
3. conf/NimbleSecurityFilters.groovy
4. conf/NimbleUrlMappings.groovy
5. domain/<package>/<User class>.groovy
6. domain/<package><Profile class>.groovy
7. views/templates/nimble/mail templates
8. i18n/messages-nimble.properties

At this point you are ready to start using nimble. Launch you application using grails run-app command. Open you browser and navigate to <app_url>/main and you will be asked to login.

By default Nimble creates two user accounts automatically, one with user rights and one with Administration rights.

You can login as:

1. user/useR123!
2. admin/admiN123!

The admin user will be able to access the full UI.

Congratulations Nimble is now fully activated within your application and you're ready to start wiring up your business logic.

3 Configuration

3.1 Configuring table names

Currently the following Nimble domain classes have been setup to utilize configurable table names

1. User
2. Profile
3. Role
4. Group
5. Permission
6. LevelPermission
7. LoginRecord
8. Url

Default table names specified in DefaultNimbleConfig.groovy is as below:

1. user = "_user"
2. role = "_role"
3. group = "_group"
4. profilebase = "profile_base"
5. loginrecord = "login_record"
6. permission = "permission"
7. levelpermission = "level_permission"
8. url = "url"

You can change default table names by overriding it in conf/NimbleConfig.groovy as shown below:

nimble {
  tablenames {
    user =  "user_master"
    role =  "role_master"
    group =  "group_master"
   }
}

You don't have to override all table names, you can choose to override just selected.

3.2 User account configuration

nimble{
  localusers {
    usernames {
      minlength = 4
      validregex = '[a-zA-Z0-9]*' //regex that should be used for validating username
   }
   provision { active = false } //whether new user accoutn should be enabled or disabled after registration
   registration { enabled = true } //Allow new users to register or now
  }
}

3.3 Password requirements

nimble{
  passwords {
    mustcontain {
      lowercase = true
      uppercase = true
      numbers = true
      symbols = true
    }
    minlength = 8
  }
}

It can be overridden in NimbleConfig.groovy

3.4 Email Settings

nimble {
  messaging {
    enabled = true
    registration { subject = "Your new account is ready!" }
    passwordreset { subject = "Your password has been reset" }
    changeemail { subject = "Your email address has been changed" }
  }
}

Nimble depends on Grails for sending mails. You must configure mail plugin properly if you enable messaging in nimble.

3.5 UI Layout

nimble {
  layout {
    application = 'app' 
    administration = 'admin' //layout used by nimble administration portal.
  }
}

4 Customizing Nimble

Overriding layout

Instead of overriding you may want to configure layout names in NimbleConfig.groovy

Overriding styles and Javascript

See NimblePluginResources.groovy to find out resource bundles.

Modifying Nimble side menu

Email templates

5 Leveraging Nimble in your application

5.1 Access control

Access control in host applications is verified in one of two ways:

1. By the host application making a direct call to subject.isPermitted(), subject.hasAllRoles() or subject.hasRole()
2. By a grails filter invoking accessControl closure.

5.1.1 Enforcing access control using filters

The following example shows the usage of the accessControl closure in filters.

Securing controller actions that require an authenticated user.

secure(controller:"product", action:"edit") {
	  before = {
	  	accessControl {
	  		true
	  	}
	  }
	}

Securing controllers/actions that require a specific role or permission

secure(controller:"product", action:"delete") {
	  before = {
	  	accessControl {
	  		role("product-admin") || permission("book:delete")
	  	}
	  }
	}

5.1.2 Enforcing access control directly in code

hasRole() - Checking if user has a role.

Subject currentUser = SecurityUtils.subject;
if (currentUser.hasRole("administrator")) {
‏
}

hasAllRoles(Collection<String> roleIdentifiers) - Check if Subject has all of the specified roles.

Subject currentUser = SecurityUtils.subject;
if (currentUser.hasAllRoles(["manager", "supervisor"])) {
‏
}

isPermitted(String permission) - Check if subject has specified permission.

Subject currentUser = SecurityUtils.subject;
if (currentUser.isPermitted("book:delete")) {
‏
}

5.2 Dynamic methods provided by Nimble

getAuthenticatedUser Returns currently logged in user or null if user is not logged in.

def sampleAction() {
	log.debug("current user : $authenticatedUser")
}

getAuthenticatedSubject Returns current subject, or null if user is not logged in. It is same as calling SecurityUtils.getSubject()

5.3 GSP tags provided by Nimble

5.3.1 Authentication and authorization tags

5.3.2 Utility and UI tags