idnits 2.17.1 draft-hunt-scim-targeting-01.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** There are 3 instances of lines with control characters in the document. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (September 6, 2012) is 4248 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'RFC2119' is mentioned on line 120, but not defined == Unused Reference: 'KEYWORDS' is defined on line 509, but no explicit reference was found in the text Summary: 1 error (**), 0 flaws (~~), 3 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT P. Hunt 3 Intended Status: Proposed Standard Oracle 4 Expires: March 10, 2013 K. Grizzle 5 Sailpoint 6 September 6, 2012 8 SCIM Targeted Resource Extension 9 draft-hunt-scim-targeting-01 11 Abstract 13 The core SCIM 1.0 specification is intended to provide updates to a 14 single cloud-based application. This extension specifies an extended 15 API definition which allows a single SCIM endpoint to support updates 16 to multiple cloud-based applications. These extensions enable network 17 relationships such as proxy updates, and hub-to-hub-to-spoke 18 relationships in addition to the hub-spoke relationship defined in 19 the core SCIM 1.0 specification. 21 Status of this Memo 23 This Internet-Draft is submitted to IETF in full conformance with the 24 provisions of BCP 78 and BCP 79. 26 Internet-Drafts are working documents of the Internet Engineering 27 Task Force (IETF), its areas, and its working groups. Note that 28 other groups may also distribute working documents as 29 Internet-Drafts. 31 Internet-Drafts are draft documents valid for a maximum of six months 32 and may be updated, replaced, or obsoleted by other documents at any 33 time. It is inappropriate to use Internet-Drafts as reference 34 material or to cite them other than as "work in progress." 36 The list of current Internet-Drafts can be accessed at 37 http://www.ietf.org/1id-abstracts.html 39 The list of Internet-Draft Shadow Directories can be accessed at 40 http://www.ietf.org/shadow.html 42 Copyright and License Notice 44 Copyright (c) 2012 IETF Trust and the persons identified as the 45 document authors. All rights reserved. 47 This document is subject to BCP 78 and the IETF Trust's Legal 48 Provisions Relating to IETF Documents 49 (http://trustee.ietf.org/license-info) in effect on the date of 50 publication of this document. Please review these documents 51 carefully, as they describe your rights and restrictions with respect 52 to this document. Code Components extracted from this document must 53 include Simplified BSD License text as described in Section 4.e of 54 the Trust Legal Provisions and are provided without warranty as 55 described in the Simplified BSD License. 57 Table of Contents 59 1 Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 60 2. Service Provider Types . . . . . . . . . . . . . . . . . . . . 3 61 2.1 Spoke Service Provider . . . . . . . . . . . . . . . . . . . 3 62 2.2 Hub Service Provider . . . . . . . . . . . . . . . . . . . . 4 63 2.3 Gateway Service Provider . . . . . . . . . . . . . . . . . . 4 64 3. Extended Resource API . . . . . . . . . . . . . . . . . . . . 4 65 3.1 Local Endpoints . . . . . . . . . . . . . . . . . . . . . . 4 66 3.2 Targeted Operations . . . . . . . . . . . . . . . . . . . . 4 67 4 Schema . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 68 4.1 Attributes (multi-valued) . . . . . . . . . . . . . . . . . 6 69 4.2 SCIM Target Schema . . . . . . . . . . . . . . . . . . . . . 6 70 5 JSON Representation . . . . . . . . . . . . . . . . . . . . . . 6 71 5.1 User with Targeted References Representation . . . . . . . . 6 72 5.2 Server Config with Targeting Representation . . . . . . . . 7 73 5.3 Target Representation . . . . . . . . . . . . . . . . . . . 8 74 5.4 Target Resource Schema Extensions . . . . . . . . . . . . . 9 75 6 XML Schema Representation . . . . . . . . . . . . . . . . . . . 11 76 7 Security Considerations . . . . . . . . . . . . . . . . . . . . 12 77 8 IANA Considerations . . . . . . . . . . . . . . . . . . . . . . 12 78 9 References . . . . . . . . . . . . . . . . . . . . . . . . . . 12 79 9.1 Normative References . . . . . . . . . . . . . . . . . . . 12 80 9.2 Informative References . . . . . . . . . . . . . . . . . . 12 81 Appendix A - Editors Notes . . . . . . . . . . . . . . . . . . . . 12 82 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 84 1 Introduction 86 This specification extends the SCIM Protocol [draft-scim-api-00] and 87 [draft-scim-core-schema-00] to enable a SCIM service endpoint to act 88 as a 'gateway' to process requests intended for other connected cloud 89 services called 'targets'. A gateway is essentially a proxy that 90 front-ends one or more applications for the purpose of provisioning. 91 The gateway may act as a simple proxy, or it may act as a hub storing 92 data to be used directly or indirectly by other cloud systems. A 93 'target' is a logical representation of a remotely connected system 94 to be provision. Such a system may be in-turn, connected via SCIM or 95 some other API supported by the gateway node. The targeting extension 96 is intended to support all SCIM operations and layers on top of SCIM 97 1.0. 99 The target resource extensions allow requesting clients to make 100 updates to entities within the gateway itself and additionally, 101 updates to be routed by the gateway to specific target end-points. 103 +----------+ 104 |CRM Target| 105 +--+-------+ 106 | 107 +------+ +-------+---+ 108 |Client|--------->|Gateway/Hub| 109 +------+ +-------+---+ 110 | 111 +---+--------+ 112 |Email Target| 113 +------------+ 115 1.1 Terminology 117 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 118 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 119 document are to be interpreted as described in RFC 2119 [RFC2119]. 121 2. Service Provider Types The following non-normative section describes 122 3 different types of service providers to illustrate how SCIM 123 Resource Targeting may be used. With resource targeting, SCIM service 124 providers are broken into 3 types: Spoke, Hubs, and Gateways. Each 125 service provider has different capabilities and are used together to 126 form a complete provisioning infrastructure. 128 2.1 Spoke Service Provider A spoke service provider is a SCIM service 129 provider where accounts are to be provisioned using the SCIM 1.0 130 APIs. It usually represents a single logical repository of 131 identities. 133 2.2 Hub Service Provider A hub service provider offers the same features 134 of a spoke, but it can also provision resources to connected service 135 providers known as "targets". A "target" is a SCIM service provider 136 that implements SCIM protocol or another protocol in such a way that 137 it appears to accept SCIM transactions. Resources stored in the hub 138 can be associated with "target" provisioned resources through the use 139 of a complex attribute "accountRefs" which links hub resources to 140 resources in target service providers. 142 2.3 Gateway Service Provider A gateway is similar to a SCIM hub except 143 that it has no local repository and is therefore stateless. Typically 144 a gateway is used as an architectural component to firewall direct 145 access to individual SCIM Service Provider endpoints by allowing 146 transactions to flow through a common gateway. 148 3. Extended Resource API 150 The SCIM protocol specifies well known endpoints and HTTP methods for 151 managing Resources defined in the core schema such as User and Group 152 resources. The core schema defines key Relative Resource URLs which 153 can be used to perform SCIM operations. 155 In addition to the endpoints defined in section 3 of [draft-scim-api- 156 00], the following endpoints are defined: 158 3.1 Local Endpoints 160 In SCIM 1.0, all operations are presumed to occur on the current end- 161 point. SCIM Hub and Gateway servers have additional server endpoints 162 that enable discovery of Target entities where transactions can be 163 routed. 165 /Targets 166 [Operations: GET] 167 Use in GET operations to retrieve a list of logical target 168 entities available within the current SCIM server. The information 169 can be used by the client to discover provisioning end-points 170 accessible via the current SCIM service provider. 172 /Targets/{target_id} 173 [Operations: GET] 174 Use in GET operations to retrieve information about a particular 175 Target identified by {target_id}. 177 3.2 Targeted Operations 179 Targeting extends the SCIM protocol so that SCIM operations can be 180 routed to a logical server. Targeting adds a prefix to the 181 endpoint path to all normal SCIM operations as follows. 183 /Targets/{target_id}/{scim-endpoint-url} 184 [Operations: All] 185 This general pattern indicates that a transaction is to be routed 186 to a target identified by {target_id}. {scim-endpoint-url} is any 187 valid SCIM 1.0 relative endpoint URL. The routed operation MAY in 188 turn be another SCIM protocol call. However it MAY ALSO be over a 189 different protocol as long as it behaves within the hub or gateway 190 as a SCIM operation. 192 For example: 193 /Targets/crm/Users/2819c223-7f76-453a-919d-413861904646 195 /Targets/{target_id}/ServerProviderConfigs 196 [Operations: Get] 197 Retrieves the service provider configuration of the target 198 identified by the logical target identifier {target_id}. Included 199 in the server configuration MAY be the 'type' attribute which 200 specifies the server type of 'spoke', 'gateway', or 'hub' and 201 defaults to 'spoke'. If target communication is not via SCIM, the 202 target 'connector' should behave as if it was. The 203 ServerProviderConfig returned SHOULD reflect the real SCIM 204 endpoint configuration, or the equivalent if SCIM protocol is not 205 used to connect the Target Service Provider. 207 /Targets/{target_id}/Schemas 208 [Operations: Get] 209 Retrieves the targeted service provider's schema. The schema 210 returned should reflect the Target Service Provider's schema or 211 the equivalent if SCIM protocol is not used to connect the Target 212 Service Provider. 214 /Targets/{target_id}/Users 215 /Targets/{target_id}/Groups 216 [Operations: All] 217 Retrieves/updates the User or Group entities from {target_id} as 218 if the request was sent directly to {target_id}. 220 /Targets/{target_id}/Users/{user_id}' 221 [Operations: All] 222 References the User entity {user_id} within the Target identified 223 by {target_id}. 225 /Targets/{target_id}/Bulk 226 [Operations: ALL] 227 Perform bulk operations on a specified target service provider. 229 4 Schema 231 To supported targeted operations, additional schema is defined to 232 support new schema objects namely "targets" and to support 233 extensions to User and Group objects. To support targeted 234 operations, the SCIM schema is extended per section 4 of [draft- 235 scim-core-schema-00]. 237 When extending schema to support targeting, the following URI MUST 238 be added to the "schemas" attribute URI: 239 'urn:scim:schemas:extension:targeted:1.0'. 241 4.1 Attributes (multi-valued) 243 accountRefs A complex multi-valued attribute containing references 244 to associated resources in other targets. Each reference consists 245 of a target identifier and a User object identifier. For each 246 targetId, there may be one or more related object identifiers 247 within each target. An individual identifier can be designated as 248 a primary within a target. 250 4.2 SCIM Target Schema The Target extension provides a schema for 251 representing the Service Provider's configured target entities 252 identified using the following URI: 253 'urn:scim:schemas:extension:targeted:1.0'. 255 The Target Resource enables a Service Provider to expose the 256 addressable targets reachable within the Service Provider as 257 gatewayed entities. All attributes are READ-ONLY. 259 5 JSON Representation 261 5.1 User with Targeted References Representation 263 The following is a non-normative example of a minimal SCIM 264 representation of a User extended with targeted references in JSON 265 format. The example user has 2 email accounts and one CRM account. 267 { 268 "schemas": 269 [ 270 "urn:scim:schemas:core:1.0", 271 "urn:scim:schemas:extensions:targeted:1.0:resourceRef" 272 ], 273 "id": "2819c223-7f76-453a-919d-413861904646", 274 "userName": "bjensen@example.com" 275 "urn:scim:schemas:extensions:targeted:1.0":{ 276 "accountRefs":[ 277 { 278 "targetId":"mail" 279 "Display":"Cloud Email Service" 280 "references":[ 281 { 282 "type":"User", 283 "value":"bjensen@example.com", 284 "primary":true 285 }, 286 { 287 "type":"User", 288 "value":"b.jensen@example.com" 289 } 290 ] 291 }, 292 { 293 "targetId":"crm" 294 "Display":"Customer Relationship Management Service" 295 "references":[ 296 { 297 "type":"User", 298 "value":"2819c223-7f76-453a-919d-413861904646", 299 "primary":true 300 } 301 ] 302 } 303 ] 304 } 305 } 307 [[Does it make sense to reference Group objects? Others?]] 309 5.2 Server Config with Targeting Representation The following is a non- 310 normative example of server configuration with targeting schema 311 (indicating the server is a SCIM provisioning "hub") in JSON 312 format. 314 { 315 "schemas": ["urn:scim:schemas:core:1.0", 316 "urn:scim:schemas:extensions:targeted:1.0"], 317 "documentationUrl":"http://example.com/help/scim.html", 318 "patch": { 319 "supported":true 320 }, 321 "bulk": { 322 "supported":true, 323 "maxOperations":1000, 324 "maxPayloadSize":1048576 326 }, 327 "filter": { 328 "supported":true, 329 "maxResults": 200 330 }, 331 "changePassword" : { 332 "supported":true 333 }, 334 "sort": { 335 "supported":true 336 }, 337 "etag": { 338 "supported":true 339 }, 340 "xmlDataFormat": { 341 "supported":true 342 }, 343 "authenticationSchemes": [ 344 { 345 "name": "OAuth Bearer Token", 346 "description": 347 "Authentication Scheme using the OAuth Bearer Token", 348 "specUrl": 349 "http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-01", 350 "documentationUrl":"http://example.com/help/oauth.html", 351 "type":"oauthbearertoken", 352 "primary": true 353 }, 354 { 355 "name": "HTTP Basic", 356 "description": "Authentication Scheme using the Http Basic", 357 "specUrl":"http://www.ietf.org/rfc/rfc2617.txt", 358 "documentationUrl":"http://example.com/help/httpBasic.html", 359 "type":"httpbasic" 360 } 361 ], 362 "urn:scim:schemas:extensions:targeted:1.0": [ 363 { 364 "type":"hub" 365 } 366 ] 367 } 369 5.3 Target Representation 371 The following is a non-normative example of the representation of 372 a Target object in JSON format. 374 { 375 "schemas":["urn:scim:schemas:core:1.0", 376 "urn:scim:extensions:targeted:1.0"], 377 "id" : "mail", 378 "description" : "Corporate imap service", 379 "type" : "spoke" 380 } 382 5.4 Target Resource Schema Extensions 384 The following is a normative example of the SCIM Targeted schema 385 extension representation in JSON format. 387 { 388 "id": 389 "urn:scim:schemas:extensions:targeted:1.0:resourceRef", 390 "name":"Targeted", 391 "description":"Targeted Resource Extension", 392 "schema": 393 [ 394 "urn:scim:schemas:core:1.0", 395 "urn:scim:schemas:extensions:targeted:1.0" 396 ], 397 "attributes":[ 398 { 399 "name":"accountRefs", 400 "type":"complex", 401 "multiValued":true, 402 "multiValuedAttributeChildName":"targetId", 403 "schema":[ 404 "urn:scim:schemas:core:1.0", 405 "urn:scim:schemas:extensions:targeted:1.0" 406 ] 407 "readOnly":false, 408 "required":false, 409 "caseExact":true, 410 "subAttributes":[ 411 { 412 "name":"targetId", 413 "type":"string", 414 "multiValued":false, 415 "description":"Identifier of target system where 416 one or more related resources can 417 be found", 418 "readOnly":false, 419 "required":true, 420 "caseExact":false 421 }, 422 { 423 "name":"display", 424 "type":"string", 425 "multiValued":false, 426 "description":"A human readable description of 427 target used for display purposes", 428 "readOnly":true, 429 "required":false, 430 "caseExact":false 431 }, 432 { 433 "name":"references", 434 "type":"complex", 435 "multiValued":true, 436 "description":"A set of one or more target references 437 for the object within the target. 438 "readOnly":false, 439 "required":true, 440 "caseExact":false 441 "subAttributes":[ 442 { 443 "name":"type", 444 "type": "string", 445 "multiValued":false, 446 "required":true, 447 "canonicalValues":["User","Group"] 448 }, 449 { 450 "name":"value", 451 "type":"string", 452 "multiValued":true, 453 "description":"Unique identifier for the SCIM 454 resource as defined within a target. 455 defined by the Service Provider. Each 456 representation of the resource MUST 457 include a non-empty id value. This 458 identifier MUST be unique across the 459 Target's entire set of resources. It 460 MUST be a stable, non-reassignable 461 identifier that does not change when 462 the same resource is returned in 463 subsequent requests. The value of the id 464 attribute is always issued by the Target 465 Provider and MUST never be specified by 466 the Target Service Consumer. REQUIRED.", 467 "schema":"urn:scim:schemas:core:1.0", 468 "readOnly":true, 469 "required":true, 470 "caseExact":false 471 }, 472 { 473 "name":"primary", 474 "type":"boolean", 475 "multiValued:false, 476 "description":"A Boolean value indicating the 477 'primary' or default targeted object 478 for the parent object", 479 "readOnly":false, 480 "required":false, 481 "caseExact":false 482 } 484 ] 485 } 486 [[TBD: what about flags such as isWriteable, etc]] 487 ] 489 } 490 ] 491 } 493 6 XML Schema Representation [[ TO BE DETERMINED]] 494 7 Security Considerations 496 [[TBD]] 498 No additional security considerations other than those listed in 499 [draft-scim-api-00]. 501 8 IANA Considerations 503 505 9 References 507 9.1 Normative References 509 [KEYWORDS] Bradner, S., "Key words for use in RFCs to Indicate 510 Requirement Levels", BCP 14, RFC 2119, March 1997. 512 [draft-scim-api-00] Drake, T., "Simple Cloud Identity Management: 513 Protocol 1.0", March 15 2012 515 [draft-scim-core-schema-00] Mortimore, C., "Simple Cloud Identity 516 Management: Core Schema 1.0", March 15 2012 518 9.2 Informative References 520 Appendix A - Editors Notes 521 The editor would like to thank Gary Cole for his extensive advice and 522 wisdom in advising on how to add Target functions to the SCIM 1.0. 523 The SCIM Target proposal builds in large part on his proposal work in 524 the OASIS RESTpml work, and is shared with his agreement. 526 Change History 528 Draft 01 is an administrative update to refresh expiry dates. 530 Authors' Addresses 532 Phil Hunt 533 Oracle Corporation 535 EMail: phil.hunt@yahoo.com