Troubleshoot app integrations with ADP

Here are the frequent issues you may face while your integration testing, & immediate steps to follow

Business to Business App Flow (Client Credentials)

Steps to do a client credentials flow:

1. Loading the certificates
2. Access Token call
3. Run feature call 

Step 1: Loading the Certificates

1. Submit a CSR (Certificate Signed Request) and get the signed certificates from ADP
2. Load the certificates in the tool (say SOAPUI) or to Linux machine (In this article, CURL scripts are provided to run the calls from UNIX command line.)

Step 2: Access Token call

1. Do Access token call from command line (say puTTY):
   • Ensure you have the following information ready:
     • CERT_LOC : Location of the certificate
     • KEY_LOC : Location of the key
     • CLIENT_ID : client id provided by ADP
     • CLIENT_SECRET : client secret provided by ADP
     • TOKEN_ENDPOINT : The end point URL provided by ADP
   • Run the below CURL command, (POST Call):
     curl -ks –cert $CERT_LOC –key $KEY_LOC -o tokenResponse -d “client_id=${CLIENT_ID}&client_secret=${CLIENT_SECRET}&grant_type=client_credentials” ${TOKEN_ENDPOINT}
   • Now extract the access token from the response “tokenResponse” using the below command:
     ACCESS_TOKEN=`grep ‘”access_token”:”‘ tokenResponse | sed ‘s/.*access_token”:”\(.*\)”,*/\1/’`
2. Issues you may encounter & debugging while you run Access Token call:
   ERROR : Proper client SSL certificate was not presented

   • Ensure that proper certificates are loaded/ The password for the certificates file is correct

   ERROR : Invalid_client/Failed to get client credentials/ HTTP Response Code 401 – Unauthorized

   • Ensure that the supplied Client Id and Client Secret are correct

   ERROR : Invalid_request/Missing or invalid grant_type/ HTTP Response Code 500 – Internal Server Error

   • Check the “grant_type” value is “client_credentials” or the payload of access token call is correct

Step 3: Run feature call

1. Run feature from command line (say puTTY):
    
   • Give the header “Authorization” and the value is “Bearer ACCESS_TOKEN” (ACCESS_TOKEN should be the access token obtained in access token call) along with other required headers for the feature call
    
2. Issues you may encounter & debugging while you run feature call:
   ERROR : Invalid_request/Validation error/HTTP Response Code 401 Unauthorized

   • Check you are passing the “Authorization” header with value as “Bearer ACCESS_TOKEN” & it is not expired.

   ERROR : Invalid_scope/ Scope you are requested for is not available/ HTTP Response Code 403

   • Ensure that the scope you are trying for is made available for your ClientId and Client secret (Contact ADP for getting this fixed)
   • The product is not allowing you to do this specific operation.
   • There might be some internal problem, please contact ADP

Business to Consumer App Flow (Authorization Code)

Steps for an integration test of Authorization code flow:

1. Session call
2. Authorize the session using user id and password
3. Allow the consent if not
4. Do the Access token call
5. Do the feature call

Step 1: Session call

1. Run Session call from Unix command line
   • Ensure you have the following information ready:
     • CERT_LOC : Location of the certificate
     • KEY_LOC : Location of the key
     • CLIENT_ID : client id provided by ADP
     • CLIENT_SECRET : client secret provided by ADP
     • TOKEN_ENDPOINT : The end point URL provided by ADP
     • REDIRECT_URI : Redirection URL
     • USER : username provided by ADP
     • PASSWORD : password provided by ADP
   • Run the below CURL command, (GET Call):
     SESSION_ID=`curl -k -s “$TOKEN_ENDPOINT?response_type=code&client_id=$CLIENT_ID&redirect_uri=$REDIRECT_URI&scope=openid%20api” | perl -p -e ‘/.*sessionID” value=”(([a-zA-Z0-9]+)-.*)”.*/; $_=””; if (defined $1) { print $1; break; }’`
   • Now session id will be available in SESSION_ID variable
