1. Introduction

GR8 CRM is a set of Grails Web Application Framework plugins that makes it easy to develop web applications with CRM functionality.

You can find more information about GR8 CRM on the main documentation site http://gr8crm.github.io.

1.1. Customer relationship management

Customer relationship management (CRM) is a system for managing a company’s interactions with current and future customers. It involves using technology to organize, automate and synchronize sales, marketing, customer service, and technical support. Wikipedia

The GR8 CRM "Ecosystem" currently contains over 40 Grails plugins. For a complete list of plugins see http://gr8crm.github.io.

Each GR8 CRM plugin defines a Bounded Context that focus on one specific domain, for example contact, project or document.

2. CRM Security Plugin

The crm-security plugin is a mandatory plugin in GR8 CRM, it manages basic application security like users, roles and permissions. However the plugin does not contain a concrete security implementation. It’s an abstract security implementation with generic features. Concrete implementations exists in the form of sub-plugins. One such sub-plugin is crm-security-shiro that implements application security using the Apache Shiro web security framework.

3. Security Design

All GR8 CRM applications use the crm-security plugin and thus get four common elements that are important objects in a GR8 CRM application (account, tenant, role and user).

3.1. Account

The account it the top-level object in GR8 CRM security object hierarchy. In a billing scenario the account is usually the invoice target and contains the invoice address and other billing information. Even if you are not running in a multi-tenant business environment an account object must exist. In the simplest setup a CRM system contains one user, one account and one tenant.

3.2. Tenant

A tenant can be viewed as a separate database but is technically just an identifier. All user-registered information in a GR8 CRM application is tied to a tenant via a tenantId property.

3.3. Role

Each tenant can contain a unique set of roles that users can have. Common roles are admin, user and guest.

3.4. User

A user is connected to tenants through roles. For example a user can have the admin role in one tenant and the user role on another tenant. A user is identified by it’s unique username.

4. Initialize Security Objects

To create user-data in a GR8 CRM application you must first create a user, an account and a tenant. This can easily be done in BootStrap.groovy with some help from crmAccountService and crmSecurityService.

Bootstrap.groovy
class BootStrap {

    def crmAccountService
    def crmSecurityService

    def init = { servletContext ->

        if (!crmSecurityService.getUser("admin")) {

            // Add a permission that allow everything.
            crmSecurityService.addPermissionAlias("permission.all", ["*:*"])

            // Create an admin user.
            def admin = crmSecurityService.createUser(username: "admin", password: "admin",
                    email: "firstname.lastname@email.com", name: "Administrator", enabled: true)

            // Create an account and a tenant. Then make sure the admin user has unlimited permissions in that tenant.
            crmSecurityService.runAs(admin.username) {
                def account = crmAccountService.createAccount(name: "My account", status: "active")
                def tenant = crmSecurityService.createTenant(account, "My first tenant", [locale: Locale.ENGLISH])
                crmSecurityService.runAs(admin.username, tenant.id) {
                    crmSecurityService.addPermissionToUser("permission.all")

                    // Statements inside this block executes as user "admin" in the context of "My first tenant".
                }
            }
        }
    }

    def destroy = {
    }
}

5. CrmAccountService

The account service is used to manage a GR8 CRM account. The account is the top-level object in the security object hierarchy.

5.1. createAccount

createAccount(Map params, Map features)

The following properties are available on CrmAccount and can be set with the params parameter:

Property Type Description

name

String

Account name (mandatory)

email

String

Email address to the account owner

telephone

String

Phone number to the account owner

address1

String

Invoice address

address2

String

Invoice address

address3

String

Invoice address

postalCode

String

Invoice address

city

String

Invoice address

region

String

Invoice address

countryCode

String

Invoice address

ssn

String

Business identification number (if relevant)

reference

String

Name of account owner or invoice reference

The features parameter is used to specify what features are available in the account. Feature names are application specific but the following three features and reserved for the security system.

Feature Value Description

crmAdmin

Integer

Max number of administrators in the account

crmUser

Integer

Max number of users in the account

crmGuest

Integer

Max number of guests in the account

To create an account that allow 2 administrators, 10 users and 50 guests you create the account with the following parameters:

CreateAccount.groovy
def account = crmAccountService.createAccount(
    [name: "Corporate Account", status: "active"],
    [crmAdmin: 2, crmUser: 10, crmGuest: 50]
)

Trying to add more than 2 users with the admin role to the account above will result in CrmException with error code admin.role.max.exceeded.

5.2. getAccounts

List<CrmAccount> getAccounts(String)

Return all accounts owned by a specific user.

5.3. getCurrentAccount

CrmAccount getCurrentAccount()

Returns the current active account. The implementation finds the current tenant and then returns the account that the current tenant belongs to.

6. CrmSecurityService

This service is the most frequently used service in the GR8 CRM security system. This service focuses on users, roles and permissions. Each tenant has its own set of roles and permissions. This means that one user instance can have different permissions in different tenants. For example user linda can have the admin role in tenant Marketing and guest role in tenant R&D.

6.1. createUser

CrmUser createUser(Map)

Create a new user instance.

Property Type Description

username

String

Short name (mandatory)

email

String

Email (mandatory)

name

String

Full name (mandatory)

company

String

Company name

telephone

String

Telephone

timezone

String

Default time zone

postalCode

String

Postal address

countryCode

String

Country code

campaign

String

Sign up campaign

status

Integer

(ACTIVE = 1, BLOCKED = -1)

6.2. addUserRole

CrmUserRole addUserRole(CrmUser user, String rolename, Date expires, Long tenant)

Assigns a role to a user. The rolename parameter is usually admin, user or guest. If the role is time-restricted you can specify an expires date. After that date the role will no longer be active.

7. Changes

Grails 2.4.x branch
2.4.3

Fix problem related to deleting user roles when deleting tenant. Added CrmSecurityService#validatePassword().

2.4.2

Added CrmThemeTagLib with theme and hasTheme tags

2.4.1

Fixed bug where permissions from "theme features" was installed in tenants not using the theme.

2.4.0

First version compatible with Grails 2.4.4.

Grails 2.2.x branch
2.0.4

Added CrmThemeTagLib with theme and hasTheme tags

2.0.3

Fixed bug where permissions from "theme features" was installed in tenants not using the theme.

2.0.2

The list() method in CrmUserService is now compatible with the selection plugin

2.0.1

The event crm.tenantCreated is now sent synchronously.

2.0.0

First public release.

8. License

This plugin is licensed with Apache License version 2.0

9. Source Code

The source code for this plugin is available at https://github.com/goeh/grails-crm-security

10. Contributing

Please report issues or suggestions.

Want to improve the plugin: Fork the repository and send a pull request.