PKI Practice: Building a Complete Certificate Service System (openubmc.cn)

1. Introduction

This tutorial provides a hands-on guide based on EJBCA, designed to compliance the CA/RA workflow in a demo environment. It walks through key operational steps including certificate profile creation, end entity profile configuration, approval process activation, and RA certificate issuance and download. This tutorial focuses on practical execution, making it ideal for experiments, proof-of-concept (PoC) setups, or internal demonstrations. Please note that this tutorial does not cover production-level security hardening or compliance requirements.

Objective: Master the core operations of EJBCA and complete the entire process from template configuration to certificate issuance.

2. Terms

• RA: registers end entities and reviews their identities.
• Certificate profile: presets key usages, SANs, and validity periods.

3. Experiment Environment and Prerequisites

• OS: Ubuntu 20.04 Server (installed offline)
• Software to be preset: Docker and docker-compose (apt package)

4. EJBCA Docker Deployment and Persistence

This chapter explains how to deploy the EJBCA certificate service using Docker, with a focus on ensuring persistent data storage on a dedicated drive. This setup helps prevent data loss in the event of container or virtual machine restarts. Key topics cover configuring data persistence of the internal database (H2 by default), running containers using docke-compose, and setting up remote access through appropriate configuration parameters.

4.1 Environment Setup and Proxy Configuration

Some EJBCA Docker images (such as keyfactor/ejbca-ce) need to be pulled from the public network. To ensure environment availability, configure the HTTP/HTTPS proxy of Docker Daemon.

Step 1 Configure the systemd proxy.

Docker Daemon runs under the systemd management. You need to add the following configurations to inherit the system proxy.

sudo mkdir -p /etc/systemd/system/docker.service.d
sudo nano /etc/systemd/system/docker.service.d/http-proxy.conf

Content:

[Service]
Environment="HTTP_PROXY=http://192.168.xxx.xxx:7890"
Environment="HTTPS_PROXY=http://192.168.xxx.xxx:7890"
Environment="NO_PROXY=127.0.0.1,localhost,192.168.13.119" // Change the IP address to the host IP address of your virtual machine.

Step 2 Reload and restart Docker.

sudo systemctl daemon-reload
sudo systemctl restart docker
sudo systemctl status docker --no-pager -l

If the output contains Active: active (running), the proxy configuration takes effect.

Step 3 Check whether the proxy has taken effect.

docker info | grep -i proxy

If the following information is displayed, the proxy has taken effect:

HTTP Proxy: http://192.168.xxx.xxx:7890
HTTPS Proxy: http://192.168.xxx.xxx:7890

4.2 Data Persistence Configuration

• Save the H2 database in files, and set the database as follows: jdbc:h2:/mnt/persistent/ejbcadb;DB_CLOSE_DELAY=-1.
• Host mount path: /opt/ejbca-data:/mnt/persistent
• Do not use --rm to start the container.
• Set the host permission: chown -R 10001:10001 /opt/ejbca-data

📌 Note: In a formal environment, it is recommended to use external database, such as PostgreSQL or MySQL, to improve system reliability and disaster recovery capabilities.

Deployment Using Docker Compose

1. Create a directory structure.

mkdir -p /opt/ejbca-compose
cd /opt/ejbca-compose
mkdir -p /opt/ejbca-data
chown -R 10001:10001 /opt/ejbca-data

2. Create and compile docker-compose.yml in the current directory.

version: "3.3" # Use Docker Compose v3.3.

services:
  ejbca: # Define the service ejbca.
    image: keyfactor/ejbca-ce:latest # Use the latest EJBCA image (community-edition) provided by Keyfactor.
    container_name: ejbca # Set the container name to ejbca.
    hostname: myejbca.test.local # Set the internal host name of the container, which affects fields such as CN in the certificate.

    environment: # Set environment variables to configure the EJBCA startup behavior.
      - DATABASE_JDBC_URL=jdbc:h2:/mnt/persistent/ejbcadb;DB_CLOSE_DELAY=-1 # Use the embedded H2 database. The data is stored in the mount directory.
      - TLS_SETUP_ENABLED=true # Enable automatic TLS settings (for HTTPS access).
      - SMTP_DESTINATION=192.168.xx.xx # Set the SMTP email server address (for sending notification emails).
      - SMTP_DESTINATION_PORT=25 # Set SMTP service port. The default value is 25. (Encryption is disabled.)
      - SMTP_FROM=ejbca@example.local # Set the email sender address.
      - SMTP_TLS_ENABLED=false # Do not enable STARTTLS for SMTP.
      - SMTP_SSL_ENABLED=false # Do not enable SSL/TLS encryption for SMTP.

    ports: # Map the container port to the host.
      - "80:8080" # Map the host port 80 to the container port 8080 (HTTP).
      - "443:8443" # Map the host port 443 to the container port 8443 (HTTPS).

    volumes: # Mount the data volume to map the directory in the container to the host for data persistence.
      - /opt/ejbca-data:/mnt/persistent # Mount the /opt/ejbca-data directory on the host to the container to persist data such as the database.

    restart: unless-stopped # If the container exits abnormally, the container is automatically restarted unless you manually stop the container.

3. Start the container service.：

docker-compose up -d
docker-compose logs -f

⚙️ You can use Compose to easily manage configuration versions, facilitating team collaboration and version recovery.

4.4 Remote Access Configuration

1. Set the container's hostname in advance, which affects CN of the TLS certificate.

hostname: myejbca.test.local

4.5 Certificate Trust Management

After downloading the super administrator certificate ·, double-click to import it.

4.6 Login Process Summary

1. Run docker-compose logs -f to search for SuperAdmin URL and one-time password in the container logs.

ejbca    | 2025-08-05 09:11:31,656+0000 INFO  [/opt/keyfactor/bin/start.sh] (process:1) *                                                                                                    *
ejbca    | 2025-08-05 09:11:31,656+0000 INFO  [/opt/keyfactor/bin/start.sh] (process:1) *   URL:      https://myejbca.test.local:443/ejbca/ra/enrollwithusername.xhtml?username=superadmin *
ejbca    | 2025-08-05 09:11:31,656+0000 INFO  [/opt/keyfactor/bin/start.sh] (process:1) *   Password: urAMy0He5c/hHy+DYyDFNy4E                                                               *
ejbca    | 2025-08-05 09:11:31,656+0000 INFO  [/opt/keyfactor/bin/start.sh] (process:1) *                                                                                                    *
ejbca    | 2025-08-05 09:11:31,656+0000 INFO  [/opt/keyfactor/bin/start.sh] (process:1) * Once the P12 is downloaded, use "urAMy0He5c/hHy+DYyDFNy4E" to import it.                           *
ejbca    | 2025-08-05 09:11:31,656+0000 INFO  [/opt/keyfactor/bin/start.sh] (process:1) *                                                                                                    *
ejbca    | 2025-08-05 09:11:31,656+0000 INFO  [/opt/keyfactor/bin/start.sh] (process:1) ******************************************************************************************************

1. Access the URL, enter the password, set the export password, and download the .p12 certificate.
2. Import the certificate and access https://myejbca.test.local/ejbca/adminweb.
3. If the system displays a message indicating that the client certificate is not provided, check whether the certificate is successfully imported, the proxy is disabled, and the domain name is correctly resolved.

✅ So far, the EJBCA deployment, persistence, and management login process is completed.

Important Notes (Must Be Followed)

✅ You must add myejbca.test.local to the hosts file or set up a local DNS server. Otherwise, the browser may fail to resolve the domain name.
✅ The default algorithm for the super administrator certificate is DILITHIUM2, which may vary by version. However, Windows probably cannot recognize DILITHIUM2. To ensure compatibility, it is advised to switch the algorithm to RSA 4096.
✅ No proxy should be enabled. Otherwise, EJBCA may fail to correctly process client certificate authentication.
✅ Ensure that the Windows/macOS/Linux certificate is correctly imported to avoid the "No client certificate was presented" error.
✅ It is recommended that you use the Chrome browser in Incognito mode for the first time to avoid the "No client certificate was presented" error caused by cache problems.

5. Initial CA Creation and Certificate Level Setup

5.1 Managing Certificate Profiles

• Log in to the EJBCA management console.
• Choose CA Functions > Certificate Profiles.

5.2 Creating a Certificate Profile

Method 1: Cloning an Existing Profile

• Find an appropriate profile (for example, ENDUSER) in the list.
• Click Clone, enter the new name, and save the profile.

Method 2: Manually Creating a Profile

• Click Add and enter the name. The editing page is displayed.
• Set necessary information as required, including Key Usage, Extended Key Usage, validity period, and Subject DN.
• Save the settings and return to the list for check.

5.3 Creating a Crypto Token

1. Choose CA Functions → Crypto Tokens。
2. Click Create new and enter the following information:
   • Name：Enter the name of your crypto token.
   • Type：Select SOFT。
   • Auto-activation(Optional)：If selected, the crypto token can be automatically activated.
   • Allow export of private keys：Select Allow if you want to export the private key.
   • Authentication Code：Enter the authentication code and confirm it.
     dd if=/dev/random bs=1 count=128 2>&1| sha256sum | awk '{print $1}
3. Save the settings and ensure that the status is Active in the list。

5.4 Generating a Key Pair

• Access the xCrypto Token details page.
• Enter the key name, for example, signKey, in Crypto Token currently does not contain any key pairs.
• Select a key algorithm, for example, RSA 4096.
• Click Generate new key pair.

Note: The default profile cannot be modified. You need to clone it before creating a new one.

5.5 Creating a CA

1. Choose CA Functions → Certification Authorities。
2. The default ManagementCA (Active) is displayed in the list on the top. You do not need to select it。
3. Scroll to the Add CA area at the bottom of the page.
   • Enter the new CA name, for example, DemoCA, in the text box.
   • Click Create… on the right. The CA configuration wizard is displayed.
4. Enter necessary fields on the Create CA page.
5. Click Create at the bottom to save the CA. If the configuration is correct, the CA list is displayed and the DemoSubCA (Active) status is displayed.
6. (Optional) If you want to manually upload the certificate issued by the root CA, select the new CA in the list and select Import CA certificate… to upload the chain file.

The intermediate CA is created. You can use it to issue end-entity certificates.

5.6 (Example) Creating a Root CA

1️⃣ CA type and key configuration

2️⃣ Certificate policies (Directives)

3️⃣ CA certificate data

4️⃣ CRL configuration

5️⃣ Approval settings

6️⃣ Other data

7️⃣ Creation/Renewal of Externally Signed CAs

8️⃣ CA Creation

After confirming all parameters are correct, click Create to generate a CA.

1. Download and verify the root CA certificate.

Run the following OpenSSL commands to verify the certificate format and validity:

# Verify PEM certificates.
openssl x509 -in rootca.pem -text -noout

# Verify DER certificates.
openssl x509 -in rootca.der -inform DER -text -noout

# Check the certificate's SHA256 fingerprint information.
openssl x509 -noout -fingerprint -sha256 -in rootca.pem

# Verify the self-signed certificate validity.
openssl verify -CAfile rootca.pem rootca.pem

2. Deploy and verify the CRL.

If the CRL URL is configured, run the following command:

# Verify the CRL file.
openssl crl -in rootca.crl -text -noout

Ensure that the CRL can be accessed through the web.

🚀 The root CA has been created and can be used to issue intermediate CAs! 🎉

5.7 Creating an Intermediate CA Certificate

1️⃣ CA type and key configuration

2️⃣ Certificate policies (Directives)

3️⃣ CA certificate data

4️⃣ CRL configuration

5️⃣ Default CA defined validation data

6️⃣ Approval settings and other data

Currently, only None is available for approval settings, indicating that no additional approval process is required. If it is required, check the global approval policy Supervision Functions of EJBCA.

7️⃣ Intermediate CA creation

After confirming all parameters are correct, click Create to generate a CSR.

Submit the CSR to the root CA for signature, download the signed certificate, and verify it.

openssl x509 -in intermediate_ca.pem -text -noout
openssl verify -CAfile rootca.pem intermediate_ca.pem

