Skip to main content
Skip table of contents

Web Services

Introduction

Integration - Web Services

Slide Deck: Integration

Overview:

EJBCA has an extensive SOAP Web Services Interface that can be used for remote scripting and to integrate EJBCA with other applications that support Web Services API. 
The SOAP Web Services interface requires client certificate authentication and that certificate is added to an appropriate administrator role, in the same way as access to the Admin GUI does.

This section will show how to use clientToolBox as a WS client.

The first part of the lab will create the Web Services administrator login account. This account is used to perform the 2nd part of the lab.

The second part of the lab will:

  1. create an entry in the database

  2. issue a certificate to that entry

  3. lookup the user in the database

  4. revoke the newly created user

  5. lookup the user in the database

Slide Reference

Certificate and CA operations availalble using Webservices

Create the URL with the default URL resource + the protocol alias; the client will contact the URL

Reminder you can visit the Accessing Your Environment page for details on how to connect to your Admin web portal

Enable Web Service Protocol

Ensure that the web service protocol is enabled:

  1. Open a browser and access your Admin Web Portal

  2. Click System Configuration >> System Configuration

  3. Click on the Protocol Configuration tab

  4. Ensure Web Service status is Enabled

Create WS Client End Entity

Create a NEW entry called training_ejbcawsracli. This end-entity will be used to authenticate to EJBCA, and create other end-entities and certificates using the WebServices protocol. Only the end-enitity is created at this point, and will be in NEW status. Follow these steps to create the training_ejbcawsracli end entity.

  1. Open a browser and access your Admin Web Portal

  2. Click RA Functions >> Add End Entity

  3. In the End Entity Profile list, select TLSClientEndEntityProfile

  4. In the Username field, enter training_ejbcawsracli

  5. In the Password field, enter foo123

  6. In the Confirm Password field, enter foo123

  7. In the CN, Common name field, enter training_ejbcawsracli

  8. In the Certificate Profile list, select TLSClientCertificateProfile

  9. In the CA list, select Management CA

  10. In the Token list, select P12 file

  11. Click Add

Register WS Client as Administrator

Add the Webservices user training_ejbcawsracli to the proper role; in this case the Super administrator role.

  1. Open a browser and access your Admin Web Portal

  2. Click System Functions >> Roles and Access Rules

  3. On Super Administrator Role, click Members

  4. In the Match With list, select X509: CN, Common name

  5. In the CA list, select ManagementCA

  6. In the Match value field, enter training_ejbcawsracli

  7. Click Add

Reminder you can visit the Accessing Your Environment page for details on how to connect via SSH

Enroll the WS admin and generate WS Client Keystore

Create the certificate (P12 file) for the Webservices entry training_ejbcawsracli using the EJBCA RAWeb. Follow these steps to generate the WS client keystore and certificate.

  1. Open a browser and click RA Web, from the ribbon menu across the top of page

  2. Select Enroll >> Use Username

  3. Enter training_ejbcawsracli for the userName

  4. Enter foo123 for the enrollment code

  5. Click Check

  6. Click Download PKCS#12, the P12 file will be downloaded to /home/sysadmin/Downloads - the name of the file is training_ejbcawsracli.p12

Configure clientToolBox WS Client

Modify the web services client properties file. This file is used by the web services client and identifies the location of the P12 file for the web services user. Follow these steps to configure the clientToolBox WS client:

  1. Using the TERMINAL app located on the desktop change to the clientToolBox directory:

CODE 
cd /home/sysadmin/clientToolBox

  1. Open the file ejbcawsracli.properties:

NONE 
vim ejbcawsracli.properties

  1. Set the following values in ejbcawsracli.properties, make sure to set the password that was used when the end entity was added:

BEWARE OF LEADING OR TRAILING SPACES WHEN EDITING THE FILE.  
THIS CAN CAUSE ERRORS WHEN RUNNING THE NEXT FEW COMMANDS.  
For example a space after the password, will cause errors.

CODE 
ejbcawsracli.url = https://ca.keyfactor.training/ejbca/ejbcaws/ejbcaws
ejbcawsracli.keystore.path = /home/sysadmin/Downloads/training_ejbcawsracli.p12
ejbcawsracli.keystore.password = foo123

Remember to remove the # symbol at the beginning of the line when editing the ejbcawsracli.properties file.

Some helpful vi commands:

a - insert characters after the current position

i - insert characters at the current position

x - delete the current character 

^ - goto beginning of the current line

$ - goto end of the current line

:wq! - save and close the file

Web Services Commands

  1. Run the following command to show functions available in the clienToolBox WS client:

    NONE 
    ./ejbcaClientToolBox.sh EjbcaWsRaCli

    Result:

    NONE 
    Usage: edituser | finduser | findcerts | pkcs10req | pkcs12req | certreq | revokecert | revokecertwithmetadata | getpublisherqueuelength | revoketoken | revokeuser | checkrevocationstatus | generatenewuser | createcrl | cacertrequest | cacertresponse | customlog | getprofile | createcryptotoken | generatectkeys | createca | importcacert | updatecacert | addadmintorole | removeadminfromrole | getexpiredcerts | getexpiredcertsbyissuer | getexpiredcertsbytype | stress | keyrecover | keyrecoverenroll | getremainingnumberofapprovals | getClientToolBoxVersion

  2. Add an end entity via Web Services protocol. The end entity will have a status of NEW.
    You will see a line stating “User ‘WebService-Cli-User1’ has been added/edited”.

    NONE 
    ./ejbcaClientToolBox.sh EjbcaWsRaCli edituser WebServiceCli-User1 foo123 false \
"CN=WebService CLI User1,O=PrimeKey Solutions AB,C=SE" NULL NULL \
"Sub CA" 1 P12 NEW TLSClientEndEntityProfile TLSClientCertificateProfile

  3. Issue PKCS#12 file. The end entity will have a status of GENERATED.
    You will see a line stating “KeyStore generated, written to WebService-Cli-User1.p12”.

    NONE 
    ./ejbcaClientToolBox.sh EjbcaWsRaCli pkcs12req WebServiceCli-User1 foo123 2048 RSA NONE

  4. Lookup the added user. The details for the entry will be displayed, with a status of GENERATED.

    NONE 
    ./ejbcaClientToolBox.sh EjbcaWsRaCli finduser USERNAME EQUALS WebServiceCli-User1

  5. Revoke the user. You will see a line stating “User revoked successfully”.

    NONE 
    ./ejbcaClientToolBox.sh EjbcaWsRaCli revokeuser WebServiceCli-User1 REV_UNSPECIFIED false

  6. Lookup the the user again. The details for the entry will be displayed, with a status of REVOKED.

    NONE 
    ./ejbcaClientToolBox.sh EjbcaWsRaCli finduser USERNAME EQUALS WebServiceCli-User1


? Question and Answers ?

JavaScript errors detected

Please note, these errors can depend on your browser setup.

If this problem persists, please contact our support.

Contact Support Close