--- 1/draft-ietf-scim-api-10.txt 2014-09-17 11:14:37.150115942 -0700 +++ 2/draft-ietf-scim-api-11.txt 2014-09-17 11:14:37.278119064 -0700 @@ -1,25 +1,25 @@ Network Working Group P. Hunt, Ed. Internet-Draft Oracle Intended status: Standards Track K. Grizzle -Expires: March 5, 2015 SailPoint +Expires: March 21, 2015 SailPoint M. Ansari Cisco E. Wahlstroem Nexus Technology C. Mortimore Salesforce - September 1, 2014 + September 17, 2014 - System for Cross-Domain Identity Management 0;,Protocol - draft-ietf-scim-api-10 + System for Cross-Domain Identity Management: Protocol + draft-ietf-scim-api-11 Abstract The System for Cross-Domain Identity Management (SCIM) specification is an HTTP based protocol that makes managing identities in multi- domain scenarios easier to support through a standardized services. Examples include but are not limited to enterprise to cloud service providers, and inter-cloud based scenarios. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and @@ -37,21 +37,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." - This Internet-Draft will expire on March 5, 2015. + This Internet-Draft will expire on March 21, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -65,59 +65,60 @@ 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 2. Authentication and Authorization . . . . . . . . . . . . . . 4 3. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 - 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 + 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 - 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 - 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 23 - 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24 - 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26 - 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 39 - 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 40 - 3.5.1. Circular Reference Processing . . . . . . . . . . . . 42 - 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 46 - 3.5.3. Response and Error Handling . . . . . . . . . . . . . 49 - 3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 55 - 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 56 - 3.7. Additional Operation Response Parameters . . . . . . . . 57 - 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 58 - 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 58 - 3.10. HTTP Status and Error Response Handling . . . . . . . . . 59 - 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 63 - 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 63 - 4. Preparation and Comparison of Internationalized Strings . . . 65 - 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 65 - 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 66 - 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 66 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 67 - 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 67 - 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 67 - 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 68 - 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 68 - 6.5. Case Insensitive Comparision & International Languages . 69 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 69 - 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 69 - 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 70 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 71 - 8.1. Normative References . . . . . . . . . . . . . . . . . . 71 - 8.2. Informative References . . . . . . . . . . . . . . . . . 72 - Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 73 - Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 73 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 73 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 76 + 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 21 + 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 24 + 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 25 + 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 27 + 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 40 + 3.5. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 41 + 3.5.1. Circular Reference Processing . . . . . . . . . . . . 43 + 3.5.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 47 + 3.5.3. Response and Error Handling . . . . . . . . . . . . . 51 + 3.5.4. Maximum Operations . . . . . . . . . . . . . . . . . 57 + 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 58 + 3.7. Additional Operation Response Parameters . . . . . . . . 59 + 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 60 + 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 60 + 3.10. HTTP Status and Error Response Handling . . . . . . . . . 61 + 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 65 + 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 65 + 4. Preparation and Comparison of Internationalized Strings . . . 67 + 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 67 + 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 68 + 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 68 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 69 + 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 69 + 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 69 + 6.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 70 + 6.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 70 + 6.5. Secure Storage and Handling of Sensitive Data . . . . . . 71 + 6.6. Case Insensitive Comparision & International Languages . 71 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 72 + 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 72 + 7.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 73 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 73 + 8.1. Normative References . . . . . . . . . . . . . . . . . . 73 + 8.2. Informative References . . . . . . . . . . . . . . . . . 75 + Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 76 + Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 76 + Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 76 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 79 1. Introduction and Overview The SCIM Protocol is an application-level, HTTP protocol for provisioning and managing identity data on the web and in cross- domain environments such as enterprise to cloud, or inter-cloud scenarios. The protocol supports creation, modification, retrieval, and discovery of core identity resources such as Users and Groups, as well as custom resources and resource extensions. @@ -161,26 +162,27 @@ "https://example.com/scim/tenancypath/". Additionally client may also apply a version number to the server root prefix (see Section 3.11 ). 2. Authentication and Authorization Because SCIM builds on the HTTP protocol, it does not itself define a scheme for authentication and authorization. SCIM depends on standard HTTP authentication schemes. Implementers SHOULD support existing authentication/authorization schemes. In particular, OAuth2 - [RFC6750] is RECOMMENDED. Appropriate security considerations of the - selected authentication and authorization schemes SHOULD be taken. - Because this protocol uses HTTP response status codes as the primary - means of reporting the result of a request, servers are advised to - respond to unauthorized or unauthenticated requests using the 401 - response code in accordance with Section 3.1 of [RFC7235]. + (see [RFC6749], [RFC6750]) is RECOMMENDED. Appropriate security + considerations of the selected authentication and authorization + schemes SHOULD be taken. Because this protocol uses HTTP response + status codes as the primary means of reporting the result of a + request, servers are advised to respond to unauthorized or + unauthenticated requests using the 401 response code in accordance + with Section 3.1 of [RFC7235]. All examples show an OAuth2 bearer token [RFC6750] (though it is not required); e.g., GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 Host: example.com Authorization: Bearer h480djs93hd8 When processing requests, the service provider SHOULD consider the subject performing the request and whether the action is appropriate @@ -254,33 +256,37 @@ are returned in the body of the HTTP response, formatted as JSON. Error status codes SHOULD be transmitted via the HTTP status code of the response (if possible), and SHOULD also be specified in the body of the response (see Section 3.10). 3.1. Creating Resources To create new resources, clients send HTTP POST requests to the resource endpoint such as: "/Users" or "/Groups". - Attributes in the request body, whose mutability is "readOnly", SHALL - be ignored. + The server SHALL process attributes according to the following + mutability rules: - Attributes whose mutability is "readWrite", that are omitted from the - request body, MAY be assumed to be not asserted by the client. The - service provider MAY assign a default value to non-asserted - attributes in the final resource representation. Service providers - MAY take into account whether a client has access to, or understands, - all of the resource's attributes when deciding whether non-asserted - attributes SHALL be defaulted. Clients that intend to override - server defaulted attributes, MAY specify "null" for a single-valued - attribute or an empty array "[]" for a multi-valued attribute to - clear all values. + o For attributes in the request body, whose mutability is + "readOnly", SHALL be ignored. + + o For attributes whose mutability is "readWrite", that are omitted + from the request body, MAY be assumed to be not asserted by the + client. The service provider MAY assign a default value to non- + asserted attributes in the final resource representation. + + o Service providers MAY take into account whether a client has + access to, or understands, all of the resource's attributes when + deciding whether non-asserted attributes should be defaulted. + Clients that intend to override server defaulted values for + attributes MAY specify "null" for a single-valued attribute or an + empty array "[]" for a multi-valued attribute to clear all values. When the service provider successfully creates the new resource, an HTTP response SHALL be returned with HTTP status "201" ("Created"). The response body SHOULD contain the service provider's representation of the newly created resource. The URI of the created resource SHALL included in the HTTP "Location" header and in JSON resource representation under the attribute "meta.location". Since the server is free to alter and/or ignore POSTed content, returning the full representation can be useful to the client, enabling it to correlate the client and server views of the new resource. @@ -1009,42 +1016,43 @@ service provider, HTTP PUT MUST NOT be used to create new resources. As the operation intent is to replace all attributes, SCIM clients MAY send all attributes regardless of each attribute's mutability. The server will apply attribute by attribute replace according to the following attribute mutability rules: readWrite, writeOnly Any values provided SHALL replace the existing attribute values. + Attributes whose mutability is "readWrite", that are omitted from + the request body, MAY be assumed to be not asserted by the client. + The service provider MAY assume any existing values are to be + cleared or the service provider MAY assign a default value to the + final resource representation. Service providers MAY take into + account whether a client has access to, or understands, all of the + resource's attributes when deciding whether non-asserted + attributes SHALL be removed or defaulted. Clients that would like + to override a server defaults, MAY specify "null" for a single- + valued attribute or an empty array "[]" for a multi-valued + attribute to clear all values. + immutable If value(s) are already set for the attribute, the input value(s) MUST match or HTTP status 400 SHOULD be returned with error code "mutability". If the service provider has no existing values, the new value(s) SHALL be applied. readOnly Any values provided (e.g. meta.resourceType) SHALL be ignored. If an attribute is "required", clients MUST specify the attribute in the PUT request. - Attributes whose mutability is "readWrite", that are omitted from the - request body, MAY be assumed to be not asserted by the client. The - service provider MAY assume any existing values are to be cleared or - the service provider MAY assign a default value to the final resource - representation. Service providers MAY take into account whether a - client has access to, or understands, all of the resource's - attributes when deciding whether non-asserted attributes SHALL be - removed or defaulted. Clients that would like to override a server - defaults, MAY specify "null" for a single-valued attribute or an - empty array "[]" for a multi-valued attribute to clear all values. - Unless otherwise specified a successful PUT operation returns a 200 OK response code and the entire resource within the response body, enabling the client to correlate the client's and the service provider's views of the updated resource. Example: PUT /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 @@ -1108,79 +1116,83 @@ 3.3.2. Modifying with PATCH HTTP PATCH is an OPTIONAL server function that enables clients to update one or more attributes of a SCIM resource using a sequence of operations to "add", "remove", or "replace" values. The general form of the SCIM patch request is based on JavaScript Object Notation (JSON) Patch [RFC6902]. One difference between SCIM patch and JSON patch is that SCIM servers do not support array indexing and may not support all [RFC6902] operation types. - The body of an HTTP PATCH request MUST contain one or more patch - operation objects. A patch operation object MUST have exactly one - "op" member, whose value indicates the operation to perform and MAY - be one of "add", "remove", or "replace". The semantics of each - operation are defined below. + The body of each request MUST contain the following "schemas" + attribute with the URI value of: + "urn:ietf:params:scim:api:messages:2.0:PatchOp". - The body of each request MUST contain the following "schemas" URI: - "urn:ietf:params:scim:api:messages:2.0:PatchOp", followed by an array - of one or more operations. For example: + The body of an HTTP PATCH request MUST contain the attribute + "Operations", whose value is an array of one or more patch + operations. Each patch operation object MUST have exactly one "op" + member, whose value indicates the operation to perform and MAY be one + of "add", "remove", or "replace". The semantics of each operation + are defined in the following sub-sections. + + The following is an example representation of a PATCH request showing + the basic JSON structure (non-normative): { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [ + "Operations":[ { "op":"add", "path":"members", "value":[ { "display": "Babs Jensen", "$ref": "https://example.com/v2/Users/2819c223...413861904646", "value": "2819c223-7f76-453a-919d-413861904646" } ] }, ... + additional operations if needed ... ] } - Example JSON body for SCIM PATCH Request + Figure 5: Example JSON body for SCIM PATCH Request A "path" attribute value is a String containing an attribute path describing the target of the operation. The "path" attribute is OPTIONAL for "add" and "replace" and is REQUIRED for "remove" operations. See relevant operation sections below for details. The "path" attribute is described by the following ABNF syntax rule: PATH = attrPath / valuePath [subAttr] - Figure 5: SCIM Patch PATH Rule + Figure 6: SCIM Patch PATH Rule The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in Section 3.2.2.2. The "valuePath" rule allows specific values of a complex, multi-valued attribute to be selected. Valid examples of "path" values are as follows: "path":"members" "path":"name.familyName" "path":"addresses[type eq \"work\"]" "path":"members[value eq \"2819c223-7f76-453a-919d-413861904646\"]" "path":"members[value eq \"2819c223-7f76-453a-919d-413861904646\"].displayName" - Figure 6: Example Path Values + Figure 7: Example Path Values Each operation against an attribute MUST be compatible with the attribute's mutability and schema as defined in the Attribute Types Section of [I-D.ietf-scim-core-schema]. For example, a client MAY NOT modify an attribute that has mutability "readOnly" or "immutable". However, a client MAY "add" a value to an "immutable" attribute if the attribute had no previous value. An operation that is not compatibile with an attribute's mutability or schema SHALL return the appropriate HTTP response status code and a JSON detail error response as defined in Section 3.10. @@ -1271,21 +1283,21 @@ The following example shows how to add a member to a group. Some text removed for readability ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [ + "Operations":[ { "op":"add", "path":"members", "value":[ { "display": "Babs Jensen", "$ref": "https://example.com/v2/Users/2819c223...413861904646", "value": "2819c223-7f76-453a-919d-413861904646" } ] @@ -1307,21 +1319,21 @@ PATCH /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations":[{ "op":"add", "value":"{ "emails":[ { "value":"babs@jensen.org", "type":"home" } ], "nickname":"Babs" }] @@ -1382,61 +1394,61 @@ PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations":[{ "op":"remove", "path":"members[value eq \"2819c223-7f76-...413861904646\"]" }] } Remove all members of a group: PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations":[{ "op":"remove","path":"members" }] } Removal of a value from a complex-multi-valued attribute (request headers removed for brevity): { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations": [{ "op":"remove", "path":"emails[type eq \"work\" and value ew \"example.com\"]" }] } Example request to remove and add a member. Some text removed for readability ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [ + "Operations": [ { "op":"remove", "path":"members[value eq\"2819c223...919d-413861904646\"]" }, { "op":"add", "path":"members", "value": [ { "display": "James Smith", @@ -1452,21 +1464,21 @@ ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [ + "Operations": [ { "op":"remove","path":"members" }, { "op":"add", "path":"members", "value":[ { "display": "Babs Jensen", "$ref": "https://example.com/v2/Users/2819c223...413861904646", @@ -1522,21 +1534,21 @@ PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations": [{ "op":"replace", "path":"members", "value":[ { "display": "Babs Jensen", "$ref": "https://example.com/v2/Users/2819c223...413861904646", "value": "2819c223...413861904646" }, { "display": "James Smith", @@ -1551,21 +1563,21 @@ PATCH /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations": [{ "op":"replace", "path":"addresses[type eq \"work\"]", "value": { "type": "work", "streetAddress": "911 Universal City Plaza", "locality": "Hollywood", "region": "CA", "postalCode": "91608", "country": "US", @@ -1580,39 +1592,39 @@ PATCH /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations": [{ "op":"replace", "path":"emails[type eq \"work\"].value", "value":"bjenson@example.com" }] } The following example shows how to replace one or more attributes of a User resource. PATCH /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas": ["urn:ietf:params:scim:api:messages:2.0:PatchOp"], - [{ + "Operations": [{ "op":"replace", "value":"{ "emails":[ { "value":"bjensen@example.com", "type":"work", "primary":true }, { "value":"babs@jensen.org", @@ -1659,21 +1671,21 @@ { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "Errors":[ { "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "code":"404" } ] } -3.5. Bulk +3.5. Bulk Operations The SCIM bulk operation is an optional server feature that enables clients to send a potentially large collection of resource operations in a single request. The body of a a bulk operation contains a set of HTTP resource operations using one of the API supported HTTP methods; i.e., POST, PUT, PATCH or DELETE. Bulk requests are identified using the following URI: "urn:ietf:params:scim:api:messages:2.0:BulkRequest". Bulk responses are identified using the following URI: @@ -1863,32 +1875,39 @@ "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "$ref": "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "type": "Group" } ] } ] } 3.5.2. BulkdId Temporary Identifiers - The client can, within one bulk operation, create a new "User", a new - "Group" and add the newly created "User" to the newly created + A SCIM client can, within one bulk operation, create a new "User", a + new "Group" and add the newly created "User" to the newly created "Group". In order to add the new "User" to the "Group" the client must use the surrogate id attribute, "bulkId", to reference the User. The "bulkId" attribute value must be pre-pended with the literal "bulkId:"; e.g., if the bulkId is 'qwerty', the value is "bulkId:qwerty". The service provider MUST replace the string "bulkId:qwerty" with the permanent resource id once created. + To create multiple distinct requests, each with their own "bulkId", + the SCIM client specifies different "bulkId" values for each separate + request. + The following example creates a User with the "userName" 'Alice' and a "Group" with the "displayName" 'Tour Guides' with Alice as a - member. + member. Notice that each operation has its own "bulkId" value. + However, the second operation (whose "bulkId" is "ytrewq") refers to + the "bulkId" of "qwerty" in order to add Alice to new 'Tour Guides' + group. POST /v2/Bulk Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"], @@ -1912,25 +1931,56 @@ "members": [ { "type": "User", "value": "bulkId:qwerty" } ] } } ] } - The service provider returns the following response: - A subsequent GET request for the 'Tour Guides' Group ('e9e30dba-f08f- - 4109-8486-d5c6a331660a') returns the following: +HTTP/1.1 200 OK +Content-Type: application/json + +{ + "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"], + "Operations": [ + { + "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", + "method": "POST", + "bulkId": "qwerty", + "version": "W\/\"4weymrEsh5O6cAEK\"", + "status": { + "code": "201" + } + }, + { + "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", + "method": "POST", + "bulkId": "ytrewq", + "version": "W\/\"lha5bbazU3fNvfe5\"", + "status": { + "code": "201" + } + } + ] +} + + In the above example, the Alice User resource has an "id" of + "92b725cd-9465-4e7d-8c16-01f8e146b87a" and the Tour Guides Group has + an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a". + + A subsequent GET request for the 'Tour Guides' Group (with an "id" + of"e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following with + Alice's "id" as the value for the member in the Group 'Tour Guides': HTTP/1.1 200 OK Content-Type: application/scim+json Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a ETag: W/"lha5bbazU3fNvfe5" { "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"], "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", "displayName": "Tour Guides", @@ -2216,37 +2266,42 @@ "bulkId": "ytrewq", "version": "W\/\"lha5bbazU3fNvfe5\"", "status": "201" } ] } 3.5.4. Maximum Operations The service provider MUST define the maximum number of operations and - maximum payload size a client may send in a single request. If - either limits are exceeded the service provider MUST return the HTTP + maximum payload size a client may send in a single request. These + limits MAY be retrieved from the Service Provider Configuration (see + 'bulk' in Section 8 of [I-D.ietf-scim-core-schema]). If either + limits are exceeded the service provider MUST return the HTTP response code 413 Request Entity Too Large. The returned response MUST specify the limit exceeded in the body of the error response. The following example the client sent a request exceeding the service - provider's max payload size of 1 megabyte. + provider's max payload size of 1 megabyte: POST /v2/Bulk Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: 4294967296 ... + In response to the over-sized request, the server responds with the + following error: + HTTP/1.1 413 Request Entity Too Large Content-Type: application/scim+json { "schemas":["urn:ietf:params:scim:api:messages:2.0:Error"], "status": "413", "detail":"The size of the bulk operation exceeds the maxPayloadSize (1048576)." } 3.6. Data Input/Output Formats @@ -2374,20 +2429,27 @@ o A service provider MAY choose to redirect the client using HTTP status 308 to the resource associated with the authenticated subject. The client MAY then repeat the request at the indicated location. o A service provider MAY process the SCIM request directly. In any response, the HTTP "Location" header MUST be the permanent location of the aliased resource associated with the authenticated subject. + When using the SCIM Create Resource command (HTTP POST) with the + "/Me" alias, the desired resourceType being created is at the + discretion of the service provider based on the authenticated subject + (if not anonymous) making the request and any request body attributes + (e.g. "schemas"). See Section 6.3 for information on security + considerations related to this operation. + 3.10. HTTP Status and Error Response Handling The SCIM Protocol uses the HTTP status response status codes defined in Section 6 [RFC7231] to indicate operation success or failure. In addition to returning a HTTP response code implementers MUST return the errors in the body of the response in the client requested format containing the error response and, per the HTTP specification, human- readable explanations. Error responses are identified using the following "schema" URI: "urn:ietf:params:scim:api:messages:2.0:Error". The following @@ -2492,21 +2554,21 @@ | | attribute with an existing | | | | value). | | | invalidSynta | The request body message | POST (Search - | | x | structure was invalid or did | Section 3.2.2, | | | not conform to the request | Create - Section | | | schema. | 3.1, Bulk - Section | | | | 3.5), PUT (Section | | | | 3.3.1) | | invalidPath | The path attribute was | PATCH (Section | | | invalid or malformed (see | 3.3.2) | - | | Figure 5). | | + | | Figure 6). | | | noTarget | The specified "path" did not | PATCH (Section | | | yield an attribute or | 3.3.2) | | | attribute value that could | | | | be operated on. This occurs | | | | when the specified "path" | | | | value contains a filter that | | | | yields no match. | | | invalidValue | A required value was | GET (Section | | | missing, or the value | 3.2.2), POST | | | specified was not compatible | (Create - Section | @@ -2783,32 +2845,55 @@ { "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"], "Errors":[ { "description":"Query filter involving 'name' is restricted or confidential", "error":"confidential_restricted" } ] } -6.3. HTTP Considerations +6.3. Anonymous Requests + + If a SCIM service provider accepts anonymous requests such as SCIM + resource creation requests (via HTTP POST), appropriate security + measures should be put in place to prevent or limit exposure to + attacks. The following counter-measures MAY be used: + + o Try to authenticate web UI components that forumulate the SCIM + creation request. While the end-user MAY be anonymous, the web + user interface component often has its own way to authenticate to + the SCIM service provider (e.g. has an OAuth Client Credential + [RFC6749]) and the web user interface component may implement its + own measures (e.g. such as CAPTCHA) to ensure a ligitimate request + is being made. + + o Limit the number of requests any particular client MAY make in a + period of time. + + o For User resources, default newly created resource with an + "active" setting of "false" and use a secondary confirmation + process (e.g. email confirmation) to ensure the resource created + is real. + +6.4. HTTP Considerations As an HTTP based protocol, implementers of SCIM SHOULD consider all security considerations of the HTTP/1.1 as enumerated in Section 1 [RFC7230] As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate the userinfo (i.e. username and password) component (and its "@" delimiter) when an "http" URI reference is generated with a message as they are now disallowed in HTTP. -6.4. Secure Storage and Handling of Sensitive Data +6.5. Secure Storage and Handling of Sensitive Data An attacker may obtain valid username/password combinations from the SCIM service provider's underlying database by gaining access to the database and/or launching injection attacks. This could lead to unintended disclosure of username/password combinations. The impact may extend beyond the domain of the SCIM service provider if the data was provisioned from other domains. Administrators should undertake industry best practices to protect the storage of credentials and in particular SHOULD follow @@ -2835,21 +2920,21 @@ a number of failed attempts, o Use "tar pit" techniques by temporarily locking a respective account and delaying responses for a certain duration. The duration may increase with the number of failed attempts, and o Use authentication system that use CAPTCHA's and other factors for authenticating users further reducing the possibility of automated attacks. -6.5. Case Insensitive Comparision & International Languages +6.6. Case Insensitive Comparision & International Languages When comparing unicode strings such as in query filters or testing for uniqueness of usernames and passwords, strings MUST be appopriately prepared before comparison. See Section 4. 7. IANA Considerations 7.1. Media Type Registration To: ietf-types@iana.org @@ -2940,24 +3025,24 @@ 8.1. Normative References [I-D.ietf-precis-saslprepbis] Saint-Andre, P. and A. Melnikov, "Preparation and Comparison of Internationalized Strings Representing Usernames and Passwords", draft-ietf-precis-saslprepbis-07 (work in progress), March 2014. [I-D.ietf-scim-core-schema] - Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, + Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, "System for Cross-Domain Identity Management: Core - Schema", draft-ietf-scim-core-schema-09 (work in - progress), August 2014. + Schema", draft-ietf-scim-core-schema-10 (work in + progress), September 2014. [IANA.Language] Internet Assigned Numbers Authority (IANA), "Language Subtag Registry", 2005. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", RFC 2246, January 1999. @@ -3018,20 +3103,23 @@ [OpenSearch] Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . [Order-Operations] Wikipedia, "Order of Operations: Programming Languages", . [RFC2277] Alvestrand, H., "IETF Policy on Character Sets and Languages", BCP 18, RFC 2277, January 1998. + [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC + 6749, October 2012. + [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012. [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 Threat Model and Security Considerations", RFC 6819, January 2013. [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation (JSON) Patch", RFC 6902, April 2013. @@ -3170,27 +3258,41 @@ - Aligned API with new URN namespace per RFC3553 and IETF90 meeting - Clarified URN usage within patch (what schema urn applies) - Made 'path' optional in PATCH for Add and Replace Draft 10 - PH - Revisions as follows Restructuring of Bulk into sub-sections - General clarifications Improved Base URI section Authorization section clarifications + Draft 11 - PH - Revisions as follows + + Made mutability processing rules for CREATE more editorially + obvious + + Added clarfications and security considerations for Anonymous + operations + + Added clarifications to "/Me" for POST requests + + Clarified use of bulkids with multiple requests + + Corrected JSON parsing issue by adding "Operations" attribute to + PATCH operation + Authors' Addresses Phil Hunt (editor) Oracle Corporation Email: phil.hunt@yahoo.com Kelly Grizzle SailPoint