Custom applications integration

Steps to integrate ADManager Plus with a custom application

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



• No Auth

  Select No Auth as the Authorization Type if your request doesn't require authorization, then click Configure. If you do 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 with a header or query parameter using the Add to drop-down 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.
  • Grant Type: Authorization code is the default Grant Type, but you can choose Client Credentials as the Grant Type depending on the application.
  • Callback URL: The Callback URL is where you will be redirected after authentication. For the applications on 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 with 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 with which you are integrating.
  • Client ID and Client Secret: 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 with which 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 in Request Body will be selected.
  • Advanced Options: Click this option and choose the headers or query parameters from the Add to drop-down.
• API-based Authorization:

  While integrating custom applications with ADManager Plus, you now have the option to get the authentication tokens from API endpoints for authorization. This is supported in the <API Key> and <Bearer> authorization types. To utilize this option,

  1. Select the API Key or Bearer (according to the integrating application's authorization standard) option from the Authorization Type drop-down.
  2. In the Value field, click the webhook icon as highlighted in the image.
  3. Configure the API authentication token in the endpoint URL or add it either in headers or in parameters.
  4. Click Test and Configure to test the webhook and proceed to set this as an authorization method.

  Note: This will also be listed as a macro in inbound and outbound webhooks in the Select Macro window pop-up.

  

  1. Click the icon to add a authentication token webhook

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

1. Under Inbound Webhook, click <Custom application> Endpoint Configuration to provide the endpoint details listed below. If required, you can configure multiple endpoints for a custom application using the + Add API Endpoint button.

   

   • 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 used to get user data will be different from the URL used 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 from the available options based on the API type:
     • JSON: This option is for REST APIs.
     • XML: This option is for SOAP APIs.
     • None: This is the default option.

     Note: Follow these steps to configure advanced settings.

2. For the Repeat Call Configuration option, select the type of action from the list given in the first drop-down. In the adjacent drop-down, mention the pagination parameters to get the data in ordered sets until the whole dataset is fetched. Enter the value of the pagination parameters in the Value field.
3. You can also set a condition using the Repeat Call Criteria option to specify how long an API needs to be called.
4. Once done, click Test & Save. A response window will display all the requested elements.
5. Click Data Source - LDAP Attribute Mapping to match endpoints and to map AD LDAP attributes with the respective attributes of 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. If you have configured dependent endpoints, then select the unique attribute for those endpoints as well.
   • In the Attribute Mapping field, select the attribute from the LDAP Attribute Name drop-down and map it with the respective attribute of the custom application.

   Note: Click Add New Format to create a new format for the user naming attributes in the custom application. In the Custom Naming format pop-up window, fill in the details and click Save. You can also add macros while specifying format values if necessary.

6. Click Save.

How to use inbound webhooks

After configuring an inbound webhook, you can use it as a data source in scheduled automations for different identity management actions in ADManager Plus. To do so, navigate to Automation, click + Create New Automation, and use the Select More option under the Select objects section. This enables you to automate the action you want to perform on the list of objects imported through the inbound webhook either once or periodically.

Advanced endpoint configuration for nested endpoints with inbound webhooks

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

Steps to configure a 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 Endpoint Configuration section, toggle the Advanced option on to fill in information when an endpoint is dependent on a previous API endpoint.
• From the Configuration Type drop-down, select the endpoint type. By default, the Base Endpoint option will be selected. You have to change it to Dependent Endpoint.
• From the Depends On drop-down, select the relevant base endpoint upon which the data for the dependent endpoint relies. Thus, the dependent endpoint will be called for each object received from the base endpoint.
• To utilize a field from the response of the base endpoint, use the base endpoint macros listed by typing % or clicking .

Steps to configure a SOAP API endpoint

You have to follow all the steps 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 file should have three columns as given below:

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

For example, as shown in the images below, the 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. This value can be mapped to the AD LDAP attribute employeeID later.

Sample CSV file:

Sample XML response:

Click here to download a sample CSV file.

Value-based indexing

Value-based indexing is a technique used to efficiently locate and retrieve data by applying specific conditions to its values. This approach enables users to create a specific xPath, allowing them to efficiently find entries that match defined criteria.

As shown in the images below, the value for the Company column in the sample CSV file is taken from the Organization_Name attribute (value: company1), highlighted in the second image. Since there are multiple entries of Worker__Organization_Data, an additional condition (Organization_Subtype_ID='company') is set to specify the correct Worker_Organization_Data. This means that the final value is selected based on a condition tied to another specific value.

This xPath filters the data under Worker_Organization_Data by checking if the Organization_Subtype_ID equals Company. It then returns the Organization Name of the matching condition.

To create a condition, follow these steps:

1. Identify the data field you want to filter (e.g., Organization_Subtype _ID).
2. Specify the value to match (e.g., Company).
3. Apply the condition in the form [?(searchpath = 'value')] to filter based on the selected attribute.

This approach enables creation of a precise xPath and results based on a defined condition.

An outbound webhook enables you to send the changes made in AD using ADManager Plus to the custom application. To configure an outbound webhook:

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, decide on the action that has to be performed, and identify the API that is required to perform the action.
5. From the drop-down, select the HTTP method that will enable you to perform the desired action on the endpoint.
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 used 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 for the action 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 on which this API request has to be tested and click OK. This will make a real-time call to the endpoint URL to execute the configured API's function on the selected objects.
10. A pop-up window will then display the webhook response and request details. If you are unable to receive the response for the API request, ensure that the mapped attributes, headers, parameters, and request message are correct.

Note: In the webhook response window, you can modify the data type or format of the attribute value fetched by the API call by using the edit option.

For example: The date format used in the integrated app might be different from the date format used in ADManager Plus. To resolve this, use the edit option in the response window to modify the date format.

How to use attributes supported by macros

• You can either type % or click to add the macros of your choice in the Enter a URL, Headers, 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 automations, scheduled automations, or automation policies. It can also be applied directly to the desired users to perform a sequence of actions on them under Management > Advanced Management > Orchestration.