Friday, January 12, 2018

Feature Highlight: Approval Profiles

So the concept of approvals is a rather well known concept in EJBCA. The basic concept is that your organization may not trust lower level or individual administrators to perform certain actions (such as enrolling end entities or renewing certificates), and thus require either higher level administrators (with specific approval rights) or a multitude of administrators (requiring a conspiracy) to perform certain actions, or a mixture of both.

In EJBCA 6.6 we introduced the concept of Approval Profiles due to the fact that we got a customer request to implement a more dynamic and complex approvals process, while we were at the same time unwilling to drop the old one.

Accumulative Approvals

Accumulative Approvals represents the type of approval process which existed prior to EJBCA 6.6, now given a name to differentiate it from later implementations. The concept is rather simple: say that we have a PKI organization containing a relatively flat structure, simple three administrators:
For the sake of argument, let's presume that these three are all equal, but their policies require that none of them be able to perform any enrollment actions without the cooperation of at least one of the other. Traditionally we would simply set the number of approvals in the CA or Certificate Profile to two, but now that we use Approval Profiles we set up an Accumulative Approval Profile instead:

Partitioned Approvals

In EJBCA 6.6 we added a more complex form of approvals, which we've decided to call Partitioned Approvals. Partitioned approvals consist of two basic temporal concepts: steps and partitions. The diagram below tries to explain this in simple terms: 

The basic concept is that steps are solve sequentially, while partitions are solved in parallel within their step. What this means is that (for example) Step2:Partition1 can't be approved until all three partitions in Step 1 have been approved. Now, how might this be used? Well, let's presume the following organization:
This structure resembles an actual PKI organization far more. The players here are:
  • Alita  -  An RA Administrator whose role is to meet certificate applicants after they've enrolled using the RA UI and to verify their identities. 
  • Björn - Works for Financial Services. Does not have any rights to enroll customers, but has been tasked in verifying that customers have payed their fees. 
  • Beatrix - Works for the company's security division. Lacks like Björn the ability to enroll customers, but is tasked in performing background checks on prospective clients. 
  • Cilla  -  A supervisor who has to approve the work of the previous three. If she's happy, then the customer can next retrieve their certificate. 
Now, looking at the graph above you may infer that Alita's, Björn's and Beatrix' tasks are all part of Step 1. The reason for this is that Cilla  isn't interested (or allowed) to give her approval until she's verified the results of Alita, Björn and Beatrix. 

On the other hand, there is nothing stopping Alita, Björn and Beatrix from solving their tasks in parallel. Once all of them approved their respective partitions, the process will automatically transition to Step 2. Combining these two diagrams we get the following, with blue representing view access and green representing approval rights:

So, what does this look like in EJBCA? Well, an initial Partitioned Profile will look like this:
As you can see above, we initially have a single step containing a single partition, which is the minimum possible. You'll also notice in the center of the partition the two multi-selects that display all available Roles with approval rights. Let's add another step by clicking on the Add Step button on the bottom right:
Next lets create the partitions in Step 1. First we'll click the Add Partition button on the bottom right of that step twice, name the partitions and assign the roles: 

Notice above that the roles do not have view rights of each others' partitions (except the RA Administrator partition, who anybody can review), and that the Supervisor role can review all. Next, let's edit Alita's partition so that she can add a bit more information for the records:
By clicking on the Add Field button (which is hidden in the above screenshot behind the drop-down) we can add meta data fields to the partition. In this case we've added a check box, a radio button list to identify the type of identification provided and a free form text field for any other information (such as passport number). 

We'll set up Beatrix' and Björn's partition in the same way, then lastly make sure that only the Supervisor group has approval and review access to the final step:
This way the supervisor can review and verify that all previous actions have been performed correctly and without fault before allowing the enrollment process to continue.

Practical Example

Now, let's see what this looks like in real life! For this example we're going to follow closely the RA Administrator Alita and her supervisor Cilla, while letting Beatrix and Björn do their work in the background for brevity. First of all, we make sure that the familiar WidgetCorp CA is set up to use the above approval profile for enrollment:
Then along rolls our old friend Alan Widget, who's about to request that the CA generate a keypair for him:
As we've activated approval for the CA, naturally Alan will have to wait a bit to receive his keypair:
Logging in as our RA Administrator we can see that she now has an approval request pending:
And viewing that request, we can fill in the relevant data about the request:
Logging in as the Supervisor on the other hand, you'll notice that the To Approve tab is empty as the Supervisor doesn't have anything to approve in the current step, while the request is instead under the Pending Approval tab as the Supervisor can still review the other's work.
Once Security and Finances have approved (or denied) their respective partitions of the request, the step is automatically completed and moves on to the final step that we've defined, which is the approval of the Supervisor. She now has the request under the To Approve tab, where she can also review all of the previous steps that she has view access to:

Approving the final step will leave the entire request executed, and our end user is now free to retrieve their certificate:
So, that is in a nutshell how to use Partitioned Approvals in EJBCA. If you have any feedback, feature requests or questions, please let us know! And if there are other EJBCA features you'd like me to dive into, please comment here on the blog!

Mike Agrenius Kushner
Product Owner EJBCA

1 comment:

Amin Khorsandi said...

Nice post, useful info! :-)