coreoz/plume-admin

A simple administration backend based on Plume

Plume Admin

Plume Admin is based on Plume Framework, it provides Jersey web services to build an administration area.

If you are looking for a JavaScript frontened that uses these web-services, check out the Plume Admin UI for React.

Looking for a demo? Check out the Plume Demo project.

Installation

1. Maven dependency:

<dependency>
    <groupId>com.coreoz</groupId>
    <artifactId>plume-admin-ws</artifactId>
</dependency>

2. Guice module: install(new GuiceAdminWsWithDefaultsModule())
3. Jersey web-services: packages("com.coreoz.plume.admin.webservices")
4. Jersey admin security: register(AdminSecurityFeature.class)
5. Jersey security: If the access control mechanism is setup, you need to add the RestrictToAdmin.class access control annotation: config.register(RequireExplicitAccessControlFeature.accessControlAnnotations(PublicApi.class, RestrictToAdmin.class));
6. Generate a JWT secret key and register it in your configuration: admin.jwt-secret = "long_generated_password_to_secure_jwt_tokens"
7. For non-https environments (ie localhost for dev), set the configuration value: admin.session.fingerprint-cookie-https-only = false (this configuration value should be set to true in HTTPS environments like production)
8. SQL, see setup files
9. Install a JS frontend like Plume Admin UI for React

Current user access

To fetch the current user in an administration web-service, this Jersey binder must be installed in the Jersey configuration class:

register(new AbstractBinder() {
	@Override
	protected void configure() {
		bindFactory(WebSessionAdminFactory.class).to(WebSessionPermission.class).in(RequestScoped.class);
		bindFactory(WebSessionAdminFactory.class).to(WebSessionAdmin.class).in(RequestScoped.class);
	}
});

Admin security

To use this module without Admin Web-services, you may want to provide implementations of AdminPermissionService, WebSessionSigner, and JwtSessionSigner. As an example, here is what is defined in the Admin Web-services Guice configuration:

bind(AdminPermissionService.class).to(AdminPermissionServiceBasic.class);
bind(WebSessionSigner.class).toProvider(JwtSessionSignerProvider.class);
bind(JwtSessionSigner.class).toProvider(JwtSessionSignerProvider.class);

More documentation about JWT and how to secure project API are available in the Plume Admin Security module.

Configuration

To generate JWT secret, LastPass generator can be used with a password length of about 50 characters.

# this key should be changed in production if test users cannot be trusted
admin.jwt-secret = "long_generated_password_to_secure_jwt_tokens"

# default values
# the duration after which a session token expires
admin.session.expire-duration = 1 minute
# the duration after which the client should refresh the session token (must be lower than the expire duration)
admin.session.refresh-duration = 20 seconds
# the duration after which the client should stop refreshing the session token (must be greater than the expire duration)  
admin.session.inactive-duration = 15 minutes
admin.login.max-attempts = 5
admin.login.blocked-duration = 30 seconds
admin.passwords.min-length = 0

# if a secure cookie is emitted alongside the JWT token to prevent XSS attacks
# see https://cheatsheetseries.owasp.org/cheatsheets/JSON_Web_Token_Cheat_Sheet_for_Java.html for details
admin.session.use-fingerprint-cookie = true
# on localhost when using HTTP, this option must be set to false => this should be set to true at least on production
admin.session.fingerprint-cookie-https-only = true

# enable to ensure that users passwords are long enough
admin.passwords.min-length = 0

WS System module

To set up the module, install the Plume Schedule module in ApplicationModule: install(new GuiceSchedulerModule());

Password hashing

Plume Admin already handles passwords hashing with BCrypt. It is used in the plm_user table.

However, you can rely on the code provided in Plume Admin to implement user authentication and password hashing in your own database tables. To do that, you will want to implement an HashService. One is already provided:

bind(HashService.class).to(BCryptHashService.class);

Note that this service is already bound if you are already using GuiceAdminWsModule or GuiceAdminWsWithDefaultsModule;

You'll use it to hash the password:

userDB.setPassword(hashService.hashPassword(userBean.getPassword()));

and to check if the provided password match the one registered:

if (hashService.checkPassword(loginBean.getPassword(), userDB.getPassword())) {
  // Password is correct
}

HTTP API Log module

To set up the module:

• Maven:

<dependency>
  <groupId>com.coreoz</groupId>
  <artifactId>plume-admin-api-log</artifactId>
</dependency>

• Install the Plume Schedule module in ApplicationModule: install(new GuiceSchedulerModule());
• Scheduler:

LogApiScheduledJobs logApiScheduledJobs; // from dependency injection
logApiScheduledJobs.scheduleJobs();

• See SQL files

Advanced configuration is detailed in the Log API module.

Upgrade instructions

See the releases notes to see the upgrade instructions.

plume-admin's Issues

Review authentication/authorization architecture

The current authentication architecture in the module plume-admin-security is tightly coupled to Plume admin. This makes implementing an authentication system outside Plume admin difficult.
Moreover, the "authentication SDK" is difficult to use:

• It seems tightly coupled with Jersey
• The class SessionWs is present in the module plume-admin-ws whereas a lot of code in this class must be reused to implement a custom authentication
• The code is not very modular: it is often required to override multiple classes to implement a custom authentication, like SessionWs, and it is complicated for the same project to provide multiple authentication system

Ideally:

• All then authentication code should be in a plume-authentication and maybe with a plume-authentication-jwt module
• plume-admin-security would only contain code to customize plume-security for Plume Admin (and maybe renamed plume-admin-authentication)
• A full documentation would be written before any development to make sure that it would be easy to use
• A sample would be implemented in https://github.com/Coreoz/Plume-showcase where we would see how to implement a custom authentication system next to the Plume admin authentication system

JWT cookie fingerprint name should be customizable

Currently the cookie name is defined in JerseySessionParser.FINGERPRINT_COOKIE_NAME. This cookie name should be customizable in cases:

• Where the same backend handles multiple authentication spaces (like a front-office with authentication and a back-office)
• Where another application on the same domain uses already the same name