lists.oasis-open.orglists.oasis-open.org/archives/provision/200602/doc0000… · web viewmartin...

OASIS Service Provisioning Markup Language (SPML) v2 – Standard Schema

Draft 0.0130 January 2006Document identifier: draft-pstc-spml2-standard-schema-01.doc

Location: http://www.oasis-open.org/committees/provision/docs/

Send comments to: [email protected]

Editor:Gary Cole, Sun Microsystems ([email protected])

Contributors:

Doron Cohen, BMCDarran Rolls, Sun MicrosystemsGavenraj Sodhi, CAHal Lockhart, BEAJeff Larson, Sun MicrosystemsRami Elron, BMCGary Cole, Sun MicrosystemsRon Jacobsen, CAMartin Raepple, SAPCory Williams, IBMIan Glazer, IBMRichard Sand, Tripod Technology Group

Abstract:

This specification defines usage of SAML Attributes as a data model (profile) for SPML v2. This specification also defines a specific schema in order to promote interoperability.

Status:

This draft is a work product for the PSTC Standard Schema Work Group.

If you are on the provision list for committee members, send comments there. If you are not on that list, subscribe to the [email protected] list and send

document.doc of 34

1

2

3

4

5

6

7

8

9

1011

1314151617181920212223242526

2728

2930

31

32

3334

1

mailto:[email protected]



comments there. To subscribe, send an email message to [email protected] with the word "subscribe" as the body of the message.

Copyright (C) OASIS Open 2005. All Rights Reserved.

document.doc of 34

3536

37

2



Table of contents

1. Introduction................................................................................................................................... 5

(non-normative)Purpose..............................................................................................................5

Organization................................................................................................................................. 5

Terminology.................................................................................................................................. 5

Notation........................................................................................................................................ 6

2. Overview....................................................................................................................................... 7

Schema......................................................................................................................................... 7

Person...................................................................................................................................... 7

Account................................................................................................................................... 11

Group...................................................................................................................................... 15

Role........................................................................................................................................ 17

Organization........................................................................................................................... 18

Profile.......................................................................................................................................... 21

4. Protocol....................................................................................................................................... 21

Execution Mode (normative).......................................................................................................21

Identifiers XML PSOs..................................................................................................................21

PSO Identifier (normative)......................................................................................................21

PSO Data............................................................................................................................... 22

Selection..................................................................................................................................... 23

Operations.................................................................................................................................. 23

Core Operations.....................................................................................................................23

listTargets........................................................................................................................23

listTargetsRequest (normative)...................................................................................23

listTargetsResponse (normative)................................................................................24

listTargets Examples...................................................................................................24

add................................................................................................................................... 24

addRequest (normative)..............................................................................................24

addResponse (normative)...........................................................................................24

add Examples.............................................................................................................25

lookup.............................................................................................................................. 25

lookupRequest (normative).........................................................................................25

lookupResponse (normative)......................................................................................25

lookup Examples.........................................................................................................25

modify.............................................................................................................................. 25

document.doc of 34

38

39

40

41

42

43

44

45

46

47

48

49

50

51

52

53

54

55

56

57

58

59

3

modifyRequest (normative).........................................................................................25

modifyResponse (normative)......................................................................................27

modify Examples.........................................................................................................27

delete............................................................................................................................... 27

deleteRequest (normative)..........................................................................................27

deleteResponse (normative).......................................................................................27

delete Examples.........................................................................................................27

Search Capability...................................................................................................................27

search.............................................................................................................................. 27

searchRequest (normative).........................................................................................27

searchResponse (normative)......................................................................................28

search Examples........................................................................................................28

5. Conformance (normative)............................................................................................................28

6. Specification (Normative)............................................................................................................29

Namespaces............................................................................................................................... 29

Core Capability........................................................................................................................... 29

Element <spml:data> .............................................................................................................29

Element <spml:modification>..................................................................................................29

Element <spml:schema>........................................................................................................30

Element <supportedSchemaEntity>.......................................................................................31

Search Capability........................................................................................................................31

Element <spmlsearch:query>.................................................................................................31

Appendix A. References.................................................................................................................. 32




Appendix B. Acknowledgments.......................................................................................................33




Appendix C. Revision history..........................................................................................................34




Appendix D. Notices........................................................................................................................35


document.doc of 34

60

61

62

63

64

65

66

67

68

69

70

71

72

73

74

75

76

77

78

79

80

81

82

83

84

4



1. IntroductionThis document defines the “Standard Interoperable Multi-Purpose Lightweight Extensible Schema Template” (SIMPLEST) profile for SPML2 [SPML2]. A profile describes the manner in which a requester and a provider agree to use the SPML2 protocol. For example, a profile may specify a particular schema language, identifier format and query language.

This document describes the use of SAML attribute value assertions and assumes a specific schema as a data model for SPML-based identity management. (See the section entitled “Overview” below.) This profile is optional.

1.1. PurposeThe SPMLv2 protocol is flexible and rich in function. It is also complex. SPMLv2 operations support arbitrary XML payloads for managed objects. A provider may expose multiple targets, each of which specifies a schema. SPML2 also defines an extensible set of optional capabilities, of which each capability may imply additional operations or semantics.

Bang for the buck. The primary purpose of this SIMPLEST profile is to provide the majority of function at a minimum of cost (in terms of implementation and overhead of operations). The SIMPLEST profile requires only the core operations of SPML2. The SIMPLEST profile also prescribes significant simplifications to how a requester and provider use these operations.

The secondary purpose of this SIMPLEST profile is to promote interoperability. The SIMPLEST profile assumes a very simple schema model. This SIMPLEST profile uses SAML 2.0 Attribute syntax because this syntax is both simple and general. This SIMPLEST profile defines a specific schema in order to promote interoperability.

The schema defines a set of object classes that represent entitities that are most common within the identity management domain. For each object class, the schema defines attributes that represent features and functions common to the identity management domain.

