OASIS Service Provisioning
Markup Language (SPML) v2 - DSML v2 Profile
Committee Draft 1.0
2005 September 14
Document identifier:
pstc-spml2-dsml-profile-cd-01.pdf
Location:
http://www.oasis-open.org/committees/provision/docs/
Send comments
to: pstc-comment@lists.oasis-open.org
Editor:
Contributors:
Robert Boucher, CA
Doron Cohen, BMC
Gary Cole, Sun Microsystems
Cal Collingham, CA
Rami Elron, BMC
James Hu, HP
Ron Jacobsen, CA
Jeff Larson, Sun Microsystems
Hal Lockhart, BEA
Martin Raepple, SAP
Kent Spaulding, Sun Microsystems
Cory Williams, IBM
Gerry Woods, SOA Software
Abstract:
This
specification defines usage of DSML v2 as a data model (profile) for SPML v2.
Status:
This is a candidate Committee Specification
that is undergoing a vote of the OASIS membership in pursuit of OASIS Standard
status.
If
you are on the provision list for committee members, send comments there. If
you are not on that list, subscribe to the provision-comment@lists.oasis-open.org
list and send comments there. To subscribe, send an email message to provision-comment-request@lists.oasis-open.org
with the word "subscribe" as the body of the message.
Copyright (C) OASIS Open 2005. All Rights Reserved.
Table
of contents
1. Introduction
(non-normative) 4
1.1. Concepts 4
1.1.1. DSML Protocol 4
1.1.2. Schema 4
1.2. Terminology 4
2. Notation 4
3. Overview (non-normative) 5
3.1. DSML PSOs 5
3.1.1. PSO Identifier 6
3.1.2. PSO Data 6
3.2. Schema 6
3.3. Core Operations 7
3.3.1. Add Request 7
3.3.2. Add Response 7
3.3.3. Modify Request 7
3.3.4. Delete Request 8
3.3.5. Lookup Request 8
3.3.6. Lookup Response 8
3.4. Search Operations 9
3.4.1. Search Request 9
3.4.2. Search Response 9
4. Specification (Normative) 10
4.1. Namespaces 10
4.2. Core Capability 10
4.2.1. Element <spml:data> 10
4.2.2. Element <spml:modification> 10
4.2.3. Element <spml:schema> 10
4.2.4. Element <supportedSchemaEntity> 10
4.3. Search Capability 11
4.3.1. Element <spmlsearch:query> 11
4.4. DSML Profile Schema 11
4.4.1. Element <spmldsml:schema> 11
4.4.2. Element <spmldsml:objectClassDefinition> 11
4.4.3. Element <spmldsml:attributeDefinition> 11
Appendix A. References 12
Appendix B. Acknowledgments 14
Appendix C. Revision history Error! Bookmark not defined.
Appendix D. Notices 15
SPML Version 2 (SPMLv2) defines a core protocol [SPMLv2] over which different data models can be used to define the actual provisioning data. The combination of a data model with the SPML core specification is referred to as a profile. The use of SPML requires that a specific profile is used, although the choice of which profile is used to negatioted out-of-band by the participating parties.
This document describes the use of the DSML protocol as a data model for SPML based provisioning. This profile is optional.
The DSML v2 protocol [DSMLV2] was designed to perform LDAP type operations using web services. The DSML V2 protocol defines synchronous request/response semantics and a data model based on attribute/value pairs. DSML V2 does not define an attribute/value pairs schema mechanism.
The DSML v2 standard does not define a schema mechanism. A schema mechanism is defined as part of this binding.
Within
this document:
- The term “requestor” always refers to a Requesting
Authority (RA).
- The term “provider” always refers to a Provisioning
Service Provider (PSP).
- The term “target” always refers to a Provisioning
Service Target (PST).
- The term “object” (unless otherwise qualified) refers to a Provisioning
Service Object (PSO).
- The term “client” (unless otherwise qualified) refers to a Requesting
Authority (RA).
- The term “server” (unless otherwise qualified) refers to a Provisioning
Service Provider (PSP).
This
specification contains schema conforming to W3C XML Schema and normative text
to describe the syntax and semantics of XML-encoded policy statements.
The
key words "MUST", "MUST NOT", "REQUIRED",
"SHALL", "SHALL NOT", "SHOULD", "SHOULD
NOT", "RECOMMENDED", "MAY", and "OPTIONAL"
in this specification are to be interpreted as described in IETF RFC 2119 [RFC2119]
"they MUST only be used where it is
actually required for interoperation or to limit behavior which has potential
for causing harm (e.g., limiting retransmissions)"
These
keywords are thus capitalized when used to unambiguously specify requirements
over protocol and application features and behavior that affect the
interoperability and security of implementations. When these words are not
capitalized, they are meant in their natural-language sense.
This
specification uses the following typographical conventions in text:
Format |
Description |
Indicates |
attributeName |
monospace
font |
The name
of an XML attribute. |
SPMLElementName |
monospace
font |
The
name of an XML element |
ns:ForeignElementName |
monospace
font |
The
name of an XML element |
<SPMLElement> |
monospace
font |
An
instance of an XML element |
<ns:ForeignElement> |
monospace font |
An
instance of an XML element |
Terms
in italic
bold-face are intended to have the meaning defined in the Glossary.
Listings of SPML schemas appear
like this.
Example code listings appear like
this.
Conventional
XML namespace prefixes are used throughout the listings in this specification
to stand for their respective namespaces as follows, whether or not a namespace
declaration is present in the example:
- The prefix dsml: stands for the Directory Services Markup
Language namespace [DSML].
- The prefix saml: stands for the SAML assertion namespace [SAML].
- The prefix ds: stands for the W3C XML Signature namespace
[DS].
- The prefix xsd: stands for the W3C XML Schema namespace [XS].
A PSO is represented
in this binding by a set of attribute/values pairs that is associated with a
target-unique identifier. All PSOs are categorized by one or more object
classes. The object class for a given PSO is denotes by an attribute named with
the reserved name of “objectclass”.
The PSO Identifier may be an X.509
Distinguished Name (DN), or any identifier that is unique for the target..
<spml:pso>
<spml:psoId ID="CN=John
Doe,OU=accounting,DC=acme.com" targetID="acme.com"/>
...
</spml:pso>
The PSO Data element contains dsml:attr elements, as defined in [DSML]. Additional data may be included via the Open Content Model.
<spml:pso>
...
<spml:data>
<attr name="cn">
<value> John Doe </value>
</attr>
<attr name="uid">
<value>jdoe</value>
</attr>
<attr name="email">
<value>jdoe@acme.com</value>
</attr>
<attr name="objectclass">
<value>user</value>
</attr>
</spml:data>
</spml:pso>
The schema defines the allowed attributes and object classes.
<spml:schema>
<spmldsml:schema>
<spmldsml:attributeDefinition name="cn" description="Common Name" />
<spmldsml:attributeDefinition name="uid" description="User ID" />
<spmldsml:attributeDefinition name="email" description="Email Address" />
<spmldsml:objectClassDefinition name="person">
<spmldsml:memberAttributes>
<spmldsml:memberAttributes name="cn" required="true" />
<spmldsml:memberAttributes name="uid"/>
<spmldsml:memberAttributes name="email"/>
</spmldsml:memberAttributes>
</spmldsml:objectClassDefinition>
</spmldsml:schema>
</spml:schema>
The Add Request creates PSOs. The Add Request must contain a <data> element that contains DSML v2 <attr> elements that define the new PSO. The Add Request may also pass a PSO Identifier (<psoID> element), a container PSO ID (<containerID> element), or a target ID (<targetID> element). If a PSO identifier is not defined in the Add Request, the new PSO Identifier must be returned in the Add Response.
<spml:addRequest>
<spml:containerID ID = "OU=accounting,DC=acme.com " targetID = "acme.com "/>
<spml:data>
<attr name="CN">
<value> John Doe </value>
</attr>
<attr name="uid">
<value>jdoe</value>
</attr>
<attr name="objectclass">
<value>user</value>
</attr>
</spml:data>
</spml:addRequest >
The Add Response message will contain the new PSO ID (unless it was specified in the Add Request). If the creation of the new PSO resulted in attributes being adding or modified in the new PSO, the entire PSO Data should be returned in the response.
<spml:addResponse status = "success">
<spml:psoId ID="CN=John Doe,OU=accounting,DC=acme.com" targetID="acme.com "/>
<spml:data>
<attr name="CN">
<value> John Doe </value>
</attr>
<attr name="uid">
<value>jdoe</value>
</attr>
<attr name="email">
<value>jdoe@acme.com</value>
</attr>
<attr name="objectclass">
<value>user</value>
</attr>
</spml:data>
</spml:addResponse>
The Modify Request modifies the specified PSO. The Modify Request must always contain the PSO Identifier.
<spml:modifyRequest>
<spml:psoId ID="CN=John Doe,OU=accounting,DC=acme.com" targetID="acme.com "/>
<spml:modification>
<modification name ="CN" operation ="replace">
<value>Jane Doe</value>
</modification>
</spml:modification>
</spml:modifyRequest >
If the Modify Request causes the PSO ID to change, then the Modify Response must contain the new PSO ID.
<spml:modifyResponse status = "success">
<spml:psoId ID="CN=Jane Doe,OU=accounting,DC=acme.com" targetID="acme.com "/>
</spml:modifyResponse>
The Delete Request deletes a specified PSO.
<spml:deleteRequest>
<spml:psoId ID="CN=John Doe,OU=accounting,DC=acme.com" targetID="acme.com "/>
</spml:deleteRequest >
The Lookup Request
is used to retrieve the data for a specified PSO.
<spml:lookupRequest>
<spml:psoId ID="CN=John Doe,OU=accounting,DC=acme.com" targetID="acme.com "/>
</spml:lookupRequest>
The Lookup Response contains the retrieved PSO data.
<spml:lookupResponse status = "success">
<spml:psoId ID="CN=John Doe,OU=accounting,DC=acme.com" targetID="acme.com "/>
<spml:data>
<attr name="CN">
<value> John Doe </value>
</attr>
<attr name="uid">
<value>jdoe</value>
</attr>
<attr name="email">
<value>jdoe@acme.com</value>
</attr>
<attr name="objectclass">
<value>user</value>
</attr>
</spml:data>
</spml:lookupResponse>
If the Search
Capability is supported, the DSML filters and attribute declarations should be
used to scope the results of the search.
The search request can specify DSML filters and attribute declarations, as defined in [DSML].
<spmlsearch:searchRequest>
<spmlsearch:query scope = "spmlsearch:oneLevel">
<spml:basePSOID ID="CN=John Doe,OU=accounting,DC=acme.com" targetID="acme.com>
<dsml:filter>
<dsml:substrings name = "cn">
<dsml:initial>John</dsml:initial>
</dsml:substrings>
</dsml:filter>
<dsml:attributes>
<dsml:attribute name = "cn" />
<dsml:attribute name = "email" />
</dsml:attributes>
</spmlsearch:query>
</spmlsearch:searchRequest>
<spml:searchResponse status = " success">
</spml:pso>
<spml:psoId ID="CN=John Doe,OU=accounting,DC=acme.com" targetID="acme.com"/>
<spml:data>
<dsml:attr name="cn">
<dsml:value>John Doe</dsml:value>
</dsml:attr>
<dsml:attr name="email">
<dsml:value>jdoe@acme.com</dsml:value>
</dsml:attr>
</spml:data>
</spml:pso>
</spml:pso>
<spml:psoId ID="CN=John Smith,OU=accounting,DC=acme.com" targetID="acme.com"/>
<spml:data>
<dsml:attr name="cn">
<dsml:value>John Smith</dsml:value>
</dsml:attr>
<dsml:attr name="email">
<dsml:value>jsmith@acme.com</dsml:value>
</dsml:attr>
</spml:data>
</spml:pso>
</spml:searchResponse>
The DSMLv2 Profile uses the DSML v2 namespace which is defined as:
urn:oasis:names:tc:DSML:2:0:core
The specification uses the prefix dsml: to refer to this namespace.
The DSMLv2 Profile defines some elements that are specific to the profile. The namespace for the profile itself is defined as:
urn:oasis:names:tc:SPML:2:0:DSML
The specification uses the prefix spmldsml: to refer to this namespace.
The <spml:data> element MUST contain zero or many <dsml:attr> elements.
The <spml:modification> element MUST contain zero or many <dsml:modification> elements. The “modificationType” on the <spml:modification> MUST NOT be specified since the <dsml:modification> defines the modification type.
If the schema is defined in-band, the <spml:schema> element MUST contain one or more <spmldsml:schema> elements. If the schema is define out-of-band, the “ref” attribute on the <spml:schema> element MUST be set to the URN of the referenced schema.
If ony a subset of
the object classes defined in the schema are supported for the target, then the
<spml:schema> element MUST
include <spml:supportedSchemaEntity>.
If no <spml:supportedSchemaEntity>
are defined in the <spml:schema>
element, then it is assumed are object classes are supported by the target.
The “entityName” attribute on the <spml:supportedSchemaEntity> element MUST refer only to object classes defined in the referenced schema. All attributes on the referenced object classes are assumed to be supported.
The <spmlsearch:query> element MAY contain <dsml:filter> and <dsml:attributes> to filter the results of the search.
The <spmldsml:schema> element defines the DSML schema for the target. The <spmldsml:schema> element contains zero or more <spmldsml:objectClassDefinition> elements and zero or more <spmldsml:attributeDefinition> elements.
The <spmldsml:objectClassDefinition>
element defines DSML v2 object classes supported by the target. The <spmldsml:objectClassDefinition>
element contains zero or more <spmldsml:memberAttributes> elements
which define the attributes that may be included on objects of the specified
object class. The <spmldsml:objectClassDefinition>
element contains zero or more <spmldsml:superiorClasses> which define the
superior object classes to the specified object class.
The <spmldsml:attributeDefinition> element defines DSML v2 attributes supported by the target. The <spmldsml:attributeDefinition> element has the following attributes:
.
[AES] National
[ARCHIVE-1] OASIS Provisioning Services Technical Committee, email archive, http://www.oasis-open.org/apps/org/workgroup/provision/email/archives/index.html, OASIS PS-TC
[DS] IETF/W3C, W3C XML Signatures, http://www.w3.org/Signature/, W3C/IETF
[DSML] OASIS Directory Services Markup Standard, DSML V2.0 Specification, http://www.oasis-open.org/specs/index.php#dsmlv2, OASIS DSML Standard
[GLOSSARY] OASIS Provisioning Services TC, Glossary of Terms, http://www.oasis-open.org/apps/org/workgroup/provision/download.php, OASIS PS-TC
[RFC 2119] S. Bradner., Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF
[RFC 2246] T. Dierks and C. Allen, The TLS Protocol, http://www.ietf.org/rfc/rfc2246.txt, IETF
[SAML] OASIS Security Services TC, http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=security, OASIS SS-TC
[SOAP] W3C XML Protocol Working Group, http://www.w3.org/2000/xp/Group/
[SPML-Bind] OASIS Provisioning Services TC, SPML V1.0 Protocol Bindings, http://www.oasis-open.org/apps/org/workgroup/provision/download.php/1816/draft-pstc-bindings-03.doc, OASIS PS-TC
[SPML-REQ] OASIS Provisioning Services Technical Committee, Requirements, http://www.oasis-open.org/apps/org/workgroup/provision/download.php/2277/draft-pstc-requirements-01.doc, OASIS PS-TC
[SPML-UC] OASIS Provisioning Services Technical Committee, SPML V1.0 Use Cases, http://www.oasis-open.org/apps/org/workgroup/provision/download.php/988/drfat-spml-use-cases-05.doc, OASIS PS-TC
[SPMLv2-Profile-DSML] OASIS Provisioning Services Technical Committee, SPMLv2 DSMLv2 Profile, OASIS PS-TC
[SPMLv2-Profile-XSD] OASIS Provisioning Services Technical Committee, SPML V2 XSD Profile, OASIS PS-TC
[SPMLv2-REQ] OASIS Provisioning Services Technical Committee, Requirements, OASIS PS-TC
[SPMLv2-ASYNC] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Async Capability of SPMLv2, OASIS PS-TC
[SPMLv2-BATCH] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Batch Capability of SPMLv2, OASIS PS-TC
[SPMLv2-BULK] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Bulk Capability of SPMLv2, OASIS PS-TC
[SPMLv2-CORE] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Core Operations of SPMLv2, OASIS PS-TC
[SPMLv2-PASS] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Password Capability of SPMLv2, OASIS PS-TC
[SPMLv2-REF] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Reference Capability of SPMLv2, OASIS PS-TC
[SPMLv2-SEARCH] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Search Capability of SPMLv2, OASIS PS-TC
[SPMLv2-SUSPEND] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Suspend Capability of SPMLv2, OASIS PS-TC
[SPMLv2-UPDATES] OASIS Provisioning Services Technical Committee, XML Schema Definitions for Updates Capability of SPMLv2, OASIS PS-TC
[SPMLv2-UC] OASIS Provisioning Services Technical Committee., SPML V2.0 Use Cases, OASIS PS-TC
[WSS] OASIS Web Services Security (WSS) TC, http://www.oasis-open.org/committees/tc_home.php?wg_abbrev=wss, OASIS SS-TC
[X509] RFC 2459 - Internet X.509 Public Key Infrastructure Certificate and CRL Profile, http://www.ietf.org/rfc/rfc2459.txt
[XSD] W3C Schema WG ., W3C XML Schema, http://www.w3.org/TR/xmlschema-1/ W3C
The following
individuals were voting members of the Provisioning Services committee at the
time that this version of the specification was issued:
Robert Boucher, CA
Gary Cole, Sun Microsystems
Rami Elron, BMC
James Hu, HP
Martin Raepple, SAP
Kent Spaulding, Sun Microsystems
OASIS takes no position regarding the validity or scope of any intellectual property or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; neither does it represent that it has made any effort to identify any such rights. Information on OASIS's procedures with respect to rights in OASIS specifications can be found at the OASIS website. Copies of claims of rights made available for publication and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementors or users of this specification, can be obtained from the OASIS President.
OASIS invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights which may cover technology that may be required to implement this specification. Please address the information to the OASIS President.
Copyright © OASIS Open 2005. All Rights Reserved.
This document and translations of it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself does not be modified in any way, such as by removing the copyright notice or references to OASIS, except as needed for the purpose of developing OASIS specifications, in which case the procedures for copyrights defined in the OASIS Intellectual Property Rights document must be followed, or as required to translate it into languages other than English.
The limited permissions granted above are perpetual and will not be revoked by OASIS or its successors or assigns.
This document and the information contained herein is provided on an “AS IS” basis and OASIS DISCLAIMS ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.