Introduction to Transfer Extensions for Identity Management Operations
In the previous two posts I introduced WS-Transfer and WS-Enumeration with examples on how ILM uses them. In this post I introduce an extension to WS-Transfer we use for more efficient operations over the wire. We will fully and formally document this extension as an earnest commitment to interoperability in product documentation. In this post I introduce the concepts so you may begin to understand these messages when you see them in the logs.
Our working title of the extension is “Transfer Extensions for Identity Management Operations", which we fondly call TEIMO internally. Please remember this name is simply so we can effectively communicate the particular extension and is subject to change.
The TEIMO extension provides a structure for transferring individual attribute values of an object. We use this extension for the Create, Get, and Put operations. We will show one example for each operation. To use this extension you MUST place the following SOAP header in all requests:
<da:IdentityManagementOperation s:mustUnderstand="1"/>
Please note the following namespaces in our examples.
- xmlns:s=”http://www.w3.org/2003/05/soap-envelope”
- xmlns:da=”http://schemas.microsoft.com/2006/11/IdentityManagement/DirectoryAccess”
- xmlns:rm=”http://schemas.microsoft.com/2006/11/ResourceManagement”
Get
Our extension enables you to specify a BaseObjectSearchRequest element to pick which attributes of the ILM object to retrieve. This element’s children are AttributeType elements which specify one attribute value to return by providing the attribute’s name. A GetResponse using our extensions will only return values for the requested AttributeType elements.
In the example below, assume we are getting a Group object. We only request the attributes “ObjectType”, “ObjectID”, “DisplayName”, etc. Our GetResponse will only include the requested attributes. It will not include other attributes bound to Group like ExplicitMember, ExpireTime, etc. Since some of these attributes, especially multi-valued attributes like ExplicitMember, can be very large, TEIMO saves bandwidth by not transferring unwanted data.
The following is the body of a WS-Transfer Get using TEIMO which requests attributes “ObjectType”, “ObjectID”, and “DisplayName”.
<s:Body>
<da:BaseObjectSearchRequest Dialect="http://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeType-20080602">
<AttributeType>ObjectType</AttributeType>
<AttributeType>ObjectID</AttributeType>
<AttributeType>DisplayName</AttributeType>
</da:BaseObjectSearchRequest>
</s:Body>
The following is the body of a WS-Transfer GetResponse using TEIMO. Each requested attribute value is wrapped by a PartialAttribute element in the BaseObjectSearchResponse:
<s:Body>
<da:BaseObjectSearchResponse>
<da:PartialAttribute>
<rm:ObjectType>Group</rm:ObjectType>
</da:PartialAttribute>
<da:PartialAttribute>
<rm:ObjectID>AF261B6A-4A56-4e64-A3CE-B6238AAA3A33</rm:ObjectID>
</da:PartialAttribute>
<da:PartialAttribute>
<rm:DisplayName>Identity Management Team</rm:DisplayName>
</da:PartialAttribute>
</da:BaseObjectSearchResponse>
</s:Body>
Put
Similar to a Get operation, our extension allows you to provide a ModifyRequest which specifies new values for individual attributes. This is very useful when adding one value to a very large multi-valued attribute. A ModifyRequest consists of multiple Change elements. Each Change element has one AttributeType and one AttributeValue element just like in the Get operation. You use AttributeType to specify which particular attribute by name and then provide the new value. The change operation specifies how to change the value. For multi-valued attributes the only valid operations are “add” and “delete”. You can only add and remove one value at a time. For single-valued attributes the only valid operation is replace. An omitted AttributeValue element is interpreted as “null” whereas an empty AttributeValue element is “empty.”
The following is an example of removing member ‘4444…’ from the group and changing the display name to “something new”.
<s:Body>
<da:ModifyRequest
Dialect="http://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeType-20080602">
<da:Change Operation="delete">
<da:AttributeType>
ExplicitMember
</da:AttributeType>
<da:AttributeValue>
44444444-4444-4444-4444-444444444444
</da:AttributeValue>
</ da:Change>
<da:Change Operation="replace">
<da:AttributeType>
DisplayName
</da:AttributeType>
<da:AttributeValue>
<rm:DisplayName>something new</rm:DisplayName>
</da:AttributeValue>
</da:change>
</da:ModifyRequest>
</s:Body>
Create
Finally, our extension allows you to provide an AddRequest element which specifies individual values for the new object’s attributes. An AddRequest and its children are logically identical to a ModifyRequest in Put except there aren’t “operations” since the object does not exist yet. To signify this difference we replace a Change element with AttributeTypeAndValue. Again, AttributeType names which attribute and AttributeValue provides the initial value.
The following is a sample create request for a new group (please note required Group attributes are missing due to space – this example is illustrative online).
<s:Body>
<da:AddRequest Dialect="http://schemas.microsoft.com/2006/11/ResourceManagement/Dialect/IdentityAttributeType-20080602">
-<AttributeTypeAndValue>
<AttributeType>DisplayName</AttributeType>
<AttributeValue>
<rm:DisplayName>Created Group</rm:DisplayName>
</AttributeValue>
</AttributeTypeAndValue>
<AttributeTypeAndValue>
<AttributeType>Scope</AttributeType>
<AttributeValue>
<rm:Scope>DomainLocal</rm:Scope>
</AttributeValue>
</AttributeTypeAndValue>
</da:AddRequest>
</s:Body>
Conclusion
The ILM Portal uses TEIMO in nearly all web service calls. We believe a basic understanding of the extension is useful for following along with message traces. The extension is particularly useful when modifying specific attributes of an object. Please note that in our dialect the AttributeValue is always the xml representation of the ILM attribute. This is why you see the <rm:DisplayName/> element wrapper around the display name value. We chose this so you could look up the element name, rm:DisplayName, in ILM’s schema to determine the type.
We hope this introduction has been useful and informative. Next week we will provide more hands-on, “working” examples on how to use the ILM web services for your benefit.