2. Issues you may encounter & debugging while you run session call:
   ERROR : HTTP Response Code 302 / Invalid request

   • Check your Client ID / redirect URI is correct, you have to use the same redirect URI you have provided to ADP 

Step 2: Authorize Session Call

1. Run Authorize Session call:
   • Run the below CURL command, (POST Call):
     curl -k -is -X POST -d “sessionID=$SESSION_ID&action=Login&username=$USER&password=$PASSWORD” -o loginResponse $TOKEN_ENDPOINT
   • Fetch the response code & sessionCode from the response “loginResponse”:
     HTTP_CODE=`head -1 loginResponse | sed ‘s/.* \([0-9]*\) .*/\1/’`
     echo ” HTTP_CODE=${HTTP_CODE}”
     SMSESSION=`cat loginResponse | perl -p -e ‘/(SMSESSION=”.*”)/; $_=””; print $1’`
     echo ” ${SMSESSION}”
2. Issues you may encounter & debugging while you run Authorize Session call:
   ERROR : HTTP Response Code 400/ oAuth session has expired

   • Ensure you are using the session id generated in the authorize session call for this user, is not expired

   ERROR : HTTP Response code 401/ Incorrect login credentials

   • Please use the login credentials provided by ADP

   ERROR : HTTP Response code 302 and “error=invalid_request” in response Error

   • Check the Post call body is correct

Step 3: Allow Consent call (If Step2 response code is 200)

1. Run Allow consent call using SESSION_ID and SMSESSION values, (POST call):
   CODE=`curl -k -is -X POST -d “sessionID=$SESSION_ID&action=Confirm” -b ${SMSESSION} $TOKEN_ENDPOINT | perl -p -e ‘/code=(.*)\&/; $_=””; print $1’`

   • Now access code will be saved in variable CODE which will be used to run the access token call

2. Issues you may encounter & debugging while you run Allow Consent call:
   If you are not able to allow the consent

   • Check your POST call JSON body has correct data and ‘action’ has a valid value

Step 4: (If Step 2 response code is 302)

1. Extract the access code from the Step 2 response:
   • Run the below commands to extract the access code:
     REDIRECT_URL=`grep ‘^Location: ‘ loginResponse | sed ‘s/^Location: //’`
     CODE=`grep ‘^Location: ‘ loginResponse | perl -p -e ‘/code=(.*)\&/; $_=””; print $1’` 

Step 5: Access Token call

1. Run the Access Token call:
   • Run the below CURL command, (POST Call):
     curl -k -is –cert $CERT_LOC –key $KEY_LOC -d ‘client_id=’$CLIENT_ID’&client_secret=’$CLIENT_SECRET’&code=’$CODE’&redirect_uri=’$REDIRECT_URI’&grant_type=authorization_code’ -o tokenResponse $TOKEN_ENDPOINT
   • Extract the access token from the response “tokenResponse”:
     ACCESS_TOKEN=`grep ‘”access_token”:”‘ tokenResponse | sed ‘s/.*access_token”:”\(.*\)”,*/\1/’`
2. Issues you may encounter & debugging while you run Authorize Session call:
   ERROR : Invalid_client/Failed to get client credentials/ HTTP Response Code 401 – Unauthorized

   • Ensure that the supplied Client Id and Client Secret are correct

   ERROR : Invalid_request/Missing or invalid grant_type/ HTTP Response Code 500 – Internal Server Error

   • Check the “grant_type” value is “client_credentials” 

Step 6: Run feature call

1. Run feature call from command line (say puTTY):
    
   • Give the header “Authorization” and the value is “Bearer ACCESS_TOKEN” (ACCESS_TOKEN should be the access token obtained in access token call) along with other required headers for the feature call

Other Issues

• ERROR : 400 – Bad request

  • Check you are passing all the required headers and valid values for the specific call
  • Check the JSON payload is as per schema

  ERROR : 412 – Pre condition failed

  • Make sure you are sending the request correctly with all the required headers
  • Ensure you are not sending any unwanted headers

  ERROR : 404 – Not found

  • The data you are looking for is not found at product level.