1.2. OrganizationThis document generally follows the organization of the SPML Specification document. Individual sections describe the interaction of requester and provider in the context of this SIMPLEST profile.

1.3. TerminologyWithin this document:- The term “requester” 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).

document.doc of 34

85

86

87

88

89909192

939495

96

979899100

101102103104

105106107108

109110111

112

113

114

115

116117

118

119120121122

5

- 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).

1.4. NotationThis 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 fontwith first letter lower-cased

The name of an XML attribute.

SPMLElementName monospace font with first letter capitalized

The name of an XML element that is defined as part of SPMLv2.

ns:ForeignElementName monospace fontwith namespace prefix

The name of an XML element that is defined by another specification.

<SPMLElement> monospace fontsurrounded by <>

An instance of an XML element that is defined as part of SPMLv2.

<ns:ForeignElement> monospace font with namespace prefixsurrounded by <>

An instance of an XML element that is defined by another specification.

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 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].

document.doc of 34

123124125

126

127128

129130131

132133

134135136137

138

139

140

141142

143144145146147148

6

2. Overview

3.

The SIMPLEST profile uses a schema syntax [ATTR] that is both simple and general.

The SIMPLEST profile assumes a specific schema in order to increase interoperability.

The SIMPLEST profile uses schema attributes to support common functions (such as password maintenance and access disablement) in order to minimize the number of operations that a requester and a provider must support.

The SIMPLEST profile specifies that a requester need not be aware of targets(except to preserve any targetID within a PSO Identifier).

The SIMPLEST profile specifies that execution must (appear to) be synchronous.See the section entitled “Execution Mode (normative)” below.

3.1. SchemaThis section defines a Standard Interoperable Multi-Purpose Lightweight Extensible Schema Template (SIMPLEST). SIMPLEST assumes that each object is represented as a collection of SAML Attributes [ATTR]. SIMPLEST specifies a standard set of attributes to use in representing several classes of object essential to the domain of identity management: Person, Account, Group and Role. These attributes describe common features of such objects. Identity Management commonly involves these features.

We call this a "Schema Template" because the standard set of attributes is not exhaustive. requester and provider may use additional attributes, but those attributes must not conflict with (and must not bypass) the standard attributes defined here. See Conformance.

3.1.1. PersonAn instance of the "Person" class normally represents a human being independent of any particular association with a computer system or application. (In some cases, an instance of "Person" may represent a pseudo-user or an entity other than an actual human being.)

The following attributes are defined for the Person object class. (The case of attribute names is not significant.) The first set of attributes (related to naming) is common to all object classes.

AttributeName Required/Optional

Syntax Multi-Valued?

Description

document.doc of 34

149

150

151

152

153

154155156

157158

159160

161

162

163

164165166167168169

170171172

173

174

175176177

178179

7

name R string SV The "friendly" identifier for this object.

DN O string SV Any DistinguishedName associated with this object. Normally unique within a particular service instance.

CN O string MV Any Common Name associated with the object. (Normally matches "name", although CN may have multiple values.)

GUID O string SV A globally unique and immutable identifier for the object.

The next set of attributes are common to both Person and Account. (The identity management industry does not always clearly distinguish the two.)



Description

logonID O string SV A short name (usually eight characters or fewer) that is used to access a computer system or application.

email O string MV Electronic mail address for this Person or Account.

password O string SV A token that is used (along with a logonID) to access a computer system or application.

passwordExpired O boolean SV If read as "true", indicates that the password value is no longer valid.

Set "true" in order to mark the current password value as no longer valid.(Set "false" in order to mark the current password value as valid.)

passwordExpireDate O dateTime SV Date and time the current password value is scheduled to expire.

Set a new value (in UTC format with no timezone) in order to change the date and time the current password value should expire.

Set to an empty value in order to remove the scheduled expiration.

passwordValid O string SV Not available when the object is read.

Set to a new value in order to determine whether the new value would be valid as a password for the object. Expect an error if the password would not be valid.

passwordReset O boolean SV If read as "true", indicates that the current password value was generated

document.doc of 34

180

181182

8

(and communicated to the Person out-of-band).

Set to "true" in order to replace the current password value with a generated value. (Expect the new password value to be communicated to the Person by other means.) The value will remain "true" until the Person sets a new password, at which time the value will be read as "false".

disabled O boolean SV If read as "true", indicates that all access by this Person or Account has been disabled.

Set "true" in order to disable all access by this Person or Account.

Set "false" in order to re-enable all access by this Person or Account.

disableDate O dateTime SV Date and time at which all access by this Person or Account is scheduled to be disabled.

Set a new value (in UTC format with no timezone) in order to change the date and time at which all access by this Person or Account is scheduled to be disabled.

Set to an empty value in order to remove the scheduled disablement.

enableDate O dateTime SV Date and time at which all access by this Person or Account is scheduled to be enabled.


Set to an empty value in order to remove the scheduled enablement.

groups O string MV Each value of the attribute identifies a Group to which this Person or Account belongs.

roles O string MV Each value of the attribute identifies a Role to which this Person or Account belongs.

resources O string MV Each value of this attribute identifies a resource to which this Person or Account has been granted access

document.doc of 349

explicitly.

(This Person or Account may have been granted implicit access to other resources by default or by virtue of Group or Role membership. Such implicit resources should not be included in the values of this attribute. See for comparison the "effectiveResources" attribute.)

privileges O string MV Each value of this attribute identifies a privilege that this Person or Account has been granted explicitly.

(This Person or Account may have been granted other implicit privileges by default or by virtue of membership in a Group or Role. Such implicit privileges should not be included in the values of this attribute. See for comparison the "effectivePrivileges" attribute.)

effectiveGroups O string MV Each value of this attribute identifies a Group to which this Person or Account belongs, whether directly or indirectly.

