The directory abstraction layer provides a logical view of the Identity Vault data. To support access by third-party software applications, the directory abstraction layer includes a Web service endpoint called the VDX Web Service. This endpoint lets you access the attributes associated with entities defined in the directory abstraction layer. It also lets you perform ad hoc searches for entities and execute predefined searches called global queries. You can think of global queries as stored procedures for LDAP.
This Appendix describes the programming interface for the VDX Web Service.
You can access the VDX Web Service endpoint using a URL similar to the following:
http://server:port/warcontext/vdx/service?test
For example, if your server is named “myserver”, your identity applications is listening on port 8080, and your User Application war file is named “IDMPROV”, the URL would be:
http://myserver:8080/IDMProv/vdx/service?test
You can also access the SOAP endpoint by going to the Administration within the identity applications. To do this, you need to select the Application Configuration tab, then select Web Services from the left-navigation menu. After selecting Web Services, pick the Web Service endpoint you want from the list.
WARNING:The test page is disabled by default. Since some of the methods allow data to be updated, the test page presents a potential security vulnerability and should not be allowed in a production environment. For details on enabling the test page, see the instructions provided for the Role Service in Enabling the Test Page.
You can access the WSDL for the VDX Web Service using a URL similar to the following:
http://server:port/warcontext/vdx/service?wsdl
For example, if your server is named “myserver”, your identity applications is listening on port 8080, and your User Application war file is named “IDMPROV”, the URL would be:
http://myserver:8080/IDMProv/vdx/service?wsdl
Before using the Web Service, you need to use the WSSDK tool or another SOAP tool kit to generate the stub classes. To allow your code to find the stub classes, you also need to add the JAR that contains the stub classes to your classpath.
If you want to use the NetIQ WSSDK tool, you can generate the client stubs by extracting the WSDL and running the wsdl2java utility. For example, you could run this command to generate the stubs in a package called com.novell.ws.client.vdx:
"C:\Program Files\Java\jdk1.6.0_31\bin\java" -cp "../lib/wssdk.jar;../lib/jaxrpc-api.jar";"../lib/mail.jar";"../lib/activation.jar";"c:\Program Files\Java\jdk1.8.0_162\lib\tools.jar"; com.novell.soa.ws.impl.tools.wsdl2java.Main -verbose -ds gensrc -d C:\ -noskel -notie -genclient -keep -package com.novell.ws.client.vdx -javadoc vdx.wsdl
You can change the wsdl2java parameters to suit your requirements.
The VDX Web Service supports two levels of security, one that restricts access to Provisioning Administrators and another that restricts access to the authenticated user. The default setting restricts access to all operations to the Provisioning Administrator.
You can modify the settings for security configuration in the ism-configuration.properties file, located by default in the /netiq/idm/apps/tomcat/conf directory. . Each property can be set to true or false. A value of true locks down the operation, whereas a value of false opens up the operation.
You can open up the VDX Web Service to authenticated users by setting the VirtualDataService/soap property to false. To open up a particular operation to authenticated users, you need to set the property for that operation (VirtualDataService/soap/operation) to false as well. If you set all of the properties to false, you can open up all operations to authenticated users. The operation names are the same as the names of the methods supported by the service.
Example To ensure that the security configuration opens up all operations within the VDX Web Service, the ism-configuration.properties file must have the following setting:
VirtualDataService/soap = false
To restrict globalQuery, change the VirtualDataService/soap/globalQuery to true in the ism-configuration.properties file.
Even though the service does not require the Administrator credentials since you set the VirtualDataService/soap property to false, the globalQuery operation will still require the Administrator credentials since you set a property for the operation to true.