EJBCA - Open Source PKI Certificate Authority - The Registration Authority UI

RA Documentation

RA User Guide and more is currently living in a separate documentation tree and can be provided by PrimeKey upon request until it reaches the official documentations.

Two External RA versions

Since EJBCA 6.6.0 there are two variants of External RA:

The (new) Peer Connector based External RA, including a user friendly GUI for users and administrators. This is actually a generic RA, but with capabilities to operate in an external polling mode.
The (old) database polling External RA, described here.

This document describes the first, new, Registration Authority.

RA Concepts

EJBCA	Enterprise Java Beans Certificate Authority, includes both CA, VA and RA
CA	Certificate Authority
RA	Registration Authority, can be run as part of the CA or as a separate services
Peer Systems	A mechanism for connections initiated from the CA to the RA (or VA), where messages for control and operations are passed
RA User	A User that makes a certificate request on the RA, the user may have to wait for an RA Admin to approve the request
RA Admin	An Administrator that approves requests made by RA Users
Approvals	The mechanism for requiring Administrators to approve actions before they are executed

Using the RA in External Polling mode

In many cases, for security reasons, is it preferable to deny all inbound traffic to the CA installation and instead let the CA fetch and process information from an external RA. The EJBCA RA does this using Peer Connectors.

EJBCA PKI setup with Peer Connector External RA, not allowing incoming connections to the CA.

Security Features

Some security features of the RA, using Peer Connectors are:

TLS Connection established from the CA to the RA, only firewall friendly outgoing connections from the CA.
Mutually authenticated TLS connection.
JSF 2.0 based Web UI, including Content Security Policy, protection against CSS, CSRF and other attacks.
Filtered error messages from the CA, only shows non-sensitive information in the RA UI.
Secure object transfer between RA and CA.
Location aware authorization. The authorization on the CA is a combination of the Users authorization, and the RA servers authorization. You can limit what is accessible through specific RA servers.

Clustering the RA

You can have several RA servers, in order to provide high availability, or increased performance. The RA itself is stateless and therefore any user can access any RA server to perform their tasks, as long as it is an RA with the same privileges (see Security Features). User session against the RA UI uses HTTPS sessions, and are typically pinned to a certain node by a load balancer.

Installation

The RA UI is part of any EJBCA installation, after installing a CA (on localhost in the example) the RA UI is available over https://loalhost:8443/ejbca/ra/.

To install the RA as an external service you first install EJBCA with an external Management CA (from your EJBCA CA) and after this configure a Peer Connection from the CA to the RA.
See the section on Installing EJBCA with external administrators in the User Guide.
See the section on Peer Systems, in the Admin Guide.

User Authorization

To be authorized to use the RA, both the peer connection role (in case the RA runs as an external service) and the user's/admin's role must be configured to allow access to the desired functionality. For the built-in role templates, the authorization works as follows:

CA Administrators are granted access to all functionality in the RA, but only to the CAs that are selected in the administrator role. CAs and related end entities and certificates, will be hidden if the administrator does not have access.

RA Administrators have access to the Enrollment, Search and Manage Requests pages, depending on the selected End Entity Rules. Access is restricted according to the selected CAs and end entity profiles as well. In order to make a certificate request, the administrator needs both "Create End Entities", "View End Entities" and "Delete End Entities" access. Permission to approve or reject a request is controlled by the approval profile, but certificate requests and requests to edit end entities additionally require the "Approve End Entity" access. The certificate and end entity search require "View End Entity" access.

Supervisors have access to the Manage Requests and Search pages only, in read-only mode.

Auditors have access to everything in read-only mode, except for the Enrollment pages which are not accessible.

Note that, in addition to the role configuration, the "Enforce ..." settings in the CA also control when certificates may be issued. Since the RA always creates a new end-entity for each request, this means that in order for renewal of certificates to work, the "Enforce unique public keys" and "Enforce unique DN" options must be turned off.

If you configure the access rules in Advanced Mode (i.e. not using the role templates), you will need to following access rules (listed per menu item). In addition, you also need access to any related CAs and End Entity Profiles, including all CAs referenced by the End Entity Profiles.

Enrollment

/ca_functionality/create_certificate
/ra_functionality/view_end_entity
/ra_functionality/create_end_entity
/ra_functionality/delete_end_entity
/ca/...
/endentityprofilesrules/.../view_end_entity
/endentityprofilesrules/.../create_end_entity
/endentityprofilesrules/.../delete_end_entity
Depending on your configuration, you might also need /ra_functionality and/or /ra_functionality/edit_end_entity + /endentityprofilesrules/.../edit_end_entity. This is a known bug (ECA-5458), which will be fixed in a future release.

Certificate and End Entity Search

/ra_functionality/view_end_entity
/ra_functionality/revoke_end_entity - if the role should be allowed to revoke certificates
/ca/...
/endentityprofilesrules/.../view_end_entity