(This attribute represents a complete list of Groups to which this Person or Account belongs. See for comparison the "groups" attribute.)

effectiveRoles O string MV Each value of this attribute identifies another Role to which this Person or Account belongs, whether directly or indirectly.

(This attribute represents a complete list of Roles to which this Person or Account belongs. See for comparison the "roles" attribute.)

effectiveResources O string MV Each value of this attribute identifies a resource to which this Person or Account has been granted access, whether explicitly or implicitly.

(This attribute represents a complete list of resources to which this Person or Account has access. See for comparison the "resources" attribute.)

effectivePrivileges O string MV Each value of this attribute identifies a privilege that this Person or Account has been granted, whether explicitly or implicitly.

(This attribute represents a complete list of privileges this Person or Account has.

document.doc of 3410

See for comparison the "privileges" attribute.)

The final set of attributes is unique to Person.



Description

ownsAccounts O string MV Each value of this attribute identifies an Account that this Person owns (i.e., an Account that this Persons uses and for which this Person is responsible).

3.1.2. AccountAn instance of the "Account" class normally represents an identity of a particular Person within the scope of a computer system or application.

The following attributes are defined for the Account object class. (The case of attribute names is not significant.) The first set of attributes (related to naming) is common to all object classes.



Description





The next set of attributes are common to both Person and Account. (The identity management industry does not always clearly distinguish the two.)



Description

logonID O string SV A short name (usually eight characters or fewer) that is used to access a computer system or application.

Email O string MV Electronic mail address for this Person or Account.

Password O string SV A token that is used (along with a logonID) to access a computer system or application.

document.doc of 34

183

184

185

186

187188

189190

191

192193

11

passwordExpired O boolean SV If read as "true", indicates that the password value is no longer valid.

Set "true" in order to mark the current password value as no longer valid.(Set "false" in order to mark the current password value as valid.)

passwordExpireDate O dateTime SV Date and time the current password value is scheduled to expire.

Set a new value (in UTC format with no timezone) in order to change the date and time the current password value should expire.

Set to an empty value in order to remove the scheduled expiration.

passwordValid O string SV Not available when the object is read.

Set to a new value in order to determine whether the new value would be valid as a password for the object. Expect an error if the password would not be valid.

passwordReset O string SV If read as "true", indicates that the current password value was generated (and communicated to the Person out-of-band).

Set to "true" in order to replace the current password value with a generated value. (Expect the new password value to be communicated to the Person by other means.) The value will remain "true" until the Person sets a new password, at which time the value will be read as "false".

Disabled O boolean SV If read as "true", indicates that all access by this Person or Account has been disabled.

Set "true" in order to disable all access by this Person or Account.

Set "false" in order to re-enable all access by this Person or Account.

disableDate O dateTime SV Date and time at which all access by this Person or Account is scheduled to be disabled.



Set to an empty value in order to remove the scheduled disablement.

enableDate O dateTime SV Date and time at which all access by this Person or Account is scheduled to be enabled.


Set to an empty value in order to remove the scheduled enablement.

Groups O string MV Each value of the attribute identifies a Group to which this Person or Account belongs explicitly.

(This Person or Account may belong to other Groups implicitly--e.g., by virtue of Group nesting. Such implicit Groups should not be included in the values of this attribute. See for comparison the "effectiveGroups" attribute.)

Roles O string MV Each value of the attribute identifies a Role to which this Person or Account belongs explicitly.

(This Person or Account may belong to other Roles implicitly--e.g., by virtue of Role nesting. Such implicit Roles should not be included in the values of this attribute. See for comparison the "effectiveRoles" attribute.)

Resources O string MV Each value of this attribute identifies a resource to which this Person or Account has been granted access explicitly.

(This Person or Account may have been granted implicit access to other resources by default or by virtue of Group or Role membership. Such implicit resources should not be included in the values of this attribute. See for comparison the "effectiveResources" attribute.)

Privileges O string MV Each value of this attribute identifies a privilege that this Person or Account has been granted explicitly.

(This Person or Account may have been granted other implicit privileges by default or by virtue of membership in a


Group or Role. Such implicit privileges should not be included in the values of this attribute. See for comparison the "effectivePrivileges" attribute.)

effectiveGroups O string MV Each value of this attribute identifies a Group to which this Person or Account belongs, whether directly or indirectly.

(This attribute represents a complete list of Groups to which this Person or Account belongs. See for comparison the "groups" attribute.)

effectiveRoles O string MV Each value of this attribute identifies another Role to which this Person or Account belongs, whether directly or indirectly.

(This attribute represents a complete list of Roles to which this Person or Account belongs. See for comparison the "roles" attribute.)

effectiveResources O string MV Each value of this attribute identifies a resource to which this Person or Account has been granted access, whether explicitly or implicitly.

(This attribute represents a complete list of resources to which this Person or Account has access. See for comparison the "resources" attribute.)

effectivePrivileges O string MV Each value of this attribute identifies a privilege that this Person or Account has been granted, whether explicitly or implicitly.

(This attribute represents a complete list of privileges this Person or Account has. See for comparison the "privileges" attribute.)

The final set of attributes is unique to Account. (Account trades the "ownsAccount" attribute of Person with the inverse attribute "ownedByPerson". Account also adds the attributes "host" and "lockedOut".)



Description

ownedByPerson O string SV Identifies the Person who owns this Account (i.e., the Person who uses this Account and who is responsible for this Account).

Host O string SV Identifies the computer system or application that defines this Account.

document.doc of 34

194

195196197

14

lockedOut O boolean SV If read as "true", indicates that the host (computer system or application) has temporarily disabled access by this Account.

Set "true" in order to temporarily disable access to the host by this Account.

Set "false" in order to re-enable access to the host by this Account (if access was temporarily disabled due to lockout).

3.1.3. GroupAn instance of the "Group" class normally represents a collection of Persons or Accounts within the scope of a computer system or application. (In some cases, a Group may contain objects of other classes.)

