EJBCA RA Administration

This guide describes EJBCA RA Administration tasks in the following sections User Authorization and Sample Configuration.

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/Admin role must be configured to allow access to the desired functionality. The following describes how the authorization works for the built-in role templates.

CA Administrators

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

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 end entity search require View End Entity access. The certificate search require View Certificate access.

Supervisors

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

Auditors

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

Access Rules

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 disabled.

If you configure the access rules in Advanced Mode (that is, not using the role templates), you need the following access rules (listed per menu item). 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/

If using a version prior to EJBCA 6.8.0, you also need the following rules to create certificates through the RA. These are not needed in EJBCA 6.8.0 and later.

/ra_functionality/edit_end_entity/
/endentityprofilesrules/.../edit_end_entity/

Certificate and End Entity Search

/ra_functionality/view_end_entity/
/ca_functionality/view_certificate/
/ca/.../
/endentityprofilesrules/.../view_end_entity/

Additionally, if the role should be allowed to revoke certificates, the following rule is needed:

/ra_functionality/revoke_end_entity/

Manage Requests

/endentityprofilesrules/.../approve_end_entity/

And at least one of the following rules:

/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/.../

Role Management

/system_functionality/edit_administrator_privileges/
/system_functionality/view_administrator_privileges/

To perform actual role management in the RA UI, a role for roles management also needs access to the rules that sub-roles have (in order to see those sub-roles withing a namespace) and the following rules:

/ca_functionality/view_ca/
/ca_functionality/view_certificate/
/ca/<CA issuing admin certificates>/

Key Recovery

/ra_functionality/keyrecovery/
/ca/.../
/endentityprofilesrules/.../keyrecovery/

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

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

It is assumed that you already have a CA (named 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

To set up approvals, you need two roles that will be part of the approval process.

  1. In the CA UI on the CA, go to Roles and Access Rules.

  2. Add a role called RA User.

  3. Add a role called RA Admin.

  4. Edit Access Rules for RA User in 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/

  5. Click Save

  6. Edit Access Rules for RA Admin:

    Template:

    RA Administrator

    Authorized CAs:

    High Assurance CA

    End Entity Rules:

    all

    End Entity Profiles:

    EV TLS

    Other rules:

    none

  7. Click Save.

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

RA Web Role Management

Optionally, the RA User role can be setup from the RA Web which is convenient if the logged in administrator does not have access to the CA (for example from an external RA). Using Role Management in the RA requires Role Management privileges (see Role Management).

  1. Go to the RA Web ( https://[yourdomain]:8443/ejbca/ra ).

  2. Navigate to Role Management > Roles.

  3. Click Create New Role.

  4. In the Available panel, select High Assurance CA and click Add.

  5. Select the End Entity Permissions options Create and delete end entities and View end entities.

  6. Under End entity profiles, select EV TLS and click Add.

  7. Click Add at the bottom of the page.

The role RA User is added with the corresponding access rules available in the CA UI.

Create an Approval Profile

To configure the system to require approvals for issuing certain certificates, you need to create an Approval Profile.

Note that the approval system stores the role privileges per request. As a result, 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

To create one part for verifying the evidence:

  1. In the CA UI on the CA, go to Approval Profiles.

  2. Enter EV TLS Approval and click Add.

  3. Click Edit for EV TLS Approval.

  4. Change Approval Profile Type to Partitioned Approval.

  5. In the first partition: Select RA Admin as Roles which may approve this partition.

  6. In the first partition: Select Anybody as Roles which may view this partition.

  7. In the first partition: Add a checkbox called Verified Evidence.

  8. In the first partition: Add a textfield called Path to evidence.

  9. Enter Evidence in the name field of the first partition.

  10. Click Save.

To create another part for verifying the payment:

  1. In the CA UI on the CA, go to Approval Profiles.

  2. Click Edit for EV TLS Approval.

  3. Click Add Partition.

  4. Change Approval Profile Type to Partitioned Approval.

  5. In the second partition: Select RA Admin as Roles which may approve this partition.

  6. In the second partition: Select Anybody as Roles which may view this partition.

  7. In the second partition: Add a checkbox called Verified payment.

  8. In the second partition: Add a radiobutton called Payment method and add the rows Credit card and Invoice.

  9. In the second partition: Add a textfield called Path to receipt.

  10. Enter Payment in the name field of the second partition.

  11. Click Save.

Configure Certificate Profile to use Approval Profile

You also need to configure the Certificate Profile to use the Approval Profile.

  1. In the CA UI on the CA, go to Certificate Profiles.

  2. Click Edit for EV TLS.

  3. Under Approval Settings, select Add/Edit End Entity, Revocation and Key Recovery

  4. For Approval Profiles, select the newly created EV TLS Approval.

  5. Click Save.

Email Notifications

You can configure email notifications for both RA Admins and RA Users with information on when a request have been created or changed, and including links to approve or checking status. Notification configurations can for example be specified in End Entity Profiles and in Approval Profiles. For more information on available parameters, see the E-mail Notifications section.

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.
The information displayed is depending on the RA User's access, for example if one or more profiles or CAs are available to the user. When there is only one choice available and thus no selection to be made, the option is not displayed on the page and thus a limited configuration results in an easy to use request page.

When you have created a request, you will be presented with a message that your request has 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, approve or reject requests. Requests can also be edited and once a request has been updated it has to be approved by another administrator as you are not allowed to approve your own edits.

Enabling Key Recovery

To perform key recovery for user, key recovery has to be enabled in EJBCA System Configuration. To activate key recovery:

  1. In the CA UI on the CA, go to System Configuration.

  2. On the Basic Configurationtab, for Enable Key Recovery, select Activate [x]

Additionally, the end entity profile used to create the end entity, requires key recovery to be enabled.

Using Local Key Generation

Local key generation is used when the key recovery data (encrypted key pair) is to be stored on an external RA rather than the CA. For more information, see the Key Recovery section.

To activate local key generation, do the following.

  1. In the CA UI on the RA, go to System Configuration.

  2. On the tab Basic Configuration, for Enable Key Recovery, select Activate [x] and Force Local Key Generation [x].

  3. Select a crypto token for encryption of the key pairs (the crypto token must be created and activated before this step).

  4. Select a crypto token key.