Manage Requests

/endentityprofilesrules/.../approve_end_entity
and at least one of:

/ra_functionality/approve_end_entity - to approve certificate requests and end entity operations
/ca_functionality/approve_caaction - to approve other operations
/secureaudit/auditor/select - to see requests without being able to approve them

CAs & CRLs

/ca_functionality/view_ca
/ca/...

Note that RA does not support Decline rules. If a role that has a Decline rule is used on the RA, it will be denied access to everything as a security precaution.

Sample Configuration

This example configuration will create one RA User that can request certificates (needing Approval) and one RA Admin that can approve the requests.

We will assume that you already have a CA (names High Assurance CA), a Certificate Profile (named EV TLS) and an End Entity Profile (also named EV TLS), where the profiles are set to issue from that CA.

Create Roles

In order to set up approvals we first need two roles that will be part of the approval process.

In the Admin GUI, go to Administrator Roles
Add a role called 'RA User'
Add a role called 'RA Admin'
Edit Access Rules for 'RA User'

Custom->Advanced Mode
/ca_functionality/create_certificate
/ra_functionality/view_end_entity
/ra_functionality/create_end_entity
/ra_functionality/delete_end_entity
/ca/High Assurance CA
/endentityprofilesrules/EV TLS/view_end_entity
/endentityprofilesrules/EV TLS/create_end_entity
/endentityprofilesrules/EV TLS/delete_end_entity

Click 'Save'
Edit Access Rules for 'RA Admin'

RA Administrator
Authorized CAs: High Assurance CA
End Entity Rules: all
End Entity Profiles: EV TLS
Other rules: none

Click 'Save'

Now add some users to the 'RA User' and 'RA Admin' roles.

Create an Approval Profile

In order to configure the system to require approvals for issuing certain certificate we need to create an Approval Profile.

One peculiarity of the approvals system is that the role privileges are stored per request, so if you change roles in an Approval Profile, you need to make a new request for the new role attributes to be applied. Old requests will live after the rules set up when those requests were made.

Create an Approval Profile with two parts.

First one part for verifying the evidence:

In the Admin GUI, go to Approval Profiles
Enter 'EV TLS Approval' and click 'Add'
Click 'Edit' for 'EV TLS Approval'
Change 'Approval Profile Type' to 'Partitioned Approval'
In the first partition: Select 'RA Admin' as 'Roles which may approve this partition'
In the first partition: Select 'Anybody' as 'Roles which may view this partition'
In the first partition: Add a checkbox called 'Verified Evidence'
In the first partition: Add a textfield called 'Path to evidence'
Enter 'Evidence' in the name field of the first partition
Click 'Save'

Next one part for verifying the payment:

In the Admin GUI, go to Approval Profiles
Click 'Edit' for 'EV TLS Approval'
Click 'Add Partition'
Change 'Approval Profile Type' to 'Partitioned Approval'
In the second partition: Select 'RA Admin' as 'Roles which may approve this partition'
In the second partition: Select 'Anybody' as 'Roles which may view this partition'
In the second partition: Add a checkbox called 'Verified payment'
In the second partition: Add a radiobutton called 'Payment method' and add two rows, 'Credit card' and 'Invoice'
In the second partition: Add a textfield called 'Path to receipt'
Enter 'Payment' in the name field of the second partition
Click 'Save'

Configure Certificate Profile to use Approval Profile

We need to configure the Certificate Profile to use the Approval Profile.

In the Admin GUI, go to Certificate Profiles
Click 'Edit' for 'EV TLS'
Under 'Approval Settings' check 'Add/Edit End Entity', 'Revocation' and 'Key Recovery'
For 'Approval Profiles' select the newly created 'EV TLS Approval'
Click 'Save'

Email Notifications

You can configure email notifications both for RA Admins and RA Users to inform them when a request have been created or changed, and the link to approve or check status. Experiment with the notification configurations in End Entity Profiles and in Approval Profiles. See the documentation on Email notifications for information about parameters that can be used in emails.

Request Certificates

Start a new browser session and access the RA at https://localhost:8443/ejbca/ra/. You should now be able to request certificates using the function in 'Enroll->Make New Request'.

Depending on what RA User has access to, one or several profiles, one or several CAs etc, you will be presented with different information. The user will not be presented with options that are non-selectable, so with a limited configuration there are very few choices (easy to use).

When you have created a request you will be presented with a message that your request have been submitted for approval, and given a Request ID so you can follow the status of your request.

Approving Requests

Start a new browser session and access the RA again as 'RA Admin'. You should now have to option to 'Manage Requests'. Here you can view and approve (or reject) requests. Requests can also be edited, and once edited have to be approved by another administrator (you are now allowed to approve your own edits).