The following describes how to install EJBCA on the most well supported application server JBoss AS. EJBCA can also be run on Glassfish and Weblogic, but your mileage may vary (see details below).

For information on quickly getting started with EJBCA, see Quick Start Guides.

Prerequisites

EJBCA uses strong crypto and keystore passwords longer than 7 characters. This requires you to install the Unlimited Strength Jurisdiction Policy Files for JDK, available for download together with the JDK download at the Oracle website. The text Using exportable cryptography will be shown on the first page in the Admin GUI if you fail to install the package. For more information, refer to the Oracle documentation on the JCE.

Needed to be built and run are:

JDK 7 or 8, OpenJDK or Oracle JDK. If available OpenJDK is recommended.
Only if using OracleJDK - Java Cryptography Extension (JCE) Unlimited Strength Jurisdiction Policy Files for your JDK.
JBoss Application Server 7.1.x or later or JBoss EAP 6 or later. WildFly 9 or later.
- The currently recommended Application Servers are WildFly 10, or JBoss EAP 7 (download WildFly or download JBoss EAP).
Apache Ant 1.8 or later to build (available as standard package in Linux, or download). Note that javascript support may be needed in ant for some components.

Windows/Unix: When we describe command line commands below we use Unix notation, e.g. ejbca.sh for the executable command files. The same command files are available for windows as cmd-files, e.g. ejbca.cmd.

If you are unsure what version of EJBCA you are running, type ant ejbcaversion in the EJBCA_HOME directory.

Configure

Configuration Files

The configuration of EJBCA that cannot be configured in the Admin GUI is located in properties files in the conf directory. All properties are documented in sample files and to configure an option you copy the sample file, for example copy conf/ejbca.properties.sample to conf/ejbca.properties and configure conf/ejbca.properties. You should at least familiarize yourself with the options in conf/install.properties, conf/ejbca.properties and conf/cesecore.properties. Most options, except those in install.properties can be changed after installation.

EJBCA Configuration

Copy conf/install.properties.sample to conf/install.properties, conf/ejbca.properties.sample to conf/ejbca.properties and conf/cesecore.properties.sample to conf/cesecore.properties. Customize if needed. The default values work fine for a test installation.

You must configure appserver.home in ejbca.properties to point to your application server directory. You find examples of how to do this in ejbca.properties.sample.

This makes libraries from the application server available to EJBCA during the build.

If you are only testing EJBCA at this stage and is not setting up a production environment, you can skip the rest of this step. There are default configuration options, that should work in a test environment, for everything.

If needed, customize the CA properties in conf/ejbca.properties. For production use you need to do this, don't forget to edit passwords to be secure and secret. Keep conf/ejbca.properties as secret as possible. DO NOT forget the passwords, if you need to re-install the software sometime.
To use a hard ca token from start, change ca.tokentype, ca.tokenpassword and ca.tokenproperties in install.properties. You also need to add the appropriate values to the ca.tokenproperties file for the HSM. Read the HSM documentation for the right values.
To put the initial superadmin certificate on a smartcard, set superadmin.batch=false in web.properties.
Enroll from public web after the installation is complete, as you would with any other smartcard user.
Username is superadmin and password is superadmin.password from web.properties.
If you are deploying on JBoss EAP you probably want to look at the property jboss.config as well, since production may be the default server to start on JBoss EAP (depends on your configuration).

Do the same with other configuration files that you might want to customize. The default values are generally sufficient, and most options are documented in the sample files.

If needed, customize the database in conf/database.properties. Most straightforward is to keep the default values, using the JBoss embedded HSQLDB. For production use you should use a real database instead of the embedded one.

Configure Application Servers

Due to differences between different application servers, configure your application server with certain settings, and EJBCA with server specific settings. For more information, see Application Servers.

Considerations

When everything is prepared, there are a few things to configure before starting your applications and running everything in a production environment.

In a production environment you should use something like the following structure:

Go through the install process creating a ManagementCA.
Use a simple DN. This CA should only be used to issue the administrator certificates, not published in LDAP. If you want to use an HSM for this CA, refer to the documentation in the configuration file conf/ejbca.properties.sample.
Once installed, create all your REAL CAs using the Admin GUI.
Use your preferred certificate profiles etc. These certificates can be published in LDAP. For configuration information, refer to doc/howto/HOWTO-multiplecas.txt.

In a production environment, it is required to use something else than the default Hypersonic database provided with JBoss, for the following reasons:

Hypersonic database is in-memory and will over time consume more memory. If a large number of certificates is issued, it will become an issue after a while.
Hypersonic does not support full SQL, in particular ALTER statements. When a new version of EJBCA is released we cannot create scripts that updates the database if some tables changed. This will complicate upgrades.

For information about installing JDBC drivers for other databases, refer to doc/howto/HOWTO-database.txt in the distribution.

Install on JBoss 7.1.1 or JBoss EAP 6

If deploying on WildFly 10 or JBoss EAP 7, follow the installation instructions in WildFly 10/JBoss EAP 7 to manually configure data sources and web.

The installation must be done with a user with privileges to write to APPSRV_HOME and sub directories. Running the deploy and install commands as described will also configure the application server with data sources and web configuration automatically.

Set the property appserver.home in conf/ejbca.properties to where your JBoss is installed, for example:

appserver.home=/opt/jboss-7.1.1.Final

Also make sure the right java tools (javac/keytool) are available in your system PATH, ie. /usr/local/jdk1.7.0_25/bin.
Open a console (terminal) and start JBoss. You can start JBoss with the normal command standalone.sh (JBoss 7/EAP 6/WildFly) from APPSRV_HOME/bin. You should see JBoss picking up everything and deploying the ear without errors.
Open a console and type:

ant deploy

It will compile and build EJBCA and deploy it to JBoss, as well as automatically create data sources and mail service. You will be prompted to enter the value for database.password if it has not already been defined in database.properties.
Type:

ant install

The command will generate all certificates, keys, etc needed to run with an initial CA, and configure TLS in the servlet container to use the generated keystore and truststore files (which are also copied in the process). You will find admin keys in ${ejbca.home}/p12. (do not delete these files!)
The command is only run once, when the CA is first installed. It creates lots of things in the database and cannot be run again (it will give an error if you try).
- tomcat.jks is for the Servlet container (don't bother with it)
- truststore.jks is for the Servlet container (don't bother with it)
- superadmin.p12 should be imported in your browser, that's your administration certificate.
Instead of creating an initial Admin CA and issuing administrator certificates from that, you can install using administrator certificates from an already existing external CA. For more information, see Administrators Issued by External CAs. This would replace step 4-8, but instead require other steps.
Restart JBoss (Ctrl+C if you run JBoss in the foreground in a terminal).
Import the certificate from EJBCA_HOME/p12/superadmin.p12 in your web browser. This is the super administrators certificate used to access the Admin GUI. Other administrators with specific privileges can be created later on. The default password for superadmin.p12 is ejbca and is configured in web.properties.
Go to https://localhost:8443/ejbca/ to access the Admin GUI, or http://localhost:8080/ejbca for the public web pages.
If you create other CAs that you want to add as acceptable CAs in the SSL server configuration, or if you renew the CA certificate, you can install any CA certificate in the SSL server configuration afterwards with the following command:

ant -Dca.name="My CA Name" javatruststore

What this does in the background is that it adds the CA certificate to p12/truststore.jks and copies this file to JBOSS_HOME/server/default/conf/keystore, where the SSL keystores are located.

You must stop and start JBoss after doing this.