Setup

Dependencies

Runtime Dependencies

Java 14

The Account Manager maven poms are currently keyed to Java 14.

Database

• PostgreSQL 9.4 or later
• Use a dedicated database. Do not intermix this schema with other schemas.

Application Container

• Tomcat 8 or later
• Note: JBoss/WildFly, Liberty, and other JEE container support is not presently maintained. Account Manager will run on these containers, but special consideration is required for the database and bouncycastle libraries, connection pool configuration, and login configuration

Projects

Package and deploy Hemi JavaScript Framework into the same container as Account Manager Service.

• Note: While the library itself can be repackaged/rebuilt, that is not necessary in this case unless changes to the library modules were made. The included pre-built version is sufficient for the subsequent example user interface.

Service Configuration

Database

Configure the database as desired for your environment and anticipated use. Depending on expected use, it is very important to make sure the memory and CPU settings are tuned to accommodate multiple joined queries across large data sets. Otherwise, the performance will suffer.

Required capabilities

• Service account must be able to authenticate to the database
• Service account must be able to create tables, views, extensions and access relations
• Service account does not need to be able to create database roles, create database users, or change database credentials
• To get started, it is simple enough to grant all privileges on the database to the service user. For example:
  • grant all privileges on database devdb to devuser;
  • A detailed map of the specific entitlements needed by the service account aren't provided at the moment.

Default Configuration

• Database name: devdb
• Service account: devuser

Extensions

The following extension needs to be created on the database as a super user.

CREATE EXTENSION IF NOT EXISTS "uuid-ossp";

Container

JAAS Configuration

Add a jaas.conf configuration file to the CATALINA_HOME/conf with the following contents:

AccountManagerService {

org.cote.jaas.AM5LoginModule required debug=true;

};

AccountManagerService is defined in AccountManagerService/src/main/webapp/META-INF/context.xml

Add an entry to the setEnv.bat or setEnv.sh to include a parameter to the jaas.conf file:

-Djava.security.auth.login.config="%CATALINA_HOME%/conf/jaas.conf"

Service Application Configuration

Update AccountManagerService/src/main/webapp/META-INF/context.xml and adjust the database connection pool settings, database name, and service account name as needed.

Service Application Dependencies

Deploy the HemiEngine web application to the container. This is the default web framework used by the example AccountManagerService interface.

Console and Test Properties

Update the database connection settings in the following properties for use with the console application (required for initial setup) and integration tests.

• Accelerant/src/test/resources/resource.properties
• AccountManagerConsole/src/main/resources/resource.properties
• AccountManagerDataAccess/src/test/resources/resource.properties

Build

AccountManager uses maven for builds. A parent pom is provided to build and install or package everything, but for the initial build and completing preparation steps it may be helpful to build each library independently.

First Time Preparation

Schema defined by AccountManagerObjects and Propellant uses the jaxb2-primitive-fixer-plugin as part of the build and it's necessary to add this dependency to the maven repository. Use the provided example script, AccountManagerObjects/src/lib/installToMaven.sh as a guide to add the jaxb2-primitive-fixer-plugin-1.0.0-SNAPSHOT.jar dependency.

Build and Install

Run mvn clean install for the following, in the following order:

• AccountManagerObjects
  • Contains the core AccountManager object model
• AccountManagerUtil
  • Contains common utility, cryptographic, and non-persistent factories. Note: Cryptography is largely handled by bouncycastle and openssl. No custom cryptography implementations are provided.
• AccountManagerDataAccess
  • Contains core data-access factories and common service classes.
• Propellant
  • Contains the extension community object model.
• Accelerant
  • Contains the community data-access factories and extensions service classes.

Run mvn clean package for the following. Install is desired for your environment and deployment methodolodgy.

• AccountManagerConsole
  • Contains the console application used to configure the database schema, populate default organizations, and add initial users.
• AccountManagerService
  • Basic web interface and REST service end points.

First Time Configuration

• Open a shell to AccountManagerConsole/target (packaged in the previous step).
• Run java -jar AccountManagerConsole.jar -testConnection to verify the connection settings in AccountManagerConsole/src/main/resources/resource.properties.
• Run the following command to configure the database. WARNING: This will erase all tables in the database. The first invocation is a test. The second invocation adds the -confirm flag to execute the changes.
  • Pre-Check: Extension created and privileges granted to the service account? If not, check the database configuration section.
  • Anticipated error: The following error will initially appear when the schema has not yet been loaded. This is expected. ERROR: relation "organizations" does not exist
  • java -jar AccountManagerConsole.jar -setup -rootPassword password -schema "{git}/AccountManager/db/postgres/AM6_PG9_Schema.sql" -rocketSchema "{git}/AccountManager/db/postgres/Rocket_PG9_Schema.sql"
  • java -jar AccountManagerConsole.jar -setup -rootPassword password -schema "{git}/AccountManager/db/postgres/AM6_PG9_Schema.sql" -rocketSchema "{git}/AccountManager/db/postgres/Rocket_PG9_Schema.sql" -confirm
• OPTIONAL: Use the tearDown scripts as an example to flatten the database and populate it with some initial users and test organizations, such as /FirstContact.
  • Change the administrative and user passwords as preferable.
• Notes about initial setup
  • The initial setup creates six organizations. Each organization is logically separate, so there is a fair amount of repetitive churn in the setup log. This is due to each organization being configured with its own set of permissions, roles, and default users. There are about a thousand initial objects created.
  • The somewhat slow Warming up Factories step is a schema-inspection step at the factory level, used primarily to expedite object-to-query translation.

AccountManagerService Configuration

Complete the following steps to deploy the AccountManagerService application.

• Confirm database settings.
  • If the database configuration has not already been made to AccountManagerService/src/main/webapp/META-INF/context.xml, do so now.
• Package AccountManagerService ** mvn clean package
• Copy target/AccountManagerService.war to CATALINA_HOME/webapps
  • Alternately, import the projects into your preferred IDE and deploy from there. If using an IDE, remember to include the jaas.conf parameter in the startup arguments.
• Test the web application:
  • Use a web browser to access https://localhost:8080/AccountManagerService
    • Note, SSL configuration guidance is not included here.
    • Also note: Previous versions included specific configuration to block non-SSL authentication attempts. This has been removed since this should be up to the container configuration anyway.
  • If the page loads, and the blue toolbar is visible, then proceed to login. Otherwise, double check the configuration.
  • If the example password of password was used, click the 'Login Admin' button. Alternately, click 'Login' and complete the following fields. Note the user name is prefaced with the organization path.
    • User name: /Development/Admin
    • Password: {password}
• Test the example service scripts (requires bash client; Windows users can use the linux subsystem if desired):
  • Use a console to navigate to AccountManagerConsole/shell
  • Enter the following to test service connectivity:
    • ./auth.sh /Development Admin password peforms an authentication to obtain an access token (proper OAuth behavior is lacking).
      • Verify a token was received.
    • ./searchGroup.sh /Development Admin "~" performs a search for the Admin user's Home Directory (within Account Manager, not on an actual file system), using the token obtained in the previous step.
      • Verify the AccountManager GroupType object was retrieved.
    • ./clearLocalAuthorizationCache.sh removes the locally cached authentication tokens.