The following attributes are defined for the Group object class. (The case of attribute names is not significant.) The first set of attributes (related to naming) is common to all object classes.



Description





The next set of attributes are common to both Group and Role. (The identity management industry does not always consistently distinguish the two.)



Description

description O string SV Text that describes this object.

resources O string MV Each value of this attribute identifies a resource to which membership in this Group or Role conveys access explicitly.

(Membership in this Group or Role may convey access to other resources implicitly --e.g., by default or by virtue of another Group or Role that this Group or Role contains. Such implicit resources should not be included in the values of this attribute. See for comparison the

document.doc of 34

198

199

200201202

203204

205

206207

15

"effectiveResources" attribute.)

privileges O string MV Each value of this attribute identifies a privilege that membership in this Group or Role conveys explicitly.

(Membership in this Group or Role may convey other privileges implicitly --e.g., by default or by virtue of membership in a Group or Role. Such implicit privileges should not be included in the values of this attribute. See for comparison the "effectivePrivileges" attribute.)

effectiveResources O string MV Each value of this attribute identifies a resource to which membership in this Group or Role conveys access, whether explicitly or implicitly.

(This attribute represents a complete list of resources to which membership in this Group or Role conveys access. See for comparison the "resources" attribute.)

effectivePrivileges O string MV Each value of this attribute identifies a privilege that membership in this Group or Role conveys, whether explicitly or implicitly.

(This attribute represents a complete list of privileges that membership in this Group or Role conveys. See for comparison the "privileges" attribute.)

The final set of attributes is unique to Group.



Description

containsGroups O string MV Each value of this attribute identifies another Group that this Group contains directly. (A Group that this Group contains only indirectly should not appear as a value of this attribute. See for comparison the "effectiveGroups" attribute.)

(What it means to contain another Group varies widely across systems and applications.)

effectiveGroups O string MV Each value of this attribute identifies another Group that this Group contains, whether directly or indirectly.

(This attribute represents a complete list of Groups that this Group contains. See for comparison the "containsGroups" attribute.)

document.doc of 34

208

209

16

3.1.4. RoleAn instance of the "Role" class normally represents an abstract description of a Person or Account that conveys a set of privileges or other attributes within the scope of a computer system or application. A Role may also function as collection of Persons or Accounts. (In some cases, a Role may contain objects of other classes.)

The following attributes are defined for the Role object class. (The case of attribute names is not significant.) The first set of attributes (related to naming) is common to all object classes.



Description


DN O string SV Any Distinguished Name associated with this object. Normally unique within a particular service instance.



The next set of attributes are common to both Group and Role. (The identity management industry does not always consistently distinguish the two.)



Description


resources O string MV Each value of this attribute identifies a resource to which membership in this Group or Role conveys access explicitly.

(Membership in this Group or Role may convey access to other resources implicitly --e.g., by default or by virtue of another Group or Role that this Group or Role contains. Such implicit resources should not be included in the values of this attribute. See for comparison the "effectiveResources" attribute.)

privileges O string MV Each value of this attribute identifies a privilege that membership in this Group or Role conveys explicitly.

(Membership in this Group or Role may convey other privileges implicitly --e.g., by default or by virtue of membership in a Group or Role. Such implicit privileges should not be included in the values of this attribute. See for comparison the

document.doc of 34

210

211212213214

215216

217

218219

17

"effectivePrivileges" attribute.)

effectiveResources O string MV Each value of this attribute identifies a resource to which membership in this Group or Role conveys access, whether explicitly or implicitly.

(This attribute represents a complete list of resources to which membership in this Group or Role conveys access. See for comparison the "resources" attribute.)

effectivePrivileges O string MV Each value of this attribute identifies a privilege that membership in this Group or Role conveys, whether explicitly or implicitly.

(This attribute represents a complete list of privileges that membership in this Group or Role conveys. See for comparison the "privileges" attribute.)

The final set of attributes is unique to Role. (Role trades the "containsGroup" attribute of Group with the analogous attribute "containsRole".)



Description

containsRole O string MV Each value of this attribute identifies another Role that this Role contains.

(What it means to contain another Role varies widely across systems and applications.)

effectiveRoles O string MV Each value of this attribute identifies another Role that this Role contains, whether directly or indirectly.

(This attribute represents a complete list of Roles that this Role contains. See for comparison the "containsRoles" attribute.)

3.1.5. OrganizationAn instance of the "Organization" class normally represents a container node in a hierarchy. Organization objects can be used to represent companies, departments, geographies, or other organizational constructs.

The following attributes are defined for the Organization object class. (The case of attribute names is not significant.) The first set of attributes (related to naming) is common to all object classes.

document.doc of 34

220

221222

223

224

225226227

228229

18



Description







Description


parentOrg O string MV Each value of this attribute identifies an organization that contains this organization.

(Normally single-valued. Multi-valued for matrix organizations.)

childOrg O string MV Each value of this attribute identifies an organization that this organization directly contains.

contactPerson O string MV Each value of this attribute identifies a contact person for this organization.

street O string MV

pobox O string MV

city O string MV

state O string MV

postalCode O string MV

country O string MV

phone O string MV

fax O string MV

email O string MV

document.doc of 34

230

231

19

3.2. Profile

4. ProtocolIn this profile, the schema-defined data for each PSO is a collection of SAML Attribute instances. The attributes in this collection should be consistent with the standard attributes defined in the Standard Interoperable Multi-Purpose Lightweight Extensible Schema Template (SIMPLEST). See the section entitled "Schema" above.

Since SPML2 treats the schema-defined XML representation of each object as an arbitrary payload, these attributes flow through the protocol requests as easily as any other schema-defined XML data. However, the choice of SAML Attributes as the XML representation for each object (together with simplifications that this profile specifies for the standard SPML2 operations) affects the manner in which a requester modifies and selects objects.

