Adaxes SPML Provider

The SPML standard allows SPML-compliant applications to exchange provisioning data with each other without complex and costly integration. The Adaxes SPML Provider enables provisioning applications to interoperate with Active Directory via the SPML 2.0 protocol. The provider transforms SPML requests sent by these provisioning applications into Active Directory operations or data retrieval queries.

AD Access Modes

The Adaxes SPML Provider can access Active Directory directly or via the Adaxes service. In the first case, the Adaxes SPML Provider interoperates with a specified Active Directory domain bypassing the Adaxes service. At that, the Softerra Adaxes functionality is NOT applied (Business Rules, Property Patterns, Security Roles). In the direct access mode, SPML requests can be sent to one AD domain only. In the indirect access mode (via the Adaxes service), the Adaxes SPML Provider can interoperate with any Active Directory domain managed by the Adaxes service. In this mode, you can benefit from the Softerra Adaxes functionality that allows to automate AD operations, apply role-based security, track AD operations, etc.

The Active Directory access mode is specified during the installation of the Adaxes SPML Provider. For information on how to modify the AD access mode after the Adaxes SPML Provider is installed, see Configuring Adaxes SPML Provider.

Provider Targets

An SPML request addressed to a certain AD object must specify the provisioning service target, where the object is located. In the direct AD access mode, the Adaxes SPML Provider has only one target that is the AD domain the SPML provider interoperates with. In the indirect AD access mode, when Active Directory is accessed via the Adaxes service, the provider target can be a specific AD domain managed by the Adaxes service, or 'all domains'. When the SPML request target is 'all domains', the AD domain, where an operation must be performed, is determined by the Adaxes SPML Provider basing on the request parameters (PSO ID or Container ID). In some cases, specifying 'all domains' as the request target may slow down the request execution.

Provisioning Service Object Identifier (PSO ID)

The PSO ID is included in an SPML request to uniquely identify the object, for which the request is sent. To identify an AD object, the Adaxes SPML Provider accepts its DN, ADS Path, SID, or GUID. When the Add Request is processed, the SPML provider returns the PSO ID of the new object in the response to the request.

Operations and Capabilities Supported by the Adaxes SPML Provider

Core Operations

Operation	Description
Add Request	The Add Request creates an object of the requested type in Active Directory.
Modify Request	The Modify Request updates properties of the specified object in Active Directory.
Delete Request	The Delete Request deletes the specified object in Active Directory. In case of recursive deletion, the Delete Subtree operation is performed, otherwise, the Delete Object operation is performed.
Lookup Request	The Lookup Request allows to retrieve the properties of the specified Active Directory object.
List Targets Request	The List Targets request is used to list target AD domains and retrieve schema and capabilities for each target.

Capabilities

Capability	Description
Set Password Request	The Set Password Request allows to change or reset passwords of AD users. If the request contains both old and new passwords, the Change Password operation is performed. If the request contains a new password only, the Reset Password operation is performed.
Active Request	The Active Request returns the state of the specified object (enabled or disabled).
Suspend Request	The Suspend Request disables a user account in Active Directory.
Resume Request	The Resume Request enables a user account in Active Directory.

Configuring Adaxes SPML Provider

The Adaxes SPML Provider can be configured via the Web.config file. By default, this file is located in the C:\Program Files\Softerra\Adaxes 3\SPML Web Service folder.

In this file, you can introduce the following modifications in the Adaxes SPML Provider configuration:

