Custom applications integration

Steps to integrate ADManager Plus with a custom application

1. Navigate to Automation and under Configurations, click Application Integrations.
2. Under Enterprise Applications, click the Custom Application tile to integrate a new application.
3. In the window that pops up, enter a suitable Name and Description, upload a Logo of the application, and click Save.
4. Click the custom application added in the previous step to configure the API authorization methods, endpoints, and webhooks.
5. In the Authorization section, select the Authorization Type from the drop-down, and select the appropriate option.



• No Auth

  Select No Auth as the authorization type if your request doesn't require authorization. On doing this, the authorization details will not be shared with the API client.

• API Key

  If you select API Key as the authorization type,

  • Enter the key name and value in the Key and Value fields respectively. Associate the key to a header/query parameter using the Add To drop-down menu and click Configure. You can refer to your application's API documentation for more details.
• Basic Authentication
  • If you select Basic Authentication as the authorization type, specify a Username and Password and click Configure.
• Bearer
  • If you select Bearer as the authorization type, enter your application's API key in the Token field and click Configure. The API key can be obtained by following the steps mentioned in your application's API documentation.
• OAuth 2.0

  If you select OAuth 2.0 as the authorization type, specify the following:

  • Header Prefix: Specify a prefix value for your authorization header.
  • OAuth 2.0 Grant Type: Authorization code is the default grant type. You can also choose Client Credentials as a grant type depending on the application.
  • Callback URL: The Callback URL is where you will be redirected after authentication. For the applications in the list, it is prefilled with ADManager Plus' URL.

    For example: http://{hostname}/OAuthCode.do. The hostname will be the machine on which the ADManager Plus instance is installed.

    While integrating a new application, this should be configured in the API provider's OAuth configuration.

  • Auth URL: Specify the Authorization Endpoint URL obtained from the application that you want to integrate while configuring the OAuth details.You can refer to the application's API document for more information.
  • Access Token URL: Enter the OAuth server URL where the application can exchange the Authorization code for an Access Token. The server URL will be the redirect URI of the application. Refer to the API documentation for the steps to get the redirect URI of the application you are integrating.
  • Client ID and Client Secret: Under Authorization, enter a valid ID and its secret key obtained from the application you want to integrate with ADManager Plus.
  • Scope: Scopes are defined in the API documentation of the application you are integrating. It limits the client's access to specific endpoints and determines if the client can only read or also write to those endpoints. Specify the scope values in ADManager Plus after referring to the scope values in the API documentation.
  • Client Authentication: You can use this option to choose if the Client Credentials have to be included in the Request Body or the Header. By default, Send Client Credentials Request Body will be chosen.
  • Click Advanced Options and choose the headers/query parameters from the Add To drop-down menu.

API endpoint configuration

To import the object data from any enterprise application, we need the API endpoints to obtain all the details of the objects that have to be imported. We can find the required API information in the application's API documentation or contact the support team of the application being integrated. Perform the steps given in the following sections after you complete the Authorization configuration.

Before proceeding to setup the endpoints, it's important to know that there are two types of endpoint configuration in ADManager Plus such as:

• Inbound Webhook
• Outbound Webhook

Depending on your organizational goals, you can configure anyone or both.

Inbound Webhook configuration:

This enables the transfer of data from the custom application to ADManager Plus. To configure this:

1. Click the Endpoint Configuration tab to provide the endpoint details as listed below. If required, you can configure multiple endpoints for a custom application using the + Add API Endpoint button. Now proceed to configure other fields.
   • Endpoint URL: Enter the endpoint URL. The endpoint URL will differ according to the operation that has to be performed and the type of data that has to be retrieved from the application.
     • For example: The endpoint URL to get user data will be different from the URL to fetch the group data. Refer to the API documentation of the application you are integrating with ADManager Plus
   • Method: Choose either Get or Post for the HTTP request method.
   • Headers: Click and configure the respective HTTP headers.
   • Parameters: Click and configure the query parameters.
   • Message type: Select the body message data type based on the type of API from the available options.
     • JSON - REST API
     • XML - SOAP API
     • x-www-Form-URLEncoded- Can be used for any type of API.
     • None - Default.

     Note: Follow these steps to configure advanced settings.