4.1. Execution Mode (normative)In the SIMPLEST profile, execution must be (or must appear to be) synchronous.

A requester MUST NOT request asynchronous execution.That is, an SPML request MUST NOT specify “executionMode=’asynchronous’”. An SPML request MAY specify “executionMode=’synchronous’” or (an SPML request MAY) omit “executionMode”.

A provider MUST respond as if the requested operation had been executed synchronously.That is, a provider’s response MUST NOT specify “status=’pending’” and (a provider’s response) MUST have the same content as it would have hadif the requested operation had been executed synchronously.

4.2. Identifiers XML PSOs

4.2.1. PSO Identifier (normative)Any value that uniquely identifies a PSO MAY serve as the PSO Identifier. A requester SHOULD treat the value of a PSO Identifier as opaque. (That is, a requester should not seek to decompose a PSO Identifier into significant parts, nor should a requester interpret the any part of the PSO Identifier.) A requester MUST specify as a PSO Identifier the complete <spml:psoID> element as it was received from the provider.

The provider MUST ultimately determine the PSO Identifier for an object. Where a requester suggests a PSO Identifier for an object (as in an addRequest), that requester MUST be prepared to accept instead any PSO Identifier that the provider returns (e.g., in the addResponse). A modify operation MAY also change the PSO Identifier for an object. A requester MUST be prepared to accept any PSO Identifier that the provider returns (in this case, in the modifyResponse).

1. The value of the "GUID" attribute (if it is available) makes the best identifier for a PSO, since a GUID value is globally unique and immutable.

2. The next best choice is the value of the "DN" attribute (if it is available), since the DN value is typically unique within a service instance.

document.doc of 34

232

233

234235236237

238239240241242

243

244

245246247248

249250251252

253

254

255

256257258259260

261262263264265

266267

268269

20

3. The value of the "logonID" attribute or the "email" attribute may also make an acceptable identifier for a PSO, since these values are likely to be relatively unique.

4. The value of the "name" attribute may also make an acceptable identifier for a PSO, as long as the name value is sufficiently unique.

Compound identifiers. Since the PSO Identifier may be any opaque identifier for the PSO, a provider may compose an "ID" value by combining several attribute values. For that matter, since the {spml:PSOIdentifierType} extends {spml:ExtensibleType}, a provider may inject additional attributes into the <spml:psoID> element.

However, these "compound" approaches tend to limit interoperability. Some XML parsers do not handle the {xsd:anyAttribute} syntax well. Furthermore, a requester may have trouble composing a PSO ID that follows the formula that suits the provider.

TargetID. The "targetID" attribute of an <spml:psoID> is optional. A provider that exposes only one target may omit the "targetID" attribute.

requesters that use the SIMPLEST profile are (for the most part) blind to targets. However, a requester must treat the PSO ID as an opaque token. (That is, any <spml:psoID> element that is supplied as part of a request must contain every attribute value and sub-element that the <spml:psoID> contained when it was received from the provider.)

Must be unique. Whatever value is (or whatever values are) used to construct a PSO ID, each PSO ID must resolve to a single PSO.

For instance if an opaque GUID is used for the PSO ID:

<spml:pso><spml:psoID ID="2244" targetID="target2"/>…

</spml:pso>

4.2.2. PSO DataThe PSO Data element contains samlattr:Attribute elements.

<spml:pso>…<spml:data>

<Attribute AttributeName="objectclass"><AttributeValue>Person</AttributeValue>

</Attribute><Attribute AttributeName="objectclass" AttributeNamespace="urn:SIMPLEST>

<AttributeValue>Person</AttributeValue></Attribute>

<name>John Doe</cn><cn>John Doe</cn><loginID>jdoe<uid><email>[email protected]</email><phone>

<home>555-2323</home><work>555-6767x321</work>

</phone></user>

</spml:data></spml:pso>

document.doc of 34

270271

272273

274275276277

278279280

281282

283284285286

287288

289

290291292293

294

295

296

297298299300301302303304305306307308309310311312313314315316

21

4.3.

4.4. Selection

4.5. Operations

4.5.1. Core Operations

4.5.1.1. listTargets

4.5.1.1.1. listTargetsRequest (normative)

A requester using the SIMPLEST profile does not strictly need the listTargets operation.

The requester does not care about targets and will not specify a targetID as part of any request (except to preserve any targetID that occurs within an <spml:psoID> -- see the section entitled "PSO Identifier" above.)

The SIMPLEST profile fixes the schema model and the standard attributes.

Standard attributes of the SIMPLEST profile support functions that are equivalent to the (functions of the optional operations defined by the) Password Capability and Suspend Capability.

Standard attributes of the SIMPLEST profile represent common relationships that might otherwise be represented as references using the Reference Capability.

a requester that wishes to use optional operations (such as those defined as part of the Search Capability, Batch Capability or Bulk Capability) must be prepared to detect and handle errors when a provider does not support such optional operations.

SPML2 requires that each provider implement the listTargets operation. However, since the SIMPLEST requester needs very little information from it, a provider that wishes to support only the SIMPLEST profile may return a minimal response.

<spml:listTargetsResponse status="success"><spml:target targetID=”target1”>

<spml:schema ref=urn:oasis:names:tc:SPML:2.0:SIMPLEST/></spml:target>

</listTargetsResponse>

This response declares that the provider supports only a single target, and that the provider's only target supports the SIMPLEST schema.

document.doc of 34

317

318

319

320

321

322

323

324

325

326327328

329

330331332

333334

335336337

338339340

341342343344345

346347

22

http://www.acme.com/schemas/user.xsd

4.5.1.1.2. listTargetsResponse (normative)

4.5.1.1.3. listTargets Examples

4.5.1.2. add

4.5.1.2.1. addRequest (normative)

