Security

Hot framework supports security out of the box. You can easily secure your entire app or just some of your REST endpoints.

Hot allows you to add authentication and authorisation based on multiple back ends technologies like:

• Database
• LDAP
• OAuth (Twitter)
• OAuth2 (Facebook, Google)

The nice thing is that you can secure your app the same way independently of the underlying login back end.

Adding security to your project

In order to secure your app, simply use the hot CLI.

Database back end

The Database back end use a set of tables previously created in one of the datasources defined in your project.

The following command will be used to add the DB based security layer to your app:

$> hot auth-db -n <datasource_name> [-u <username>] [-p <password>] [-roles <coma seperated list of roles>]

-n,--name <arg>       Name of the datasource
-p,--password <arg>   Default password (associated to username) to insert
                       in the DB (optional)
-roles <arg>          List of roles associatted to username (optional)
-u,--username <arg>   Default username to insert in the DB (optional)

The datasource must be previously defined in your project. You can optionally create a default user via the username, password and roles parameters.

The users and authorities tables must be created before adding the authentication back end. They will contain users infos and associated roles.

H2 Schema

CREATE TABLE users(
	username varchar_ignorecase(50) NOT NULL PRIMARY KEY,
	password varchar_ignorecase(50) NOT NULL,
	enabled boolean not null);

CREATE TABLE authorities (
	username varchar_ignorecase(50) NOT NULL,
	authority varchar_ignorecase(50) NOT NULL,
	CONSTRAINT fk_authorities_users foreign key(username) references users(username));
	CREATE UNIQUE INDEX ix_auth_username on authorities (username,authority);

Mysql Schema

CREATE TABLE IF NOT EXISTS users(
	username varchar(50) NOT NULL PRIMARY KEY,
	password varchar(50) NOT NULL,
	enabled boolean not null) engine = InnoDb;

CREATE TABLE IF NOT EXISTS authorities (
	username varchar(50) NOT NULL,
	authority varchar(50) NOT NULL,
	foreign key (username) references users(username)) engine = InnoDb;
	
CREATE UNIQUE INDEX ix_auth_username on authorities (username,authority);

Oracle Schema

create table users(
    username varchar2(50) not null primary key,
    password varchar2(50) not null,
    enabled number(1) not null
);

create table authorities (
    username varchar2(50) not null,
    authority varchar2(50) not null,
    constraint fk_authorities_users foreign key(username) references users(username)
);

LDAP backend

Le LDAP backend use a LDAP server to handle authentication and autorisations.

The following command will be used to add the LDAP based security layer to your app:

$> hot auth-ldap -url <ldap url> [ -udp <user-dn-patterns> |  -usb <user-search-base> -usf <user-search-filter> ] [ -gsb <group-search-base> -gsf <group-search-filter> ] 

-gsb,--group-search-base <arg>     search base for group searches
                                   (optional)
-gsf,--group-search-filter <arg>   the LDAP filter to search for groups
                                   (optional)
-udp,--user-dn-patterns <arg>      the LDAP patterns for finding the
                                   usernames (optional)
-url <arg>                         ldap url in the form of
                                   'ldap://example.com:389/dc=example,dc=
                                   com'
-usb,--user-search-base <arg>      search base for user searches
                                   (optional)
-usf,--user-search-filter <arg>    the LDAP filter used to search for
                                   users (optional)

Facebook Login back end

You can add a OAuth2 based Facebook login authentication back end. Your app must be registered on Facebook and you must have received a App Id/App Secret pair.

The following command will be used to add the Facebook login based security layer to your app:

$> hot auth-facebook -id <App ID> -sec <App Secret>

-id,--app-id <arg>        Facebook provided application id
-sec,--app-secret <arg>   Facebook provided application secret

App ID and App Secret must be previously created from the Facebook dev console.

The redirect URI must be http(s):<hostname>[:<port>]/auth/facebook

Now simply put a login button in the login page of your app:

<a href="auth/facebook">Connect with Facebook</a>

Twitter authentication back end

You can add a OAuth based Twitter authentication back end. Your app must be registered on Twitter and you must have received a consumer key/password pair.

The following command will be used to add the Twitter login based security layer to your app:

$> hot auth-twitter -ck <consumer key> -cp <consumer password>

-ck,--consumer-key <arg>        Twitter provided OAuth consumer key
-cp,--consumer-password <arg>   Twitter provided OAuth consumer password

Consumer key and consumer password must be previously created from the Twitter app console

The redirect URI must be http(s):[:]/auth/twitter

Now simply put a login button in the login page of your app:

<a href="auth/twitter">Connect with twitter</a>

Google authentication back end

You can add a OAuth2 based Google authentication back end. Your app must be registered on Google and you must have received a client id/secret pair.

The following command will be used to add the Google login based security layer to your app:

$> hot auth-google -id <client ID> -sec <client secret>

-id,--client-id <arg>        The client ID you obtained from the Google
                             Developers Console
-sec,--client-secret <arg>   The client secret you obtained from the
                             Developers Console

Client ID and client secret must be previously created from the Google API console.

The redirect URI must be http(s):<hostname>[:<port>]/auth/google

Now simply put a login button in the login page of your app:

<a href="auth/google">Connect with Google</a>

Removing security of your project

Database backend

$> hot auth-db -r

LDAP backend

$> hot auth-ldap -r

Facebook Login backend

$> hot auth-facebook -r

Twitter authentication backend

$> hot auth-twitter -r

Google authentication backend

$> hot auth-google -r

Securing static assets

In order to secure access to static resources located in the www folder, simply put a .secure empty file in each directory you wish to secure.

Access to these resources through a web browser will redirect the user to either a login.html page located in www if it exists or to a generated login form.

Securing REST endpoints

In order to secure your REST endpoints, simply call the auth() method from the get/post/put/delete methods of the rest object. Without argument, the endpoint will require the user to be authenticated (either using Form, Basic or OAuth authentication methods).

You can optionally pass a list of roles a user need to have in order to access a endpoint. Hot automatically retrieves roles from the database or from the LDAP depending of the configured back end. In OAuth scenario, no role is associated to the user.

Groovy example

rest.post("/article").auth('EDITOR', 'PLANNER', 'SYSTEM').then { request ->
  ...
}

In this example, in order to access the post("/article") endpoint, the user must be authenticated and have the three mentioned roles.

Accessing user informations

User informations are retrievable through the user attribute from the request object when authenticated users access REST endpoints.

Available informations depends of the authentication back end. Database based authentication provides name, password and roles attributes. LDAP based backend provides the roles mentioned above plus the dn attribute. OAuth/OAuth2 auth backend provides a bit more informations. The following attributes are provided:

• name - The name of the user.
• accessToken - The OAuth access token allowing various social API calls.
• picture - A link to the user profile picture
• link - Link to the user profile on the OAuth platform (Facebook profile, Twitter profile,...)
• id - ID of the user on the OAUth platform.
• provider - OAuth provider (Facebook, Twitter or Google)
• expiresIn - Expiration timestamp for the access token.

The following snippet expose a REST endpoint returning user informations.

rest.post("/userInfos").auth().then(function(request){
  return {
     'name':request.user.name,
     'picture':request.user.picture,
     'link':request.user.link,
     'id':request.user.id,
     'provider':request.user.provider
   }
})