2. Navigate to the Settings tab and toggle the Repeat calling this Endpoint button on to repeatedly call the API until you get all the required data.
3. Select the type of action from the list given in the first drop-down box in the Repeat Call Configuration option.
4. In the next drop-down box, mention the pagination parameters to get the data in ordered sets until the whole dataset is fetched.
5. Enter the value of the pagination parameters in the value by box.
6. You can also set a condition using the Repeat Call Criteria option to specify how long an API needs to be called.
7. Once done, click Test and Save. A response window will display all the requested elements.
8. Click Data Source - LDAP Attribute Mapping to match endpoints and to map AD LDAP attributes with the respective attributes of the custom application.

   Note: Click Add New Naming Format to create a new naming format for the user naming attributes in the custom application.

   • Enter the Configuration Name and Description and select the Automation Category from the drop-down menu.
   • In the Select Endpoint field, check the custom application's endpoint box and in the Primary Key drop-down select the attribute that is unique to users (employeeIdenifier, username, etc.) but hold the same value in all the endpoints.
   • In the Attribute Mapping field, select the attribute from the LDAP Attribute Name drop-down menu, and map it with the respective attribute of the custom application.
   • Click Save.

How to use inbound webhooks

After configuring the inbound webhook, you can use it as a data source by clicking the Select More option under Select objects section of the automation in scheduled automations for different identity management actions from ADManager Plus.This enables us to perform the desired action available in automation on the list of objects imported through the inbound webhooks either once or periodically.

Advanced endpoint configuration for nested endpoints in inbound webhooks

For some API configurations we may have to configure multiple endpoints where the endpoints are dependent on others. For example, the first endpoint fetches all employee IDs in an organization and we need to hit another API for each employee ID received in the response to fetch the employee's details. In cases like these, configure the first API as a base endpoint (default type) and the second endpoint as dependent endpoint using the Advanced option.

Steps to configure the dependent endpoint

Toggle the Advanced button to on under the API Endpoint Configuration to fill in information when the endpoint is dependent on the previous API endpoint.

• In the Configuration Type drop-down, select the endpoint type. By default, the Base Endpoint option will be chosen. You have to change it to Dependent Endpoint.
• Select the relevant base endpoint from the available options in the Depends On drop-down menu, upon which the data for the current endpoint relies. Thus, the current endpoint will be called for each object received from the base endpoint.
• To utilize a field from the response of base endpoint, use the macros of base endpoints listed by typing in the % symbol or clicking .

Steps to configure a SOAP API endpoint

You have to follow all the steps as mentioned in the inbound webhook configuration section except for this step. When the message type is set to XML, ADManager Plus requires the Response Parser CSV file. This file helps in filtering only the required data from the endpoint's XML response. The filtered attributes can then be linked to the AD LDAP attributes.

The CSV should have three columns as given below:

• columnName: Desired name for the data to be filtered from the XML response.
• xPath: Location from where the data is to be fetched.
• isParameter: If set as 1, it will become an iterating attribute during repeated calls. For example, if a node named Page in the message body needs to be incremented by 1 during each call, the isParameter for Page is set as 1.

For example, as shown in the below images, value for the columnName Worker ID as highlighted in the sample CSV file is extracted from the attribute Worker_ID(value:100001) as highlighted in the sample XML response file. This value can be later mapped to the AD LDAP attribute employee ID.

Sample CSV file:

Sample XML response:

Outbound webhook enables you to send the changes made in AD using ADManager Plus to the custom application. To configure outbound webhooks,

1. Under Outbound Webhook, click <Custom application>Webhook Configuration.
2. Click + Add Webhook.



3. Enter a name and description for this webhook.
4. Refer to the custom application's API references and decide on the action that has to be performed and the headers, parameters, and other requirements that will be needed.
5. Select the HTTP method that will enable you to perform the desired action on the endpoint from the drop-down menu.
6. Enter the Endpoint URL. It will vary according to the data that you want to transfer to the application
   • For example: The endpoint URL to update user attributes will be different from the endpoint URL used to update the recently changed passwords of users. Refer to the API documentation of the application that you are integrating with ADManager Plus.
7. Configure the Headers, Parameters, and Message Type in the appropriate format based on the API call that you would like to perform.
8. Click Test and Save. A pop-up window will then display a list of users and groups.
9. Select the desired users and groups over which this API request has to be tested and click OK. This will make a real-time call to the endpoint URL, and the selected objects' values will be updated.
10. A pop-up window will then display the webhook response and request details.

How to use macros-supported attributes

• You can either type in the % symbol or click the to add the macros of your choice in the Endpoint URL, Header, and Parameters fields.
• If you have to add the macros in the message body, click Select Macros.

How to use outbound webhooks

After you configure an outbound webhook for the required action, use it as a block in an orchestration template. The configured orchestration template can be executed using event-driven automation, scheduled automations, automation policies, and can also be applied directly on the desired users to perform a sequence of actions on them (Management > Advanced Management > Orchestration).