A Certificate Signing Request (CSR) is required for accessing ADP Application Programming Interfaces (APIs) and authenticating users with single sign-on (SSO).
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 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 a 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 5.
- To install OpenSSL, follow the instructions in the Install Wizard.
- Open cmd.exe.
- Go to the location where you installed OpenSSL and at the command line, type cd C:\Program Files (x86)\OpenSSL-Win32\bin (or C:\Program Files\OpenSSL-Win64\bin for 64-bit).
- 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 an 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, 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 CSR text box.
- Click Submit.
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:\Program Files (x86)\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 the Export Password.
The resulting certificate and key should be in the file companyname_auth.pfx that you'll 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.