A private key and matching Web Services (WS) Certificate is required to access ADP web services. The WS Certificate provides client information to ADP and the matching private key confirms the authenticity of the client. To generate the WS Certificate, a Certificate Signing Request (CSR) needs to be generated by the client. During the CSR generation, the private key and matching public key are created. The CSR is submitted to the ADP Web Services Certificate Authority (currently run by Sectigo/Comodo) and they return the WS Certificate. Many software tools store the private key and the WS Certificate in one Personal Information Exchange Format (PFX), also known as P12, file. Other tools (such as Java Keytool) that can be used to generate a CSR are not covered in this document.
Open Secure Sockets Layer (OpenSSL) is an open source tool. Although ADP has tested the commands based on the OS, configuration settings and other environmental factors, the commands and configuration may have to be adjusted. Clients will need check and support the OpenSSL tool from their own IT department. Clients need to ensure that every time new private and public keys are created, they are managed properly. If they are generated more than once, each key pair must be stored (possibly in different directories) so there is no confusion. In addition, the returned Web Services Certificate (which also contains the public key) must be managed properly (stored in the directory that has the matching private key).
To complete a Certificate Signing Request, do the following:
- Download OpenSSL Light for Windows at: http://slproweb.com/products/Win32OpenSSL.html. Mac users can open Terminal and jump to the OpenSSL commands in step 7
- Follow the instructions in the Install Wizard to install OpenSSL
- Go to the location where you installed OpenSSL. For example, C:\OpenSSL-Win32\bin) and modify the file C:\OpenSSL-Win32\bin\openssl.cfg. Look for the section starting with req_attributes, remove unstructuredName, and click Save.
[ req_attributes ]
challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20 unstructuredName = An optional company name
[ req_attributes ]
challengePassword = A challenge password challengePassword_min = 4 challengePassword_max = 20
- Open cmd.exe.
- Go to the location where you installed OpenSSL and at the command line, type cd C:\OpenSSLWin32\bin.
- If you are using a Windows machine, set the following variable: set OPENSSL_CONF=C:\OpenSSL-Win32\bin\openssl.cfg.
- Generate the CSR:
- openssl genrsa -out companyname_auth.key 2048
- openssl req -new -key companyname_auth.key -out companyname_auth.csr
Your CSR must not request S/MIME capabilities
- Enter the following information into your CSR. Leave the challenge password blank.
- Country Name
- State or Province Name
- Locality Name
- Organization Name: must be the same string used by your organization when registered with ADP
- Common Name (Use something meaningful, such as CompanyName Corp Mutual SSL or whatever best describes the usage and identifies this as the Mutual SSL Authentication certificate)
- Challenge password (leave this field blank)
- After you have created your CSR, you have two options for submitting it to ADP for signing. If you’re currently in the process of implementing ADP APIs, you can email your CSR to your assigned ADP implementation representative for signing. Otherwise, follow these steps to submit your request directly to ADP security Services:
- Open the ADP Certificate Signing Tool (no login is required)
- Choose “Authentication and transaction singing” for the certificate type
- Enter your technical contact’s email
- Enter your company name and ADP client ID. Note, if you are a ADP Workforce Now client, your ADP client ID is all the characters to the right of the ‘@’ symbol in your ADP Workforce Now login name. If you don't know your ADP client ID, please contact your ADP representative.
- Enter your technical contact’s first and last name and a group distribution list to be automatically notified when the generated certificate is reaching its two-year expiration date
- Paste the complete contents (including ‘BEGIN CERTIFICATE REQUEST’ and ‘END CERTIFICATE REQUEST’) of your CSR into the certificate singing Request (CSR) text box
- Click Submit. Note: It might take up to a week to sign the CSR
- Save the signed certificate from ADP into a file named companyname_auth.pem in the same location that you initially created the CSR ( C:\OpenSSL-Win32\bin )
- If you are using Windows/IIS, use the following command to get the key and certificate in PKCS12 format: openssl pkcs12 -export -out companyname_auth.pfx -name “Company Name Mutual SSL” -inkey companyname_auth.key -in companyname_auth.pem
- Enter Export Password.
The resulting certificate and key should be in the file companyname_auth.pfx that you will reference for Mutual SSL authentication.
Make sure you safeguard the .key, .pfx and .jks files. Anyone that possesses these confidential files has access to the web service.