With , applications can use SPML documents to look up, retrieve and update directory data in Active Directory, Azure AD, and AD LDS. converts XML elements and attributes into commands used to make changes to Active Directory and retrieve data from Active Directory. can also convert the response received from Active Roles or Active Directory to XML format. These conversions are based on and are in compliance with the OASIS SPML v2 - DSML v2 Profile specification.
runs as a Web application on a Web server running Microsoft Internet Information Services (IIS), and uses SOAP over HTTP to transmit and receive directory requests from client computers.
The environment includes the following components:
-
Clients that use SPML v2: These clients are applications that manage directory objects (for example, user accounts). A client issues SPML requests that describe operations to be performed on the directory object and send these requests to .
-
: Receives and processes client requests, and returns a response to the client.
-
Active Roles: In proxy mode, this is the endpoint for provisioning requests and the actual software that manages directory objects.
-
Active Directory, Azure AD, or AD LDS: In proxy mode, can access Active Directory or Azure AD domains and AD LDS instances that are registered with Active Roles as managed domains, Azure AD tenants, and managed AD LDS instances, respectively. In direct access mode, can access the domain controller or the AD LDS instance defined in the SPML.Config file. For more information, see “Configuring ” later in this document.
The following diagram illustrates the flow of requests and responses through the environment components:
Figure 161: Flow of requests and responses through the environment components
As shown in the diagram, the client/ communications are based on the simple request/response protocol.
In proxy mode, works in the following way:
-
A client issues a well-formed SPML request using the SOAP over HTTP protocol. This request goes to a server running IIS, where it is routed to .
-
examines the request for conformance to the SPML format.
-
If the request complies with the SPML format, the submits the request to Active Roles. Based on the client request, Active Roles retrieves or modifies data in Active Directory, Azure AD, or in AD LDS.
-
After performing the requested operation, Active Roles sends the result of the operation back to .
-
then processes this result data and sends the result of the performed operation back to the client in the form of an SPML response.
In direct access mode, works in the following way:
-
A client issues a well-formed SPML request using the SOAP over HTTP protocol. This request goes to a server running IIS, where it is routed to .
-
examines the request for conformance to the SPML format.
-
If the request conforms to the SPML format, retrieves or modifies the relevant data in Active Directory or in AD LDS (ADAM).
-
sends the result of the performed operation back to the client in the form of an SPML response.
If the client request does not conform to the SPML format, the client receives an SPML response that describes the encountered error.
Configuration settings allow the administrator to configure and its schema in order to adjust the behavior. Administrators can, for example, specify the required managed objects and attributes in the schema, or choose the type of execution (disabling or deprovisioning objects) for the Suspend operation.
The configuration settings can be found in the SPML.Config file located in the Web subfolder of the installation folder. The SPML.Config file contains data in the XML format. You can open and edit the configuration file with a common text editor, such as Notepad.
NOTE: After you modify configuration settings,restart the IIS application pool for the website for the changes to take effect.
The following table describes the XML elements used in the configuration file.
Table 92: XML elements used in the configuration file
service |
configuration |
In proxy mode, specifies the name of the computer running the Active Roles Administration Service. In direct access mode, specifies the name of the AD domain controller or AD LDS server. The name of the AD LDS server must be in the form <servername:portnumber>. |
adsiProvider |
configuration |
Specifies the progID of the ADSI Provider. In proxy mode, the progID is EDMS. In direct access mode, the progID is LDAP. |
schemaFile |
configuration |
Contains the name of the file that defines the DSML Profile schema for . By default, the file name is SPMLSchema.Config. The schema file must be located in the same folder as the SPML.Config file. |
defaultMaxSelect |
search |
Specifies the maximum number of search results that can return without page splitting. The default value is 1000. |
pageSize |
search |
Specifies the maximum number of search results per page. The default value is 25.
NOTE: If pageSize is set to 0, returns search results without page splitting. |
class |
password |
Contains the LDAP display name of the schema class of objects on which is expected to perform the Password Capability-related operations such as setPassword and expirePassword. |
class |
suspend |
Contains the LDAP display name of the schema class of objects on which is expected to perform the Suspend Capability-related operations such as suspend, resume, and active. |
suspendAction |
suspend |
Possible values: disable or deprovision. The default value is disable.
If suspendAction is set to disable, disables the specified user account on the target.
If suspendAction is set to deprovision, deprovisions the specified user account in accordance with the deprovisioning policies defined by Active Roles. |
checkOutput |
configuration |
Possible values: true or false. The default value is false.
true causes to check the string attribute values retrieved from the underlying directory before adding them to a response. If an attribute value contains illegal characters that could break the XML parser on the client side, converts the attribute value to the base64binary format and then adds the result of the conversion to the response. Note that this option may result in performance degradation of as checking every attribute value is a resource-intensive operation.
false causes not to check the string attribute values retrieved from the underlying directory. An attribute value is added to the response without any conversion even if the value contains illegal characters.
NOTE: In accordance with the XML specification, the legal character range is as follows: #x9 | #xA | #xD | [#x20-#xD7FF] | [#xE000-#xFFFD] | [#x10000-#x10FFFF]. With checkOutput set to true, ensures that attribute values in a response contain only characters from the legal character range. |
The following is an example of the configuration file for configured to operate in proxy mode. If and the Active Roles Administration service are installed on the same computer, the default configuration settings look as follows:
<?xml version="1.0"?>
<configuration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns="urn:quest:names:SPMLProvider">
<service>localhost</service>
<adsiProvider>EDMS</adsiProvider>
<schemaFile>SPMLSchema.Config</schemaFile>
<capabilities>
<search>
<defaultMaxSelect>1000</defaultMaxSelect>
<pageSize>25</pageSize>
</search>
<password>
<appliesTo>
<class>user</class>
</appliesTo>
</password>
<suspend>
<appliesTo>
<class>user</class>
</appliesTo>
<suspendAction>disable</suspendAction>
</suspend>
</capabilities>
<checkOutput>false</checkOutput>
</configuration>