🚀 The intermediate CA has been created and can be used to issue end entity certificates! 🎉

6. RA Common User Creation and Permission Configuration

6.1 Creating an RA Role

1. Access the RA Web page and choose Role Management > Roles > Create New Role.
   Role Management →Roles →Create New Role
   

2. Enter role information.：

   Field	Recommended Value
   Namespace	No namespace
   Role name	test RA Users

3. Set the permissions for Certificate Authorities.：
   • Select a CA, for example, Intermediate CA or Root CA, from the Available list and click Add.
4. Set the permissions for End Entity.(Recommended):
   • ✅ Create end entities
   • ✅ Create certificates
   • ✅ ...by using username and password
   • ✅ ...by using a request ID
   • ✅ View end entities and certificates
5. Set the permissions for End Entity Profiles.：
   • Select EMPTY from the Available list and click Add.
6. Click Add to save the created role.

6.2 Creating an RA Commer User (End Entity)

1. Access the EJBCA Admin Web page and choose RA Functions > Add End Entity.
2. Enter the user details.

   Field	Recommended Value
   End Entity Profile	EMPTY
   Username	test_signuser
   Password	123
   Confirm Password	123
   Batch generation	Not selected
   E-mail	cert-user@example.com
   CN	test RA user S1
   O	test
   C	CN
   Certificate Profile	ENDUSER
   CA	test Intermediate CA
   Token	P12 file

3. Click Add.

End Entity is created.

6.3 Downloading the User Certificate

1. Access the RA Web page and choose Enroll > Use Username.
2. Use the created username and password to log in.
   • Username: test_signuser
   • Password: 123
3. Select a key algorithm after logging in.
   • Select the RSA 4096 algorithm, and generate and download the .p12 user certificate.

6.4 Adding a User to the RA Role

1. Access the RA Web page and choose Search > End Entities.
2. Copy the CN of the certificate created earlier.
3. Access the RA Web page and choose Role Management > Roles > Members > Add Role Member.
4. Enter the information about the role member.

   Field	Recommended Value
   Role	test RA Users
   Token Type	Certificate
   CA	test Intermediate CA
   Match with	CN Common Name
   Match Value	Paste the copied certificate CN.
   Description	RA common user

5. Click Add to add the role member.
6. Restart the EJBCA service for the permission to take effect (recommended).
7. docker restart ejbca

6.5 Logging In to the RA WebUI

1. Non-administrator roles import the downloaded · certificate to the browser.
2. Access the RA Web page for automatic authentication and login.
3. Perform authorized RA operations, such as creating and viewing certificates.

6.6 Important Notes (Must Be Followed)

✅ You are advised to use the Chrome browser in incognito mode for the first login to quickly start the verification and avoid the error "No OAuth providers configured. Please log in using a valid certificate" caused by cache problems.

✅ Use HTTPS to access, for example, https://192.168.xxx.xxx/ejbca/ra/, to avoid the error "No OAuth providers configured. Please log in using a valid certificate."

7. Certificate Profile Settings

This section describes the meanings and recommended usage of the Certificate Profile configuration items in the EJBCA. It is applicable to certificate issuance requirements for common devices such as HTTPS, web, device, and client.

7.1 Basic Information

7.2 Permissions Control

✅ Suggestion: Keep profiles consistent in the production environment. Disable override permissions unless needed to stop CSR or End Entities from making unauthorized changes.

7.3 X.509v3 Extension—Basic Information

7.4 X.509v3 Extension—Key Usage

7.5 X.509v3 Extension—Extended Key Usage

7.6 Name Extension

7.7 Validation Data

7.8 Private Key Validity Period

7.9 ETSI Compliant Extensions (Typically for High-compliance PKI Use Cases)

7.10 Other Extensions

7.11 Approval Settings and Additional Fields

7.12 CA & Release Settings

To configure the code signing certificate profile, adjust the keyUsage and extendedKeyUsage fields.

📌 You are advised to create different profiles for different applications (such as VPN, HTTPS, code signing, and client authentication) to facilitate management and compliance control.

8. Approval Configuration and Management

8.1 Creating an Approval Profile (Approval Configuration)

1. Choose Watchdog > Approval Profiles.
2. Type a name (for example, test) at the bottom and click Add.
3. Click Edit in the list to enter the detailed settings.

8.2 Basic Parameter Settings

8.3 Approval Steps

1. Set Number of Required Approvals.
   • Development/Test: 1 (1-of-1).
   • Production/Sensitive operations: 2 (2-of-2) or partitioned approval.
2. Notification email:
   • Notification message email recipient: approval-admin-group@example.org supervisor@example.org
   • Notification message email sender: no-reply@192.168.xxx.xx
   • Example theme profile:
     [AR-${approvalRequest.ID}-${approvalRequest.STEP_ID}-${approvalRequest.PARTITION_ID}] Approval Request
     

   • Variables that can be referenced in the body: ${approvalRequest.TYPE}, ${approvalRequest.REQUESTOR}, and ${approvalRequest.WORKFLOWSTATE}.

8.4 Binding to a Specific Action

End Entity Profile:

Choose CA Functions > End Entity Profiles > > Approval Settings> Add/Edit End Entity to be approved > Approval Profile and then click Save.

Common options: Add/Edit End Entity and Key Recovery (if enabled)

Certificate Profile:

Choose CA Functions > Certificate Profiles > > Approval Settings > Operation > Approval Profile and then click Save.

Sensitive administrator actions: It is recommended that 2-of-2 or partitioned approval be used for intermediate CA change and revocation.

8.5 Testing and Verification

1. Use a common RA account to start an operation (for example, creating an end entity) that requires approval on the RA WebUI.
2. Choose Inspector Function > Approvals to check the approval queue, and use another approver account to complete the approval.
3. Confirm that the operation was executed automatically and the email notification was received successfully.

8.6 FAQs

• No email received: Check the SMTP configuration, firewall, and recipient name, and view container logs.
• Stuck in pending status: Number of Required Approvals is set too high or the approver does not have the permission.
• Can be self-approved: Allow Self Approved Request Editing is selected by mistake. This function should be disabled in production.
• Expired: Request/Approval Expiration is set too short. The value can be changed to 8h to 24h.

9. End Entity Profile Settings

Path: RA Functions > End Entity Profiles. The End Entity Profile defines the fields that can be populated, specifies which are mandatory or modifiable, and determines the default Certificate Profile, CA, and Token.

9.1 Creating and Opening an End Entity Profile

1. Choose RA Functions > End Entity Profiles.
2. Enter the profile name (for example, test) at the bottom and click Add Profile.
3. Select the profile from the list and click Edit Endpoint Entity Profile.

9.2 Basic Information (Username/Password/Email)

Generally, the username/password does not need to be specified in the profile. The profile only sets the rules and methods. The username/password/enrollment code can be specified during end entity creation or application submission.

Recommended practice

• Username: Select Auto-generated (for auto and batch operations), or manually specify the username when creating an end entity.
• Password (or Enrollment Code): Select Required to use the one-off Enrollment Code. Enter the specific value when creating an end entity or submitting the application on the RA.
• Minimum password strength/length: Retain the policy (for example, the length is greater than or equal to 8), but do not enter the specific password.
• Maximum number of failed login attempts: Set the number as needed. Select Modifiable if you need to temporarily change this limit.
• Batch generation: Disable this function. Avoid storing enrollment codes in plaintext.
• E-mail: Set it based on the Required/Modifiable setting. It is used for notification and identification.

Impact of different application paths on username/password

• RA Web > Enroll > Use Username: Username and Password/Enrollment Code are specified when an end entity is created. The user uses this account to log in to the system and obtain the certificate.
• RA Web > Enroll > Use Request ID: The system allocates Request ID. Password/Enrollment Code is set when the request is created. The applicant uses the ID and code to obtain the certificate.
• User Generated (CSR): Token=User Generated. Retain Required to generate a one-off code. The applicant uses the CSR and code to complete the issuance.

Directives

