This section covers the controls and control XML elements that your SPML request must include to send controls to the Active Roles Administration Service.
Element name: controls
Element description: Specifies a collection of InControl-type controls to send to Administration Service.
Child elements: control
Attributes:
Table 93: Controls attributes
|
xmlns |
Declares the namespase for all child elements of the controls element. This attribute must be set to quest:ars:SPML:2:0 |
Element name: control
Element description: Describes a control to send to the Administration Service.
Parent elements: controls
Child elements: None
Attributes:
Table 94: Control attributes
|
name |
Specifies the name of the control. |
The control value in the control element body must be specified as follows:
<control name=%control name%>%control value%</control>
To send an empty control, use the following syntax:
<control name=%control name% />
This section covers the controlsForOutput and control XML elements that your SPML request must include to specify a set of controls to return to the client.
Element name: controlsForOutput
Element description: Specifies a collection of OutControl-type controls to return to SPML client.
Child clements: control
Attributes:
Table 95: Attributes for controlsForOutput
|
xmlns |
Declares the namespase for all child elements of the controls element. This attribute must be set to quest:ars:SPML:2:0 |
Element name: control
Element description: Describes a control to return to client with an SPML response.
Parent elements: controlsForOutput
Child elements: None
Attributes:
Table 96: Attributes for control
|
name |
Specifies the name of the control. |
The control elements used to specify controls to return with SPML response must be defined as follows:
<control name=%control name% />
This section provides sample SPML requests and SPML responses to show how to use the feature with Active Roles.
NOTE: You must modify the sample SPML requests to adjust them to your environment. For example, before using the first sample, set the ID attribute of the psoID element to the distinguished name of the user account you want to modify.
SPML request to modify a user object
This sample shows how an client can send a request to modify the specified user object. With this request, the client sends the AllowApproval built-in control set to Confirm, and the CustomControl control set to MyCustomValue. The request also contains the controlsForOutput element, which specifies that Active Roles Administration Service will return values of the OperationStatus and CustomControl controls in the SPML response.
TIP: For more information about the use of the AllowApproval and OperationStatus controls, refer to the Active Roles SDK documentation.
<?xml version="1.0"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<spml:modifyRequest xmlns:spml="urn:oasis:names:tc:SPML:2:0">
<controls xmlns="quest:ars:SPML:2:0">
<control name="AllowApproval">Confirm </control>
<control name="CustomControl">MyCustomValue </control>
</controls>
<controlsForOutput xmlns="quest:ars:SPML:2:0">
<control name="OperationStatus"/>
<control name="CustomControl"/>
</controlsForOutput>
<spml:psoID ID="CN=JDOE,OU=Users,DC=mycompany,DC=com"/>
<spml:modification>
<modification name="description" operation="replace" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>New description</value>
</modification>
</spml:modification>
</spml:modifyRequest>
</soap:Body>
</soap:Envelope>
SPML response of modifying a user object
The following example provides a sample response to the previous request of modifying a user object.
<?xml version="1.0" encoding="UTF-16"?>
<soap:Envelope xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema">
<soap:Body>
<modifyResponse status="success" xmlns="urn:oasis:names:tc:SPML:2:0">
<controls xmlns="quest:ars:SPML:2:0">
<control name="OperationStatus">Completed</control>
<control name="CustomControl">ReturnedValue</control>
</controls>
<pso>
<psoID ID="CN=JDOE,OU=Users,DC=mycompany,DC=com"/>
<data>
<attr name="cn" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value xsi:type="xsd:string">Admin1</value>
</attr>
<attr name="objectClass" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value xsi:type="xsd:string">top</value>
<value xsi:type="xsd:string">person</value>
<value xsi:type="xsd:string">organizationalPerson</value>
<value xsi:type="xsd:string">user</value>
</attr>
<attr name="objectCategory" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value xsi:type="xsd:string">CN=Person,CN=Schema,CN=Configuration,DC=dom,DC=lab,DC=local</value>
</attr>
<attr name="objectGUID" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value xsi:type="xsd:base64Binary">Aodvua6TAE+Ja9O3vnRntg==</value>
</attr>
<attr name="description" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value xsi:type="xsd:string">New description</value>
</attr>
</data>
</pso>
</modifyResponse>
</soap:Body>
</soap:Envelope>
Supported Azure features
Active Roles supports creating Azure users, Azure groups, and Azure contacts.
NOTE: To create Azure users, groups or contacts in an Azure AD deployment with , you must configure an Azure tenant in the Active Roles Configuration Center, and consent Active Roles as an Azure application.
For more information, see Configuring Active Roles to manage Azure AD using the GUI.
Sample SPML requests for creating Azure users, groups or contacts in Azure AD
The following sample SPML requests show how to create Azure objects in an Azure AD deployment configured for Active Roles.
Sample SPML request for creating an Azure user
<?xml version="1.0"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<addRequest xmlns="urn:oasis:names:tc:SPML:2:0" returnData="everything">
<containerID ID="OU=AzureOU, DC=Sample,DC=local,DC=com"/>
<data>
<attr name="cn" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureUser</value>
</attr>
<attr name="description" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>Azure test user</value>
</attr>
<attr name="sAMAccountName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureUser</value>
</attr>
<attr name="objectClass" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>user</value>
</attr>
<attr name="mail" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureUser@ARStestdev.onmicrosoft.com</value>
</attr>
<attr name="otherHomePhone" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>12135555555</value>
<value>12134444444</value>
</attr>
<attr name="edsaPassword" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>P@ssw0rd123</value>
</attr>
<attr name="edsaAccountIsDisabled" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>FALSE</value>
</attr>
<attr name="userPrincipalName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureUser@ARStestdev.onmicrosoft.com</value>
</attr>
<attr name="edsvaAzureOffice365Enabled" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>TRUE</value>
</attr>
<attr name="edsaAzureUserPrincipalName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureUser@ARStestdev.onmicrosoft.com</value>
</attr>
<attr name="edsaAzureUserAccountEnabled" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>TRUE</value>
</attr>
<attr name="edsaAzureUserDisplayName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureUser</value>
</attr>
</data>
</addRequest>
</soap:Body>
</soap:Envelope>
Sample SPML request for creating an Azure group
<?xml version="1.0"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<addRequest xmlns="urn:oasis:names:tc:SPML:2:0" returnData="everything">
<psoID ID="CN=GroupName,OU=AzureOU,DC=Sample,DC=local,DC=com"/>
<data>
<attr name="objectClass" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>group</value>
</attr>
<attr name="description" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>My test group</value>
</attr>
<attr name="mailEnabled" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>false</value>
</attr>
<attr name="mail" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value> GroupName@company.com</value>
</attr>
<attr name="mailNickName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value> GroupName</value>
</attr>
<attr name="edsvaAzureOffice365Enabled" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>TRUE</value>
</attr>
<attr name="edsaAzureGroupDisplayName" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value> GroupName</value>
</attr>
<attr name="edsaEstablishGroupEmail" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>false</value>
</attr>
<attr name="edsaAzureGroupType" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>-2147483646</value>
</attr>
</data>
</addRequest>
</soap:Body>
</soap:Envelope>
Sample SPML request for creating an Azure contact
<?xml version="1.0"?>
<soap:Envelope xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xmlns:xsd="http://www.w3.org/2001/XMLSchema" xmlns:soap="http://schemas.xmlsoap.org/soap/envelope/">
<soap:Body>
<addRequest xmlns="urn:oasis:names:tc:SPML:2:0" returnData="everything">
<containerID ID="OU=AzureOU,DC=Sample,DC=local,DC=com"/>
<data>
<attr name="cn" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureContact</value>
</attr>
<attr name="description" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureContact</value>
</attr>
<attr name="objectClass" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>Contact</value>
</attr>
<attr name="edsvaAzureOffice365Enabled" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>TRUE</value>
</attr>
<attr name="edsaAzureContactEmail" xmlns="urn:oasis:names:tc:DSML:2:0:core">
<value>AzureContact@test.com</value>
</attr>
</data>
</addRequest>
</soap:Body>
</soap:Envelope>
implements the SPML v2 core protocol and supports core operations that are required for compliance with the official SPML v2 specification. The following table lists the core operations supported by .
Table 97: Core operations supported by
|
listTargets |
Lists targets available for provisioning through and the 's supported set of capabilities for targets. |
|
add |
Creates a new object on the target. |
|
modify |
Changes the specified object on the target. |
|
lookup |
Obtains the XML that represents the specified object on the target. |
|
delete |
Removes the specified object from the target. |
In addition to core operations required for conformance to the SPML v2 specification, supports a set of optional operations (Capabilities) that are functionally related. The following tables list the Capabilities supported by .
Search capability
Table 98: Search capabilities supported by
|
search |
Obtains every object that matches the specified query. |
|
iterate |
Obtains the next set of objects from the result set selected for a search operation. |
|
closeIterator |
Informs that the client no longer intends to iterate the search result. |
Suspend capability
Table 99: Suspend capabilities supported by
|
suspend |
Disables/deprovisions the specified object on the target. |
|
resume |
Re-enables the specified object on the target. |
|
active |
Checks whether the specified object on the target has been suspended. |
Password Capability
Table 100: Password capabilities supported by
|
setPassword |
Specifies a new password for a user account. |
|
expirePassword |
Marks as invalid the current password for a user account. |
For detailed information on the SPML v2 operations, refer to the “Operations” section in the official SPML v2 specification, available for download at http://www.oasis-open.org/specs/index.php#spmlv2.0.
