Roles and Access Rules Operations

The following describes how to work with roles and access rules.

For more information on the general concepts, see Roles and Access Rules Overview.

Managing Role Namespaces

Namespaces are used to create a partition between sets of roles, to reduce the risk of mistakenly assigning an administrator belonging to one organization to a role belonging to another. See Managing Role Namespaces.

Creating a New Administrator

Follow the steps below to create a new Administrator certificate, add this Administrator to a role, and test the access.

Creating a Certificate Profile for the Administrator

Follow the steps below to create a new Certificate Profile for administrators. The administrators certificates will be issued by a CA called ManagementCA.

  1. Under CA Functions, click Certificate Profiles.

  2. Click Clone for the profile named ENDUSER.

  3. Enter AdministratorEndEntityCertificateProfile as the new name and click Create from Template.

  4. Click Edit for the new profile.

  5. Under Validity, enter 365d (1 year validity).

  6. Under Key usage, choose Digital Signature and Key encipherment (Ctrl+Click to select multiple).

  7. Clear Allow Key Usage Override.

  8. Select Use Extended Key Usage.

  9. Under Extended Key Usage, choose Client Authentication.

  10. Under Available bit lengths, "1024 bit", "2048 bit" and "4096 bit".

  11. Under Available CAs, choose ManagementCA (the CA you use to issue Administrator certificates).

  12. Click Save.

Creating an End Entity Profile for the Administrator

Follow the steps below to create a new End Entity Profile for Administrators. The profile will be connected to the Certificate Profile created above.

  1. Under RA Functions, click Edit End Entity Profiles.

  2. Enter a name for your end entity profile, AdministratorEndEntityProfile.

  3. Click Create.

  4. Select AdministratorEndEntityProfile and click Edit End Entity Profile.

  5. Under the Subject DN Fields, add DN fields for the Admin DN, for example O, UID and C.

  6. Under Default Certificate Profile, choose AdministratorEndEntityCertificateProfile.

  7. Under Available Certificate Profiles, choose AdministratorEndEntityCertificateProfile.

  8. Under Default CA, choose ManagementCA.

  9. Under Available CAs, choose ManagementCA.

  10. Click Save.

Issue the following new end entity based on the new end entity profile: CN: SoftCard RA Admin1.

Creating a new RA Role

Follow the steps below to create a RA Administrator role with access to add/list/edit end entities:

  1. Under System Functions, click Administrator Roles.

  2. Click Add.

  3. Choose a name for your new administrator group, RAAdministratorRole.

  4. When the group is created, click Access Rules.

  5. Choose the RA Administrator role template.

  6. Under Authorized CAs, choose which CAs the role should have access to and select ManagementCA.

  7. Under Edit End Entity Profiles, select AdministratorEndEntityProfile.

  8. Click Save.

Adding new Administrators to the RA Role

Follow the steps below to add new administrators to the RA role:

  1. Choose Search > Edit End Entities and select your newly created end entity, choose View Certificates.

  2. Copy the value of Certificate Serial Number, e.g. 5F003A0113F507F9.

  3. Go to Administrator Roles, click Administrators under RAAdministratorRole.

  4. Choose the CA that the administrator belongs to, ManagementCA.

  5. Paste the text from < in the Match value.

  6. Click Add.

In EJBCA Enterprise Edition, it is also possible to add a new administrator to an existing role by using the WS API call addSubjectToRole in your application or with the Web Services CLI.

Test the new Administrator

Log in with the new administrators to view differences between that and the super administrator. Additionally, try the different roles and privileges to see the differences between them all.

The authorization privileges are cached and there will be a slight delay before a rule change is used.

Renewing the Super Administrator

Renewing the SuperAdmin certificate is done in the same way as for any client certificate. You can reset your SuperAdmin credentials when expired using either the Admin GUI or the CLI.

The SuperAdmin certificate is normally issued as a PKCS#12 keystore, if not issued as a browser certificate for smart card enrollment.

Renewing SuperAdmin Using the Admin GUI

To renew SuperAdmin using the Admin GUI, do the following:

  1. Go to Search/Edit End Entities and search for user superadmin.

  2. Click Edit End Entity.

  3. Set a new password and set status to NEW, click Save.

  4. Go to EJBCA RA Web and click Use Username.

  5. Enter the username superadmin, and the password set in step 3.

  6. In the next screen, select key length 2048 and click OK.

Your new superadmin keystore is downloaded and you can install it in your browser.

Renewing SuperAdmin Using the CLI

To renew SuperAdmin using the CLI, do the following:

  1. Access your EJBCA server CLI.

  2. Run the following to reset the status of the SuperAdmin End Entity.

    bin/ejbca.sh ra setendentitystatus superadmin 10

  3. Run the following to reset the password. This password is used to protect the superadmin.p12 file and is set to password in the following example:

    bin/ejbca.sh ra setclearpwd superadmin password

  4. Run the following to process the request from the CLI. The batch command outputs the file to the directory /ejbca/p12.

    bin/ejbca.sh batch

Your new SuperAdmin keystore is generated and stored in the subdirectory /ejbca/p12. The password is set according to what you specified using the setclearpwd command in step 3 above.

Using Client Certificates Issued by External CAs

Administrator certificates in EJBCA can be issued by a CA other than a CA in the same installation. This can for example be useful if you want to use a national ID for administration of an organizational PKI.

To use a certificate issued by an external CA as Administrator, do the following:

  1. Add the CA-certificate to p12/truststore.jks with

    keytool -import -trustcacerts -file externalca.pem -keystore p12/truststore.jks -storepass changeit -alias externalca

  2. Redeploy EJBCA truststore using ant deploy-keystore and restart the application server to make sure the new truststore is in use

  3. Import the CA-certificate under CA UI > Certificate Authorities > Import CA Certificate or use the CLI.

  4. Add the Administrator to the desired role under CA UI > Administrator Roles.

  5. To allow administrators to log in when their certificates are not present in the EJBCA database, set web.reqcertindb=false in conf/web.properties.

Installing EJBCA with External Administrators

You can install an EJBCA instance from scratch, with a certificate from an external CA as the initial SuperAdmin certificate.

Start with deploying EJBCA as usual with ant deploy, but instead of running ant install, run the following to import the certificate of the external Administration CA and initialize the authorization system of EJBCA:

bin/ejbca.sh ca importcacert ManagementCA ManagementCA.cacert.pem -initauthorization -superadmincn SuperAdmin

You need to configure TLS and the truststore of the application server yourself, or if you have a p12/tomcat.jks and p12/truststore.jks this can be done for you on JBoss by ant deploy-keystore in the same way as configuring TLS as described in Application Servers.

The initial administrator that is set up has DN CN=SuperAdmin, but you can change this using the -superadmincn (run bin/ejbca.sh ca importcacert for documentation). You can also run the bin/ejbca.sh admins command for information on how to configure other admins.

After this command is run and TLS is correctly configured, you can log in to EJBCA and create your CAs in the CA UI. No initial CA is created for you.