The Add Request creates PSOs. The Add Request must contain a <data> element that contains one or more SAML Attributes that define the new PSO. The Add Request may also pass a PSO Identifier (<psoId> 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:data>

<Attribute AttributeName="name"<AttributeValue>John Doe</AttributeValue>

</Attribute><Attribute AttributeName="logonID"

<AttributeValue>jdoe</AttributeValue></Attribute><Attribute AttributeName="email"

<AttributeValue>[email protected]</AttributeValue></Attribute><Attribute AttributeName="objectclass"

<saml:AttributeValue>Person</AttributeValue></Attribute>

</spml:data></spml:addRequest >

4.5.1.2.2. addResponse (normative)

The Add Response would contain the status. If the request is successful, the response could include the new PSO ID and data. For instance:

<spml:addResponse status="spml:success"><spml:psoID ID="e83912:10540392175:-8000"/><spml:data>

<Attribute AttributeName="name"<AttributeValue>John Doe</AttributeValue>

</Attribute><Attribute AttributeName="CN"

<AttributeValue>John Doe</AttributeValue></Attribute><Attribute AttributeName="GUID"

<AttributeValue>e83912:10540392175:-8000</AttributeValue></Attribute><Attribute AttributeName="logonID"

<AttributeValue>jdoe</AttributeValue></Attribute><Attribute AttributeName="email"

<AttributeValue>[email protected]</AttributeValue></Attribute><Attribute AttributeName="objectclass"

<saml:AttributeValue>Person</AttributeValue></Attribute>

document.doc of 34

348

349

350

351

352353354355

356357358359360361362363364365366367368369370371372

373

374375

376377378379380381382383384385386387388389390391392393394395396

23

</spml:data></spml:addResponse>

4.5.1.2.3. add Examples

4.5.1.3. lookup

4.5.1.3.1. lookupRequest (normative)

The Lookup Request returns the data for an identified PSO. The Lookup Request always contains the PSO Identifier.

<spml:lookupRequest returnData = "spml:everything"><spml:psoID ID="2244" targetID="target2"/>

</spml:lookupRequest>

4.5.1.3.2. lookupResponse (normative)

The Lookup Response (if successful) will return the data for the identified PSO.

<spml:lookupResponse><spml:psoID ID="2244" targetID="target2"/><spml:data>

<user><cn>John Doe</cn><uid>jdoe<uid><email>[email protected]</email><phone>

<mobile>555-1212</mobile><home>555-2323</home><work>555-6767x321</work>

</phone></user>

</spml:data></spml:lookupResponse>

4.5.1.3.3. lookup Examples

4.5.1.4. modify

4.5.1.4.1. modifyRequest (normative)

The Modify Request modifies PSOs. The Modify Request always contains the PSO Identifier and at least one <spml:modification>. ModificationMode can be one of 'add', 'replace' or 'delete'.

Add. Adding a new attribute is simple. Adding a new attribute that matches an existing attribute (i.e., an attribute that has the same attributeName and AttributeNamespace as an existing Attribute of the object) simply adds to the existing Attribute any AttributeValue from the new Attribute that the existing Attribute does not already contain.

Delete. Deleting an attribute is also simple. Any attribute that is optional may be deleted. The requester uses the <component> (sub-element of <modification>) to specify the attribute to delete.

document.doc of 34

397398399

400

401

402

403404

405406407

408

409

410411412413414415416417418419420421422423424

425

426

427

428429

430431432433

434435436

24

"path" specifies the AttributeName of the attribute to delete.

"namespaceURI" specifies the AttributeNamespace of the attribute to delete.

Deleting a specific attribute value, however, is not simple. There is no syntax to specify which value should be deleted. (Unless we want to say that path may specify both attributeName and attributeValue, as for example in "path='name/John Doe'".) Instead, a requester must replace the attribute. See the "Replace" topic below within this section.)

Replace. Each attribute that is specified as within the modification's <data> element replaces any corresponding attribute of the object entirely (i.e., including all values of the attribute). In fact, the way to delete a specific attribute value is to replace the attribute with (a new copy of the attribute that contains) all of the current values except the value to be deleted.

A strict provider may treat as an error a request to replace an attribute that does not currently exist in the object, but a lax provider should simply add the attribute.

<spml:modifyRequest ><spml:psoID ID="e83912:10540392175:-8000"/><spml:modification modificationMode="spml:replace">

<spml:data><Attribute AttributeName="name"

<AttributeValue>Jane Doe</AttributeValue></Attribute>

</spml:data></spml:modification>

</spml:modifyRequest>

To replace a sub-element:

<spml:modifyRequest ><spml:psoID ID="2244" targetID="target2"/><spml:modification modificationMode="spml:replace" >

<spml:component path="./phone" namespaceURI="http://www.w3.org/TR/xpath20"/>

<spml:data><phone>

<mobile>555-1212</mobile><home>555-2323</home><work>555-6767x321</work>

</phone></spml:data>

</spml:modification></spml:modifyRequest>

To delete a sub-element:

<spml:modifyRequest ><spml:psoID ID="2244" targetID="target2"/><spml:modification modificationMode = "spml:delete" >

<spml:component path="./phone" namespaceURI="http://www.w3.org/TR/xpath20"/>

</spml:modification></spml:modifyRequest>

document.doc of 34

437

438

439440441442

443444445446

447448

449450451452453454455456457458459460461462

463

464465466467468469470471472473474475476477478

479

480481482483484485486

25

http://www.w3.org/TR/xpath20

http://www.w3.org/TR/xpath20

4.5.1.4.2. modifyResponse (normative)

4.5.1.4.3. modify Examples

4.5.1.5. delete

4.5.1.5.1. deleteRequest (normative)

The Delete Request deletes PSOs. The Delete Request always contains the PSO Identifier.

<spml:deleteRequest><spml:psoID ID="2244" targetID="target2"/>

</spml:deleteRequest >

