Quick Start Guide - Start EJBCA Container with Client Certificate Authenticated Access
Learn how to start an EJBCA Community Docker container with client certificate authenticated access.
In this guide, you will learn to:
- Pull EJBCA Community container
- Start EJBCA Community container
- Generate administrator certificate
- Import certificate into browser
- Access EJBCA CA UI
The EJBCA Community container is started as an ephemeral instance which means that when you stop the container, it will automatically be removed and all data will be destroyed. This setup is suitable for testing EJBCA or for evaluating added functionality in an updated version. For information on running the container with more production-like settings with persistent data, refer to EJBCA on Docker Hub.
This guide covers how to quickly get an instance of EJBCA up and running, primarily for testing or evaluation purposes. For detailed instructions on how to install a production Certificate Authority (CA), see the EJBCA Installation guide.
Before you begin, you need Docker running in the background. To download and install, refer to docker.com.
Since this build is based on a self-contained Docker image, build tools such as Apache ANT or an application server such as Wildfly are not needed.
Step 1 - Pull EJBCA Community container
The EJBCA Community Docker container is available on Docker Hub and can be pulled straight from the command line using the docker tool.
To download and unpack the latest EJBCA Community container image from Docker Hub, use the following command:
$ sudo docker pull keyfactor/ejbca-ceCODE
Step 2 - Start EJBCA Community container
Start the EJBCA Community container as an ephemeral instance, suitable for testing or evaluation purposes:
Start the container with the container hostname set to "localhost":
$ docker run -it --rm -p 80:8080 -p 443:8443 -h localhost -e TLS_SETUP_ENABLED="true" keyfactor/ejbca-ceCODE
The container starts running with "localhost" as the hostname, but feel free to use any substitute.
- The end of the output is similar to the following, displaying the URL, username and password to use to enroll for the initial SuperAdmin client certificate:
EJBCA is now up and running and has generated a Management CA (used to manage internal PKI in EJBCA) as well as an initial super administrator with full rights.
Step 3 - Generate administrator certificate
To access the EJBCA CA UI, the SuperAdmin credentials need to be retrieved from the server and installed in your browser. We recommend using Mozilla Firefox as it has self-enrollment capabilities and its own keystore separate from the operating system.
The P12 (PKCS#12 file) referred to in the console output above is a key pair that will be generated by the EJBCA server when accessing the provided URL. The P12 format contains the private key, a certificate signed by the Management CA containing the public key, and is encrypted and password protected. It is with these credentials you will be able to generate additional administrators and users, CAs, and profiles, and therefore you mustn't lose these credentials.
To generate the super admin credentials:
- To generate the P12, copy the URL from the console output and paste it into your browser.
- A browser warning is shown as you have not added the Management CA to the list of trusted roots in your certificate store (nor will you need to for this example). Accept this warning by clicking Advanced and then clicking through the warning.
- On the EJBCA Public Web Keystore Enrollment page, enter the username "superadmin" (case sensitive) and the password from the console output and click OK.
On the Token Certificate Enrollment page, select a key algorithm and length in the Key specification list, for example RSA 2048 bits, and click Enroll to generate a file named superadmin.p12 and download the file.
Step 4 - Import certificate into browser
To access the EJBCA CA UI, import the downloaded SuperAdmin certificate into your web browser.
The procedure for importing a certificate may vary. This example describes how to import a certificate to Mozilla Firefox.
To import the certificate in Mozilla Firefox:
- On the Firefox menu, select Preferences.
- Click Privacy & Security.
- In the Security section, click View Certificates.
- On the Your Certificates tab, select Import.
- Browse to the downloaded P12 keystore (
superadmin.p12file) to import and select the file.
- Enter the password provided in the console output, and click Sign in.
- On the Mozilla Firefox tab Your Certificates, verify that the certificate was imported, and then click OK.
Step 5 - Access EJBCA CA UI
Next, point your browser to https://localhost/ejbca/adminweb/ to access EJBCA using the imported certificate.
EJBCA CA UI opens displaying the administration page.
In this guide, you learned how to start an EJBCA Docker container with client certificate authenticated access and download and install the administrator certificate to access EJBCA.
To learn how to create basic profiles and issue a client authentication certificate in EJBCA, you can follow the Quick Start Guide - Issue Client Authentication Certificate using EJBCA.
To find out more about EJBCA use cases, see Solution Areas.
Related Quick Start Guides