Active Roles 7.3.1 - SPML Provider Administrator Guide

Support for Active Roles controls

Support for Active Roles controls

Active Roles implements special parameters called Active Roles controls (hereafter controls). The controls allow you to customize request processing.

In proxy mode, SPML Provider clients can send controls to the Active Roles Administration Service with an SPML request to perform an administrative operation. The Administration Service can process the controls. On the other hand, the Administration Service can return its own control to the SPML Provider client, and then the client can process that control. The controls a client sends to the Administration Service are referred to as InControls whereas the controls the Administration Service returns to the client are referred to as OutControls.

This section covers the following subjects:

  • Sending the InControl-type controls to the Active Roles Administration Service with an SPML request.
  • Specifying a set of the OutControl-type controls that the Active Roles Administration Service will return with an SPML response.

For more information about Active Roles controls and for the list of available built-in controls, see Active Roles SDK.

IMPORTANT: All elements described in this section must be defined at the beginning of your SPML request. For a sample of use, see later in this document.

Sending controls to the Active Roles Administration Service

Sending controls to the Active Roles Administration Service

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 2: Controls attributes

attribute name

attribute description

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 3: Control attributes

attribute name

attribute description

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% />

Specifying controls to return to the SPML Provider client

Specifying controls to return to the SPML Provider client

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 SPML Provider client.

Element name: controlsForOutput

Element description: Specifies a collection of OutControl-type controls to return to SPML client.

Child clements: control

Attributes:

Table 4: Attributes for controlsForOutput

attribute name

attribute description

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 SPML Provider client with an SPML response.

Parent elements: controlsForOutput

Child elements: None

Attributes:

Table 5: Attributes for control

attribute name

attribute description

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% />

Sample SPML request

Sample SPML request

This section provides a sample SPML request and the SPML response that illustrate how to use Active Roles controls in your SPML requests.

This sample shows how an SPML Provider 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.

NOTE: You need to modify the sample SPML request in order to adjust it to your environment. Before using this sample, set the ID attribute of the psoID element to the distinguished name of the user account you want to modify.

SPML request

<?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

<?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 7.3 SPML Provider supports Azure user, group, and contact creation.

NOTE: You must complete Azure AD configuration, before using SPML for user, group, and contact creation in Azure AD. For more information, see Azure AD and Office 365 Management Administrator Guide.
Sample SPML request for Azure user, group, and contact creation

Sample SPML request for Azure User Creation

<?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 Azure Group Creation.

<?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 Azure Contact Creation

<?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>

 

Related Documents