• Reverse Subject DN and Subject Alt Name Checks: You can also deselect this option.
• Allow merge DN for all interfaces: Generally, this option is not selected. It is selected only when DN combination is required for multiple APIs.
• Allow multi-value RDNs: This option is selected only when special requirements are met. (It is disabled by default, which is more secure.)

9.3 Subject DN Attributes—(Setting by Users)

Available attributes are displayed on the left, and selected attributes are displayed on the right. Add the required fields to the right and set Required/Modifiable/Validation for each field.

Common recommendations (client/general):

If stricter verification is required, you can specify a regular expression or format rule in Validation.

9.4 Other Subject Attributes—(Setting by Users)

Subject Alternative Name (SAN) :

• Client certificate: RFC 822 Name (e-mail address) (same as the account email address)
• Server certificate: DNS Name and IP Address (added by domain name/IP address)
• Device certificate: OtherName (written into the device ID/OID)

(Optional) **Subject Directory Attributes:

Attributes such as Date of birth (YYYYMMDD) are used only for archiving or compliance needs. You are advised not to enable multiple directory attributes.

Addition method: Select an item in the Other Subject Attributes area and click Add. You can also mark it as Required/Modifiable if supported by the interface.

9.5 Main Certificate Data

9.6 Other Certificate Data

• Custom certificate serial number: disabled by default
• Certificate Validity Start/End Time: controlled by Certificate Profile by default. If a temporary certificate is required, enable this item and select Modifiable.
• Name Constraints (Permitted/Excluded): used for intermediate CAs. Generally, this item is disabled in end entity profiles.
• Custom certificate extension data / ETSI PSD2 QC Statement / CA/B Forum Organization Identifier: Enable it as required for compliance.

9.7 Other Data/Restrictions

9.8 Saving and Authorization

1. Click Save.
2. Choose RA Web > Role Management and check that the related role has been authorized to use the end entity profile (visible/creatable).
3. Choose Search > End Entities and use the profile to create a test user to check the following:
   • Check whether the DN/SAN is added to the database according to the rules.
   • Check whether the certificate uses the expected Certificate Profile/CA/Token.
   • Check whether the download or import is successful (P12/PEM/CSR process).

10. Applying for an End Entity Certificate as an RA Common User

Choose RA Web → Enroll。

By default, you are advised to use By the CA (the CA generates the key) for stability and fewer errors; no CSR is needed.

10.1 Path and Prerequisites

• Profiles have been prepared in End Entity Profiles (Section 9) and Certificate Profiles. Users have access permission.
• When approval is enabled (see Section 8), submissions go into the pending queue. Certificates are issued once they are approved.

10.2 Recommended: By the CA (No CSR Required)

1. Choose Enroll > Make New Request.
2. Select Certificate Type (End Entity Profile) and Certificate subtype (Certificate Profile).
3. Set Keypair generation to By the CA.
4. Expand Provide request info and enter Subject DN / SAN (such as CN, email address, DNS, and IP address) as required.
5. Download the *.p12 file.

10.3 Optional: Provided by user (Uploading a CSR)

This option is used only when the key must be generated on the client or server for reasons like compliance, using an HSM or dedicated device, or migrating an existing key.

1. Generate a private key and CSR locally.
2. Select Provided by user and paste the complete CSR, including BEGIN/END CERTIFICATE REQUEST, into the text box.
3. Submit the CSR and download the certificate as prompted (the private key is not included).

10.4 Approval Association and Notification

• If a profile is bound to an Approval Profile, the profile will be pending approval upon submission. After the profile is approved, the profile will be automatically issued or available for download.
• The email subject and body comply with the notification requirements in Section 8.

10.5 FAQs

• Field failure: The DN/SAN is inconsistent with that in the profile. Adjust the DN/SAN according to Section 9.
• Unable to download P12: Download is blocked by the browser, or password policies conflict. Use another browser or check the password length and character set.
• CSR rejected: The Subject/SAN in the CSR conflicts with that in the profile. Rebuild the CSR using the profile or use By the CA.
• Approval suspended: The number of approvers does not meet the requirement, or the approver does not have the required permission. Check the status under Monitor > Approvals.