Integrating ADSSP with ADCSP Using Webhooks for AD User Account Unlock Synchronization
Overview
This article explains how to integrate AD Self Service Portal (ADSSP) with AD Connect Sync Portal (ADCSP) using Webhooks. The integration allows ADSSP to notify ADCSP whenever a user account is unlocked, enabling ADCSP to update the corresponding object automatically.
Prerequisites
Before proceeding, ensure that:
- ADCSP and ADSSP are installed and accessible.
- You have Administrator access to both applications.
- Network connectivity exists between the ADSSP server and ADCSP server.
- HTTPS communication is allowed between both applications.
Workflow
The integration consists of the following steps:
- Register an application in ADCSP.
- Obtain the Access URL, Access Token, and Signing Secret.
- Configure a Webhook Endpoint in ADSSP.
- Map the webhook fields and event transformation in ADSSP.
- Verify webhook delivery logs once you start sending requests from ADSSP.
- Verify application logs in ADCSP once you start receiving requests in ADCSP.
Step 1: Register an Application in ADCSP
- Open the ADCSP Admin Login page in your browser.
- Log in as an Administrator.
- Navigate to: System → App Registration
- A list of registered applications will appear.
- Click New App button.
Configure Application Details
- Specify the values for New App:
Setting | Value |
App Name | Enter a friendly name for the application |
Permissions | Select ADCSP.OBJECT.UPDATE |
App Status | Live |
Payload Signing | Enabled |
- Payload Signing: When Payload Signing is enabled, ADCSP generates an HMAC-SHA256 hash using the received request payload and the configured signing key. The generated hash is then compared with the value provided in the request's X-Hash-Header header. If the values match, the request is considered authentic and the payload integrity is verified. This mechanism helps detect payload tampering and ensures that the request originated from a party possessing the signing key.
Step 2: Save Application Credentials
- Click Next.
- The App Details dialog will appear.
You will be provided with:
- Access URL
- Access Token
- Signing Secret (Signing Key)
Important Note: These credentials are displayed only once. Copy and store them securely before leaving this page. If they are lost, they cannot be retrieved and must be regenerated, which may disrupt existing integrations. These values will be required while configuring Webhooks in ADSSP.
Step 3: Configure Webhook in ADSSP
- Open the AD Self Service Portal (ADSSP) application and login as an Administrator.
- Navigate to: System → Webhooks.
The Webhooks management screen will open as shown below:
- Click New Endpoint button.
Step 4: Configure Webhook Endpoint
- Specify the following settings:
Setting | Value |
Webhook Name | Enter a friendly name |
Enabled | Checked |
Target URL | Use the Access URL copied from ADCSP App Details |
Header Name | X-Hash-Header |
Header Mechanism | HMAC-SHA256 |
Example Target URL
Note: Replace the above URL with the Access URL generated by your ADCSP application registration in step # 2 above.
Step 5: Configure Events & Payloads
- Navigate to the Events & Payloads tab.
- Select the following event:
ADSSP.USER.ACCOUNT.UNLOCK
This ensures that a webhook request is generated whenever an Active Directory user account is unlocked through ADSSP.
Step 6: Configure Field Mapping
- Open the Field Mapper tab.
- By default, two mappings are displayed as shown below:
- Locate the Target Field.
- Target Field Name: userupn
- And modify it to: ObjectIdentifier
This allows ADCSP to correctly identify the object that needs to be updated.
Step 7: Configure Value Transformation
- Click the
button next to the mapped field named “action”. - It will open Value Transformation dialog box.
- Under Value Transformation, configure the following:
Source Value | Target Value |
ADSSP.USER.ACCOUNT.UNLOCK | ADCSP.OBJECT.UPDATE |
This transformation converts the ADSSP event into an ADCSP action that updates the corresponding object.
Step 8: Verify Webhook Delivery
After configuration is complete:
- Unlock a user account through ADSSP.
- Navigate to: System → Webhooks → Delivery Logs
Successful entries confirm that the webhook was delivered and processed by ADCSP.
Step 9: View Application Logs (Optional)
- Within the registered application in ADCSP, click: App Logs to verify that the requests are received from the ADSSP.
This section displays all requests and activities related to the registered application and can be used for troubleshooting.
Troubleshooting
If synchronization does not occur:
- Verify that the Target URL matches the Access URL generated in ADCSP.
- Confirm that the Access Token and Signing Secret are correctly configured.
- Ensure Payload Signing is enabled on both sides.
- Verify that the header is configured as:
X-Hash-Header
using the HMAC-SHA256 mechanism.
- Review:
- ADCSP → App Logs
- ADSSP → Delivery Logs
- Confirm network connectivity and HTTPS access between the ADSSP and ADCSP servers.
Result: After completing the above configuration, every AD User Account Unlock event generated in ADSSP is securely transmitted via Webhooks to ADCSP. ADCSP validates the HMAC signature, authenticates the request using the Access Token, and performs the ADCSP.OBJECT.UPDATE action, providing a reliable integration bridge between the two applications.