bookmark

A showcase project demonstrates:

• using act-aaa for authentication/authorisation
• an integrated development environment for API management and automate testing

Getting start with bookmark project

The requirement of the bookmark project has been defined in github. It is recommend the new comer to read through the requirements which links to the implementation and automate testing of the project.

The first time user can load the project into IDE (Intellij IDEA preferred) and view the structure of the project. Once the project is loaded into IDE, the user can run the project by run the main entry class: demo.AppEntry:

Start the app

There two ways to start the application

1. Run app in your console
2. Run app in IDE directly

View API document

Once the app has been started (in dev mode), the developer can get access to the API document by visiting ~/api:

Note API document is generated automatically by ActFramework. Developer just need to put the right information in Javadoc in the source code. The corresponding Javadoc for the endpoint shown in the above screenshot is:

As shown above, ActFramework automatically generates sample data for endpoints.

Automate testing

The bookmark project has been created with full automate testing scenarios which covers all stories defined, including the normal and exceptional cases. The testing scenarios are defined in src/main/resources/test/scenarios dir:

When app has been started in dev mode, the developer can run automate test by going to ~/test:

Understanding aaa

This project use act-aaa-plugin to provide authentication and authorisation support.

Note, by default act-aaa-plugin reads resources/acl.yaml file to get permissions, privileges and role definitions. There is yet another approach that defines the permissions/privileges and roles definition into database . Checkout the aaa-obj-in-db branch to see how to use database to store the AAA objects.

Authentication

Once act-aaa has been added into the project pom dependencies, all endpoints are by default require authentication, meaning if a user that hasn't logged in request to an endpoint, a 401 response will be send back.

In order to mark an endpoint as public, i.e. no authentication required, it can add NoAuthentication annotation to the controller class or request handler method, e.g.

package demo.services;

import act.controller.Controller;
import act.controller.annotation.UrlContext;
import org.osgl.aaa.NoAuthentication;

@NoAuthentication
@UrlContext("/api/v1")
public abstract class PublicServiceBase extends Controller.Util {
}

The above code define a base class for public controllers, all request handler method defined in the sub class of PublicServiceBase will not require authentication

Authorisation

Whenever a resource needs authorisation protection, the developer can use AAA.requirePermission(...) APIs to declare an authorisation requirement to protect the resource, e.g.

@PostAction
@PropertySpec("id")
public Bookmark create(@Valid Bookmark bookmark) {
    AAA.requirePermission(AAAHelper.PERM_CREATE_BOOKMARK);
    bookmark.owner = me.email;
    return bookmarkDao.save(bookmark);
}

The above code declare permission AAAHelper.PERM_CREATE_BOOKMARK is required to access create bookmark endpoint.

Dynamic permission

It is not unusual that a resource protected by authorisation needs to do further check besides permission check. e.g.

@PutAction("{bookmark}")
public void update(@DbBind @NotNull Bookmark bookmark, @NotBlank String description) {
    AAA.requirePermission(bookmark, AAAHelper.PERM_EDIT_MY_BOOKMARK);
    bookmark.description = description;
    bookmarkDao.save(bookmark);
}

The above code declare permission PERM_EDIT_MY_BOOKMARK is required to edit a bookmark, however, it doesn't make sense to let user A to edit a bookmark created by user B, thus we have declared PERM_EDIT_MY_BOOKMARK permission in AAAHelper.java as dynamic permission, meaning aaa framework needs to further check if the resource been protected (the bookmark here) is owned by (linked to) the current user. The link between bookmark and user is implemented in Bookmark class:

@Entity(name = "bookmark")
public class Bookmark implements UserLinked {
    ...
    @Override
    public boolean isLinkedTo(Principal principal) {
        return S.eq(principal.getName(), owner);
    }
    ...
}

About Database

This demo application use act-hibernate as the database plugin to provide database access support.

There is no database configuration provided with the Demo app, ActFramework load the only database plugin introduced by maven dependency. In terms of database, the framework will use built-in h2 database engine to create a file database named test in the project folder.

However a db.properties file has been provided with a bunch of commonly used database configurations (all commented) for developer's reference.

Summary

This demo application shows

• How to use act-aaa to for authentication/authorisation
• How to leverage /~/api endpoint for API document generation
• How to leverage /~/test endpoint for test automation