Custom applications integration

Integrate ADManager Plus with your enterprise applications that support REST API or SOAP API to manage the identities in those applications. After configuring the application, you can use it as a data source and design automations for different identity management actions from ADManager Plus.

ADManager Plus also comes with prebuilt connectors for various applications. If the application you want to integrate is not found on this list, follow the steps below to integrate that application with ADManager Plus.

Steps to integrate ADManager Plus with a custom application

1. Navigate to Automation and 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 LDAP data mapping.
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. 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.
     • Access Token URL: Enter the OAuth server URL where the application can exchange the Authorization code for an Access Token.
     • 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.
   Note: ADManager Plus sends an authorization request to the Auth URL specified above along with the Client ID and Secret. The authorization server responds with an Authorization Code, which is then exchanged for Refresh and Access Tokens. The Access Tokens are then used to make API calls post which the user is redirected to the specified Callback URL.

   

   

   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.

6. Now, in the API Endpoint Configuration section, add the following:
   • Click the Endpoint Configuration tab to provide the endpoint details. To configure advanced settings follow these steps.
   • Endpoint URL: Enter the Endpoint URL.
   • Method: Choose either Get or Post for the HTTP request method.
   • Headers: Click and configure the respective HTTP headers.
   • Parameters: Cick 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
     • None - Default
7. Navigate to the Settings section and check the Repeat calling this Endpoint option to repeatedly call the API until you get the required response. From the drop-down menu, select the parameter and specify the increment value. You can also set a condition, which when satisfied calls the endpoint repeatedly.
8. Once done, click Test and Save. A response window will display all the requested elements.
Note:
• The elements in the response window must match with the ones in the schema.
• Only those elements in the leaf nodes can be selected in the Data Source - LDAP Attribute Mapping section.
• All those unique user attributes present in non-leaf nodes must be replaced.
9. Click Data Source - LDAP Attribute Mapping to match endpoints and to map AD LDAP attributes with the respective attributes in the custom application
Note: Click Add New Naming Format to create a new naming format for the user naming attributes in the custom application.
10. Enter the Configuration Name and Description and select the Automation Category from the drop-down menu.
11. In the Select Endpoint field, select the columns that are unique to users (employeeIdenifier, username, etc.) but hold the same value in all the endpoints.
12. In the Attribute Mapping field, select the attribute from the LDAP Attribute Name drop-down menu, and map it with the respective column in the custom application.
13. Click Save.

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.

Advanced endpoint configuration for nested endpoints

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

1. 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 above except for the step 6. 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: