Before you can establish a connection, you must you must complete two key prerequisites:

1. Obtain a custom OAuth application and its associated credentials from ADP.
2. Generate a client certificate for Mutual SSL Authentication.

ADP requires Mutual SSL Authentication, meaning you must provide a client certificate for authentication. This certificate consists of:

• A Private Key to sign authentication requests.
• A Public Certificate issued by ADP to verify requests.

Mutual SSL helps establish a secure, trusted connection by requiring both parties to exchange certificates and verify each other's identities. Since ADP issues these files separately, you must retrieve both before configuring your connection.

For more details, see ADP Developer Resources.

You can retrieve these files using one of three methods, depending on how your organization purchased ADP APIs:

• ADP Partners: Automated process through the Developer Self-Service Portal.
• ADP Clients: Manual Certificate Signing Request (CSR) generation and submission through the ADP Certificate Signing Tool.
• ADP API Central users: Automated process through API Central.

Regardless of the retrieval method, you must combine the Private Key and Public Certificate into a single PFX or PEM file before configuring your connection.

Important Security Note: Your Private Key and combined certificate files (PFX or PEM) are sensitive credentials. Store them securely, and do not share them. Anyone with access to these files could impersonate your application.

Common mistakes to avoid:

• Attempting to retrieve the Private Key after generation. It can only be copied once.
• Using an incorrect organization name when creating the certificate. This name must match the organization name registered with ADP.
• Failing to combine the Private Key and Public Certificate into a supported format. The connection will fail if this step is skipped.
• Allowing certificates to expire. ADP sends a renewal notice 60 days before expiration.

Note: If you are manually generating a CSR, you must submit the CSR to ADP and download the signed certificate before combining it with your private key. For more information, see ADP Developer Resources.

Retrieving Your SSL Certificate from the Developer Self-Service Portal

To retrieve your SSL certificate, follow these steps:

1. Log in to the ADP Developer Self-Service Portal using your Partner Developer Account.
2. Navigate to the Certificate section.
3. Click Request Certificate.
4. Complete the required fields and click Next.
5. On the next screen, click Copy to save your Private Key (.key file).
6. After copying the key, click Ok, I copied my key.
7. Click Done, then download your Public Certificate (.pem file).

Important: The Private Key file is only available at the time of generation. You must copy and store it securely, as you are not be able to retrieve it again later.

Your certificate is valid for two years. ADP will send a renewal notification 60 days before expiration.

Retrieving Your SSL Certificate with the Manual CSR Process

If your organization uses the manual Certificate Signing Request process:

1. Follow the instructions in the ADP Certificate Signing Tool to generate your CSR and private key.
2. Submit the CSR and download the signed certificate from ADP once it's approved.
3. Proceed to combine the private key and public certificate into a PFX or PEM file as described below.

Retrieving Your SSL Certificate from API Central

If your organization uses API Central:

1. Log in to API Central and navigate to your project.
2. Select Certificate from the menu or from Step 1 of the project setup.
3. Follow the guided process to generate and download your Private Key and Public Certificate.
4. Store the private key securely.

After retrieving both files, proceed to combine them into a supported format.

Combining the Private Key and Public Certificate

Before using the certificate, you must combine the Private Key and Public Certificate into a single file format that the component supports. If your organization uses ADP API Central, this manual combination process may not be required.

Option 1: Create a PFX File (Default)

If using the default setting for the SSLClientCertType property (PFXFILE), convert your Private Key and Public Certificate into a .pfx file.

1. Run the following command in OpenSSL:
   

   openssl pkcs12 -export -out adp.pfx -name "<OrgName> Mutual SSL" -inkey <your-private-key>.key -in <your-public-certificate>.pem

   Replace "<OrgName>" with your organization name. This string must match exactly the organization name used when registering with ADP and appears during certificate generation in the Developer Self-Service Portal.

   Next, replace "<your-private-key>.key" and "<your-public-certificate>.pem" with the actual file paths to your SSL private key and certificate.

2. When prompted, enter an export password. Use this password as the value for the SSLClientCertPassword property, and use the full file path of the generated .pfx file as the value for the SSLClientCert property when configuring the connection.

Using a Base64-Encoded PFX File (PFXBLOB)

If using the PFXBLOB type, you must convert the .pfx file into a Base64 string before using it in the connection settings.

1. Run the following command to encode the .pfx file:
   

   openssl base64 -in adp.pfx -out adp_base64.txt

2. Copy the entire contents of adp_base64.txt into the SSLClientCert property when configuring the connection.

Option 2: Create a PEM File (PEMKEY_FILE or PEMKEY_BLOB)

If using the PEMKEY_FILE or PEMKEY_BLOB certificate type, follow one of the methods below to combine your Private Key and Public Certificate into a single PEM-formatted file.

You can do this manually by opening both privateKey.key and publicCert.pem in a text editor:

1. Copy the Private Key contents.
2. Paste the Public Certificate contents directly below the Private Key in the same file.
3. Save the file as combined_cert.pem.

Alternatively, for Linux users, run the following command in a terminal from the directory where your Private Key and Public Certificate files are stored:

cat privateKey.key publicCert.pem > combined_cert.pem

If using PEMKEY_FILE, set the full file path of combined_cert.pem as the value for the SSLClientCert property when configuring the connection.

If using PEMKEY_BLOB, you have two options:

• Open combined_cert.pem in a text editor and copy the entire contents directly into the SSLClientCert property.
• Or, encode the file as Base64 using the following command, and copy the output into the property:
  

  openssl base64 -in combined_cert.pem -out cert_base64.txt

Then, copy the full Base64 string from cert_base64.txt into the SSLClientCert property.