Generating a Certificate Signing Request

Overview

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.

There are two ways you can generate the WS Certificate which are listined below, The Automated process would be for ADP Partners and the Manual process which will be for ADP Clients. 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.

Disclosure

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).

Automated Process Steps (Partner Process Steps)

To create your Mutal SSL Certificate via Developer Self Service portal, follow these steps:

1. Login into the Developer Self Service Portal with your Partner Developer Account 
2. Once Logged in click on "Certificate" on the left hand side
   
   
    
3. On the next page click on "Request Certificate"
   Note: If you already have a valid certificate you can also use this same page to upload your existing certificate.
   
   
    
4. This will take you to the page below where you will be required to fill out all field. Once completed click on "Next".
   
   
    
5. On the next screen you will be able to copy and save your .key file. Click on "Copy" then click on "Ok, I copied my key".
   Note: You will not be able to move forward and click on "Ok, I copied my key" until you first click on "Copy". Save you key as you will not be able to go back and get it after you move past this step. 
   
   
    
6. Click on "Done" on the next page.
   
   
    
7. On the next page now that your Certificate is created you can now donload your .pem file by clicking on "Download".
   
   

   Your certificate will be valid for two years from the date created and can be used across all of your projects both developement and production. When your certificate is about to expire not only will the person be notified that created the certificate but so will any other user assoicated with your project(s) within the Developer Self Service Tool. 

    

Manual Process Steps (Client Process Steps)

To complete a Certificate Signing Request, do the following:

1. 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. 
2. To install OpenSSL, follow the instructions in the Install Wizard.
3. Open cmd.exe.
4. 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).
5. 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.

    

6. 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)
7. After you have created your CSR, 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.

     
      
8. 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).
9. 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.
10. 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.