4.5.1.5.2. deleteResponse (normative)

4.5.1.5.3. delete Examples

4.5.2. Search CapabilityThe SIMPLEST profile requires only the core operations that SPML2 requires. However, the search operation is very desirable to most requesters, and this profile recommends that a provider support the search operation (if the provider finds it practical to do so).

The Search Capability of SPML2 defines three operations: search, iterate, and closeIterator. This profile recognizes that a provider may not wish to support all the operations of the Search Capability.

SPML2 specifies that a provider that declares support for a capability must support all of the operations that the capability defines. In order to comply with the SPML2 specification, a provider that wishes not to support the iterate operation or (not to support) the closeIterator operation MUST NOT declare in its listTargetsResponse that it supports the Search Capability (for any target that specifies SIMPLEST as its schema).

A requester that uses the SIMPLEST profile SHOULD NOT rely on a provider’s declaration of support for the Search Capability to indicate whether the provider supports the search operation. Instead, a SIMPLEST requester that wishes to use the search operation should try to do so and SHOULD be prepared to handle a response that specifies “error=’unsupportedOperation’”.

A provider that wishes not to support the iterate operation or (not to support) the closeIterator operation SHOULD implement the operations so as to return a minimal response that specifies “error=’unsupportedOperation’”. A provider that wishes not to support the ‘search’ operation SHOULD implement the ‘search’ operations so as to return a minimal response that specifies “error=’unsupportedOperation’”.

4.5.2.1. search

4.5.2.1.1. searchRequest (normative)

The search request can specify a search base and an XPath selection statement.

document.doc of 34

487

488

489

490

491

492493494

495

496

497

498499500

501502503

504505506507508

509510511512513

514515516517518

519

520

521

26

<spmlsearch:searchRequest><spmlsearch:query scope = "spmlsearch:oneLevel" targetID="target2"> <spml:select>/user</spml:select></spmlsearch:query>

</spmlsearch:searchRequest>

The select clause for the search request treats each target as a document root that (directly or indirectly) contains all other objects as nodes. So, for example,

"/Person" would select every Person object that the target directly contains.

"//Person" would select every Person object on a target, no matter which container was the Person object's parent.

"/Group" would select every Group object that the target directly contains.

"//Group" would select every Group object on a target, no matter which container was the Group object's parent.

4.5.2.1.2. searchResponse (normative)

4.5.2.1.3. search Examples

The search response, if successful, would contain all of the PSOs that satisfied the search criteria. For instance:

<spml:searchResponse status = "spml:success"><spml:pso>

<spml:psoID ID="2244" targetID="target2"/><spml:data>

<user><cn>John Doe</cn><uid>jdoe<uid><email>[email protected]</email>

</user></spml:data>

</spml:pso><spml:pso>

<spml:psoID ID="2245" targetID="target2"/><spml:data>

<user><cn>Jane Smith</cn><uid>jsmith<uid><email>[email protected]</email>

</user></spml:data>

</spml:pso></spml:searchResponse>

5. Conformance (normative)Schema Conformance. A requester and provider MAY use object classes in addition to those defined in the SIMPLEST schema. A requester or provider MUST NOT use an object class that conflicts with an object class that the SIMPLEST schema defines. A requester or provider MUST NOT use an object class that bypasses (i.e., duplicates the intended function of) an object class that the SIMPLEST schema defines.

document.doc of 34

522523524525526

527528

529

530531

532

533534

535

536

537538

539540541542543544545546547548549550551552553554555556557558559560561

562

563564565566567

27

A requester or provider MAY use attributes in addition to those required by the object class that the SIMPLEST schema defines. Those attributes must not conflict with (and must not bypass) the standard attributes defined here. In addition, a compliant requester or provider must not use additional attributes that duplicate the function of these standard attributes without also supporting the functionally equivalent standard attributes. A compliant requester or provider SHOULD convert those additional attributes to the functionally equivalent standard attributes (rather than duplicating the function with additional attributes), but simple duplication does not

6. Specification (Normative)

6.1. Namespaces

6.2.

6.3. Core Capability

6.3.1. Element <spml:data> The <spml:data> element MAY contain any number of XML elements. The elements MUST conform to the XSD specified in the spml:schema for that target.

6.3.2. Element <spml:modification>The <spml:modification> element MAY contain any number of XML elements. The <spml:modification> element MUST define the “modificationMode” attribute to be one of “add”, “replace”, or “delete”.

An <spml:modification> element MAY contain at most one <component> element. If the modification is on a sub-element of the PSO data, the component element MUST be set to the XPath state that uniquely identifies the sub-element withen the PSO data root element. If the modification is on the PSO data root element, the component element MAY be omitted.

An <spml:modification> element MAY contain at most one <data> element. If the <spml:modification> contains a <component> element, then the <spml:modification> MUST contain a <data> element.

Modification component. An <spml:component> element MUST have a “namespaceURI” attribute and MUST have a “path” attribute.

The value of the “namespaceURI” attribute MUST specify the XML namespace of a query language. The value of the “path” attribute MUST be an expression that is valid in the query language that “namespaceURI” specifies. (For example, if a requester uses XPath 2.0 as the query language for the “path” attribute, the value of the “namespaceURI” attribute MUST be "http://www.w3.org/TR/xpath20".)

document.doc of 34

568569570571572573574

575

576

577

578

579

580

581

582

583584

585

586587588

589590591592

593594595

596597

598599600601602

28

The value of the “path” attribute MUST specify an attribute or a sub-element (or an attribute of a sub-element) of the object that the provider is to modify. The specified attribute or element MUST be valid (according to the schema of the target) for the schema entity of which the object to be modified is an instance.An <spml:component> element MAY include <spml:namespacePrefixMap> elements that defines the namespace prefixes that are used in the XPath path. Each “prefix” attribute on the <spml:namespacePrefixMap> element MUST exactly match one the namespace prefixes used in the Xpath.

