Approving Actions

The following provides information on approvals and workflows.

EJBCA allows enabling other administrators to approve an action in order to ensure that the correct data is entered.

The following actions are enabled for approvals:

  • Add End Entity
  • Edit End Entity
  • Change User Status
  • Revoke End Entity
  • Revoke Token (approval for each certificate)
  • Revoke Certificate
  • Reactivate Certificate On Hold

The main menu option Approve Actions allows the administrator to search for waiting requests, review their data, and approve or reject the action.

Configuring Approvals

Approvals are configured for each CA, in the Certificate Authorities page and for each certificate profile in the Certificate Profiles page.

Select the actions that need approval and the approval profile to use and save (see Approval Profiles). The actions Add End Entity, Change End Entity and Change User Status are all covered by the setting Add/Edit End Entity. Revoke End Entity, Revoke Certificate, Revoke Token and Reactivate Certificate are covered by setting Revocation. Approvals will be required if the CA or the certificate profile enforces it. In case both the CA and the certificate profile specify different approval profiles for the same actions, both approval profiles will apply in sequence; first the approval profile set in the CA, then the approval profile set in the certificate profile.

Noting that no administrator is allowed to take action regarding the same approval request more than once.

Approval Profiles

There are two types of approval profiles: Accumulative Approval Profile and Partitioned Approval Profile.

Accumulative Approval Profile

In the Accumulative Approval Profile profile, only the number of required approvals is set. No requirements are specified for the approving administrators other than that no administrator is allowed to approve the same request more than once.

Partitioned Approval Profile

In the Partitioned Approval Profile profile, several options can be set to specify which administrators can approve or reject a request. It is also possible to specify additional data that has to be acquired when a request is approved.

A partitioned approval consists of two concepts, Steps and Partitions:

  • Approval Steps need to be performed sequentially, i.e. step 1 must be approved before step 2 can be acted upon.
  • Approval Partitions are non-sequential parts that can be approved independently of each other, within a step. I.e. when step 1 has to be approved, Partition 1 and Partition 2 within this step can be approved in any order, independent of each other.

Both approval profiles types allow configuring a notification to be sent to the end user and/or to the administrator expected to approve the request (see Approval Notification). The profiles also allow setting the expiration period for the approval and for the request (see Approval Status).

For more information on available Approval Profile fields, see Approval Profiles.

Authorizing Approving Administrators

In order to authorize an administrator to review approval requests do one of the following.

Using Basic Rule Sets

Give a role the role template of SuperAdmin, CAAdmin or RAAdmin with Approve End Entities selected.

The SuperAdmin and CAAdmin give access to approve rules not associated with any end entity profile (i.e dual authenticated CA configuration (Not implemented yet)) while the RAAdmin only can approve actions related to authorized end entity profiles.

Using Advanced Rule Sets

There are three new access rules:

  • '/cafunctionality/approve_caaction', a rule that gives access to non end entity profile related actions like approving CA editing and creation (not implemented yet). An administrator must have either this rule or the '/rafunctionalty/approve_end_entity' in order to access the 'Approve Actions' web pages.
  • '/rafunctionalty/approve_end_entity', a rule (along with the corresponding end entity profile rule) that gives access to end entity profile related access rules, like adding and editing end entities. The administrator must also have the 'approve_end_entity rule' for at least one of the '/endentityprofilerules/' in order to approve any actions.
  • '/endentityprofilerules/<endentityprofilename>/approve_end_entity'see previous rule.

Two Different Approval Requests

In the system, there are basically two different classes of requests. One is requests to do some action, like adding an end entity, and that is executed directly after the last required administrator has approved the action. This type is called 'Executable Action Request'. The other type is requests to get hold of some information, like hard token PUK codes or archived keys. This kind of request is approved when the last administrator gives his consent and is valid for a defined period of time (set in the approval profile). In this case, the requesting administrator is supposed to poll the approval request if it has been approved or not. These requests are called 'Non-Executable Action Requests'.

Approval Status

The following lists the different approval request statuses:

Approval Status

Description

Waiting

Means that the action request is waiting to be processed by authorized administrators, request are valid for the time specified in the approval profile (Request Expiration Period) before it is set to status Expired.

Approved

Means that the action request is approved and is valid for the amount of time specified in the approval profile (Approval Expiration Period). After this, it is set to Expired. Used by action requests that are not executable.

Rejected

Means that the action request is rejected and won't be allowed. The rejection lasts the amount of time specified in the approval profile (Approval Expiration Period). After this, it is set to Expired and a new request can be done. Used by action requests that are not executable.

Expired

Means that the action request isn't valid anymore and cannot be processed. The requesting administrator has to make a new request in order to approve it.

Expired and Notified

Same as Expired but also indicates that the requesting administrator has been notified that the request has expired.

Executed

Means that the action request has been executed successfully. Used by action requests that are executable.

Execution Failed

Means that the action request failed for some reason during execution, see log for more information. Used by action requests that are executable.

Execution Denied

Means that the action request hasn't been approved and will not be executed. The difference with status Rejected is that this status is only used with executable requests and do not have any expire time. This means that the requesting administrator can apply again directly after the rejection.

Approval Notification

EJBCA approval functionality allows sending e-mail notifications to administrators affected by the approval workflow and/or the end user.

Notifications are configured per approval partition. An approval notification is sent for a partition when the partition:

  • Has been acted upon.
  • Becomes approvable due to the previous step being finished.
  • No longer is approvable since a parallel partition has been rejected or the request has expired.

Ensure to configure mail-server settings in order to enable EJBCA to send emails.

Dynamic Substitution Variables for approval notifications

The following variables are used with approval notifications:

VariableDescription
${approvalRequest.ID} The approval request identifier.
${approvalRequest.STEP_ID} The approval step that this notification concerns.
${approvalRequest.PARTITION_ID} The ID of the approval partition in the step that this notification concerns.
${approvalRequest.PARTITION_NAME} The name of the approval partition in the step that this notification concerns.
${approvalRequest.TYPE} The type of approval request.
${approvalRequest.WORKFLOWSTATE} The workflow state from the perspective of the one(s) responsible for handling the partition.
${approvalRequest.REQUESTOR} The human-readable version of the authentication token that was used to create the request.
${approvalRequest.APPROVALADMIN} The human-readable version of the authentication token that was used to last approve the request, if any.

The workflow states are:

Workflow State

Description

APPROVED

The partition has been approved and no longer requires any action.

APPROVED_PARTIALLY

The partition has been approved, but is still pending additional approvals.

REJECTED

The partition has been rejected and no longer requires any action.

REQUIRES_ACTION

The partition requires an action from admin.

EXPIRED

The partition (and also currently the whole approval) has expired and no longer requires any action.