Switching to the Direct Active Directory Access Mode
If you want the Adaxes SPML Provider to access Active Directory directly, do the following:
For the XML element 'configuration\softerra\spmlWebService\adaxesProvider', set the 'disabled' attribute to 'true'. Then, for the XML element 'configuration\softerra\spmlWebService\ldapProvider', set the 'disabled' attribute to 'false', and specify the name of the AD domain as the value of the 'domainName' attribute.
Example
```
 <configuration>
 ...
   <softerra>
   ...
     <spmlWebService ...>
       <adaxesProvider adaxesConfigurationSetId="" disabled="true"/>
       ...
       <ldapProvider defaultContainerDn="" domainName="example.com" disabled="false"/>
       ...
     </spmlWebService>
   </softerra>
 </configuration>
          
```
Switching to the Indirect Access Mode (via the Adaxes service)
If you want the Adaxes SPML Provider to access Active Directory via the Adaxes service, do the following:
For the XML element 'configuration\softerra\spmlWebService\adaxesProvider', set the 'disabled' attribute to 'false'. Then, for the XML element 'configuration\softerra\spmlWebService\ldapProvider', set the 'disabled' attribute to 'true'. After that, for the XML element 'configuration\softerra\spmlWebService\adaxesProvider', specify the ID of the Adaxes service configuration set as the value of the 'adaxesConfigurationSetId' attribute. The Adaxes SPML Provider will connect to any Adaxes service of the configuration set.
Example
```
 <configuration>
 ...
   <softerra>
   ...
     <spmlWebService ...>
       <adaxesProvider adaxesConfigurationSetId="{7cc970bd-6426-406e-9d36-0d0cac909dfb}" disabled="false"/>
       ...
       <ldapProvider defaultContainerDn="" domainName="" disabled="true"/>
       ...
       </spmlWebService>
   </softerra>
 </configuration>
          
```
Specifying Default Container for AD Objects
By default, if an Add Request does not specify, where to create an AD object (neither container ID, nor PSO ID is specified), AD objects are created in the built-in Users container of the target AD domain. If necessary, you can specify the default container for an AD domain, where you want AD objects to be created in such cases. You can specify the default container for specific AD domains and for 'all domains' target. For this purpose, do the following:
In the direct access mode:
For the XML element 'configuration\softerra\spmlWebService\ldapProvider', specify the DN of the default container as the value of the 'defaultContainerDn' attribute.
Example
```
 <configuration>
 ...
   <softerra>
   ...
     <spmlWebService ...>
       ...
       <ldapProvider defaultContainerDn="CN=Default Container,DC=example,DC=com" domainName="example.com" disabled="false"/>
       ...
     </spmlWebService>
   </softerra>
 </configuration>
            
```
In the indirect access mode (via the Adaxes service):
You can specify the default container for every AD domain managed by the Adaxes service and for 'all domains' target.
In the XML element 'configuration\softerra\spmlWebService\adaxesProvider\defaultContainerDnToTargetIdMap', create a new 'add' element and specify the AD domain name or 'all domains' as the value of the 'key' attribute, and the DN of the default container as the value of the 'value' attribute. For example: <add key="example.com" value="CN=Default Container,DC=example,DC=com"/>.
Example
```
 <configuration>
 ...
   <softerra>
   ...
     <spmlWebService ...>
       <adaxesProvider adaxesConfigurationSetId="{7cc970bd-6426-406e-9d36-0d0cac909dfb}" disabled="false"/>
         <defaultContainerDnToTargetIdMap>
           <add key="example.com" value="CN=Default Container,DC=example,DC=com"/>
           <add key="all domains" value="CN=Users,DC=softerra,DC=com"/>
         </defaultContainerDnToTargetIdMap>
       </adaxesProvider>
       ...
     </spmlWebService>
   </softerra>
 </configuration>
            
```
Modifying Adaxes SPML Provider Schema
By default, the SPML schema returned by the Adaxes SPML Provider is stored in SpmlSchema.xml file located in the installation folder of the Adaxes SPML Provider (C:\Program Files\Softerra\Adaxes 3\SPML Web Service). You can modify the Adaxes SPML Provider schema in this file the way you need. After modification, IIS must be restarted for your changes to take effect.
Also you can specify another file to store the Adaxes SPML Provider schema. For this purpose, make the following changes in the Web.config file:
For the XML element 'configuration\softerra\spmlWebService', specify the name of the file to store the Adaxes SPML Provider schema as the value of the 'schemaFile' attribute.
Example
```
 <configuration>
 ...
   <softerra>
   ...
     <spmlWebService schemaFile="ModifiedSpmlSchema.xml" ...>
     ...
     </spmlWebService>
   </softerra>
 </configuration>
          
```
Modifying Adaxes SPML Provider Capabilities
By default, the Adaxes SPML Provider capabilities are stored in SpmlCapabilities.xml file located in the installation folder (C:\Program Files\Softerra\Adaxes 3\SPML Web Service). You can modify the Adaxes SPML Provider capabilities in this file the way you need. After modification, IIS must be restarted for your changes to take effect.
Also you can specify another file to store the Adaxes SPML Provider capabilities. For this purpose, make the following changes in the Web.config file:
For the XML element 'configuration\softerra\spmlWebService', specify the name of the file to store the Adaxes SPML Provider capabilities file as the value of the 'capabilitiesFile' attribute.
Example
```
 <configuration>
 ...
   <softerra>
   ...
     <spmlWebService capabilitiesFile="ModifiedSpmlCapabilities.xml" ...>
     ...
     </spmlWebService>
   </softerra>
 </configuration>
          
```
Modifying RDN Mapping
If the RDN property for an object class is not specified in the mapping, the Adaxes SPML Provider uses CN as the RDN property for this class. If you have added some classes to the schema of the Adaxes SPML Provider, you may need to specify the RDN property for them.
To specify the RDN property for an object class, in the section 'configuration\softerra\spmlWebService\objectClassToRdnTypeMap\, create a new 'add' element and specify the class of the AD object, to which you want to map the RDN property, as the value of the 'key' attribute, and the RDN property for this class as the value of the 'value' attribute. For example: <add key="user" value="CN"/>.
Example
```
 <configuration>
 ...
   <softerra>
   ...
     <spmlWebService ...>
       ...
       <objectClassToRdnTypeMap>
         <add key="organizationalUnit" value="OU"/>
         <add key="organization" value="O"/>
         <add key="domain" value="DC"/>
       </objectClassToRdnTypeMap>
     </spmlWebService>
   </softerra>
 </configuration>
            
```

The changes you make in the Web.config file are applied automatically, there is no need to restart IIS.