Modification data. A requester must specify as the content of the <data> sub-element of a <modification> any value that is to be added to, replaced within, or deleted from the element or attribute that the <component> element specifies.

In the XML Schema profile, a requester that specifies a <component> element within a <modification> element with “modificationMode=’add’” or (within a <modification> element with) “modificationMode=’modify’” MUST specify a value that is to replace the element or attribute that the <component> element specifies.

If the <component> element (XPath expression) specifies an XML element, then the value (that is the content of the <data> element) MUST be one or more XML elements that are valid (according to the schema of the target) for the element that the <component> element specifies.

If the <component> element (XPath expression) specifies an XML attribute, then the value MUST be valid (according to the schema of the target) for the attribute that the <component> element specifies.

In the XML Schema profile, a requester that specifies a <component> element within a <modification> element with “modificationMode=’delete’” MUST NOT specify a value. The (XPath expression that is the value of the) <component> element MUST specify the set of elements or (MUST specify) the attribute that the provider should delete.

If the <component> element (XPath expression) specifies a set of XML elements, then each XML element that the <component> element specifies must be optional (i.e., “minOccurs=’0’”) according to the schema of the target for the object to be modified.

If the <component> element (XPath expression) specifies an XML attribute, then the specified attribute MUST be optional (according to the schema of the target) for the object to be modified.

6.3.3. Element <spml:schema>If the schema is included as content of an <spml:schema> element, the <spml:schema> element MUST contain at least one <xsd:schema> element. If the schema is not included as content of an <spml:schema> element, the “ref” attribute on the <spml:schema> element MUST be set to the URN of the referenced schema. If the schema is included as content of an <spml:schema> element, a requester should ignore any “ref” attribute on the <spml:schema> element.

If a provider supports only a subset of the top-level elements that are defined in the schema for a target, then the <spml:schema> element MUST contain at least one <spml:supportedSchemaEntity> element. Each <spml:supportedSchemaEntity> element specifies a top-level schema element that the provider supports for that target.

If the <spml:schema> element contains no <spml:supportedSchemaEntity> element, then the requester may assume that the provider supports for that target all of the top-level elements that the schema of the target defines.

document.doc of 34

603604605606607608609610

611612613

614615616617

618619620621

622623624

625626627628

629630631

632633634

635

636637638639640

641642643644

645646647

29

6.3.4. Element <supportedSchemaEntity>The “entityName” attribute on the <spml:supportedSchemaEntity> element MUST refer to a top-level element that is defined in the schema for a target. The provider MUST support every sub-element and attribute of the referenced schema element.

6.4. Search Capability

6.4.1. Element <spmlsearch:query>The <spmlsearch:query> element MUST contain (as open content) at least one <saml:Attribute> instance. The set of <saml:Attribute> instances that an <spmlsearch:query> element contains are to be interpreted as a filter as follows:

Each <saml:Attribute> is interpreted as an attribute condition. In order to match an attribute condition, an object must contain an attribute with the same AttributeName and with the same AttributeNamespace that the attribute condition specifies.

- Multiple AttributeValues within an attribute condition are logically ORed.(That is, if an attribute condition specifies more than one AttributeValue, then the corresponding attribute of a matching object must contain an AttributeValue that matches at least one AttributeValue that the attribute condition specifies.)

- A single, empty AttributeValue matches any AttributeValue. (That is, any object that has an AttributeValue for the corresponding attribute matches an attribute condition that specifies only one AttributeValue element that has no content.)

Attribute conditions are logically ANDed. An object must satisfy every attribute condition in order satisfy the set of attribute conditions.

6.4.2.

document.doc of 34

648

649650651

652

653

654655656

657658659660

661662663664

665666667668

669670

671

672673

674

30

Appendix A. References

[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

[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

[RFC2119] S. Bradner., Key words for use in RFCs to Indicate Requirement Levels, http://www.ietf.org/rfc/rfc2119.txt, IETF

[DSML] OASIS Directory Services Markup TC., DSML V2.0 Specification, http://www.oasis-open.org/apps/org/workgroup/dsml/documents.php, OASIS DS-TC

[SAML] OASIS Security Services Technical Committee., XMLTitle, http://www.oasis-open.org/apps/org/workgroup/sstc/documents.php, OASIS SS-TC

[DS] IETF/W3C., W3C XML Signatures, http://www.w3.org/Signature/, W3C/IETF

[XS] W3C Schema WG ., W3C XML Schema, http://www.w3.org/TR/xmlschema-1/ W3C

[ATTR] OASIS Security Services Technical Committee., SAML V1.0 Assertion Schema, http://www.oasis-open.org/committes/security/docs/cs-sstc-schema-assertion-01.xsd

[SPML-Bind]] OASIS Provisioning Services Technical Committee., 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

document.doc of 34

675

676677678679

681682683

685686

688689690

692693694

696697

699700

701702703704705

707708709710711

713

714

31

http://www.w3.org/TR/xmlschema-1/

Appendix B. AcknowledgmentsThe following individuals were voting members of the Provisioning Services committee at the time that this version of the specification was issued:List Members Here:

document.doc of 34

715

716717718719720

32

Appendix C. Revision historyRev Date By whom What

D-01 22 July 2005 Editor 0.1 Rough Draft

document.doc of 34

722

723

724

33

Appendix D. NoticesOASIS 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 implementers or users of this specification, can be obtained from the OASIS Executive Director.

OASIS has been notified of intellectual property rights claimed in regard to some or all of the contents of this specification. For more information consult the online list of claimed rights.

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 Executive Director.

Copyright (C) OASIS Open 2004. 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 may 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.

document.doc of 34

725

726727728729730731732733734

735736

737738739

740

741742743744745746747748

749750

751752753754755

34

lists.oasis-open.orglists.oasis-open.org/archives/provision/200602/doc0000… · web viewmartin...

Documents