--- 1/draft-ietf-scim-api-05.txt 2014-06-23 15:14:26.724880553 -0700 +++ 2/draft-ietf-scim-api-06.txt 2014-06-23 15:14:26.832883224 -0700 @@ -1,25 +1,25 @@ Network Working Group P. Hunt, Ed. Internet-Draft Oracle Intended status: Standards Track K. Grizzle -Expires: November 14, 2014 SailPoint +Expires: December 25, 2014 SailPoint M. Ansari Cisco E. Wahlstroem Technology Nexus C. Mortimore Salesforce - May 13, 2014 + June 23, 2014 System for Cross-Domain Identity Management:Protocol - draft-ietf-scim-api-05 + draft-ietf-scim-api-06 Abstract The System for Cross-Domain Identity Management (SCIM) specification is designed to make managing user identity in cloud based applications and services easier. The specification suite seeks to build upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. It's intent is to reduce the cost and complexity of user management @@ -36,21 +36,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 November 14, 2014. + This Internet-Draft will expire on December 25, 2014. 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 @@ -62,54 +62,56 @@ Table of Contents 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 2. Authentication and Authorization . . . . . . . . . . . . . . 4 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 7 - 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 - 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 - 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 + 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 9 + 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 9 + 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 10 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 22 - 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 23 + 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 23 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 25 - 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 34 + 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 35 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 50 3.7. Additional Operation Response Parameters . . . . . . . . 51 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 52 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 53 3.10. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 53 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 55 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 55 - 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 57 - 4.1. Associating Clients to Tenants . . . . . . . . . . . . . 58 - 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 58 - 5. Security Considerations . . . . . . . . . . . . . . . . . . . 59 - 5.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 59 - 5.2. Querying Using HTTP GET . . . . . . . . . . . . . . . . . 59 - 5.3. Universal Identifiers . . . . . . . . . . . . . . . . . . 60 - - 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 - 6.1. Media Type Registration . . . . . . . . . . . . . . . . . 60 - 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 61 - 7.1. Normative References . . . . . . . . . . . . . . . . . . 61 - 7.2. Informative References . . . . . . . . . . . . . . . . . 62 - Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 62 - Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 62 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 63 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64 + 4. Preparation and Comparison of Internationalized Strings . . . 57 + 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 57 + 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 58 + 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 59 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 59 + 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 59 + 6.2. Request URI Information Leakage . . . . . . . . . . . . . 59 + 6.3. Case Insensitive Comparision & International Languages . 60 + 6.4. Universal Identifiers . . . . . . . . . . . . . . . . . . 60 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 + 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 60 + 7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 61 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 + 8.1. Normative References . . . . . . . . . . . . . . . . . . 62 + 8.2. Informative References . . . . . . . . . . . . . . . . . 64 + Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 64 + Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 64 + Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 64 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 66 1. Introduction and Overview The SCIM Protocol is an application-level, HTTP protocol for provisioning and managing identity data on the web. The protocol supports creation, modification, retrieval, and discovery of core identity resources; i.e., Users and Groups, as well as custom resource extensions. 1.1. Intended Audience @@ -131,74 +133,74 @@ For purposes of readability examples are not URL encoded. Implementers MUST percent encode URLs as described in Section 2.1 [RFC3986]. 1.3. Definitions Base URL: The SCIM HTTP API is always relative to a Base URL. The Base URL MUST NOT contain a query string as clients may append additional path information and query parameters as part of forming the request. Example: "https://example.com/scim/" - For readability, all examples in this document are expressed assuming the SCIM service root and the server root are the same. It is expected that SCIM servers may be deployed using any URI prefix. For example, a SCIM server might be have a prefix of - "https://example.com/", or "https://example.com/scim/tenancypath/ - ". Additionally client may also apply a version number to the - server root prefix (see Section 3.11). + "https://example.com/", or "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 The SCIM protocol does not define a scheme for authentication and authorization therefore implementers are free to choose mechanisms appropriate to their use cases. The choice of authentication mechanism will impact interoperability. It is RECOMMENDED that clients be implemented in such a way that new authentication schemes - can be deployed. 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 10.4.2 of Section 10.4.2 [RFC2616]. + can be deployed. 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]. All examples assume OAuth2 bearer token [RFC6750]; e.g., GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 Host: example.com Authorization: Bearer h480djs93hd8 The context of the request (i.e. the user for whom data is being requested) MUST be inferred by service providers. 3. API The SCIM protocol specifies well known endpoints and HTTP methods for managing resources defined in the core schema; i.e., "User" and "Group" resources correspond to "/Users" and "/Groups" respectively. Service providers that support extended resources SHOULD define resource endpoints using the established convention; pluralize the resource name defined in the extended schema by appending an 's'. Given there are cases where resource pluralization is ambiguous; e.g., a resource named "Person" is legitimately "Persons" and - "People" clients SHOULD discover resource endpoints via the "/ - ResourceTypes" endpoint . + "People" clients SHOULD discover resource endpoints via the + "/ResourceTypes" endpoint. GET Retrieves a complete or partial resource. - POST Create new resource, perform an extended Search, or bulk modify + POST Create new resources, create a Search request, or bulk modify resources. - PUT Modifies a resource with a complete, client specified resource - (replace). + PUT Modifies a resource by replacing existing attributes with a + specified set of replacement attributes (replace). PUT SHOULD NOT + be used to create new resources. PATCH Modifies a resource with a set of client specified changes (partial update). DELETE Deletes a resource. +------------+--------------------+---------------+-----------------+ | Resource | Endpoint | Operations | Description | +------------+--------------------+---------------+-----------------+ | User | /Users | GET (Section | Retrieve/Add/Mo | @@ -239,31 +241,44 @@ | | | | within a | | | | | resource | | | | | endpoint for | | | | | one or more | | | | | resource types | | | | | using POST. | +------------+--------------------+---------------+-----------------+ Table 1: Defined endpoints - All requests to the service provider are made via Section 9 [RFC2616] - on a URL derived from the Base URL. Responses are returned in the - body of the HTTP response, formatted as JSON. Response and error - 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. + All requests to the service provider are made via HTTP Methods as per + Section 4.3 [RFC7231] on a URL derived from the Base URL. Responses + are returned in the body of the HTTP response, formatted as JSON. + Response and error 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. 3.1. Creating Resources To create new resources, clients send POST requests to the resource - endpoint; i.e., "/Users" or "/Groups". + container endpoint such as: "/Users" or "/Groups". + + Attributes whose mutability is "readOnly", that are included in the + request body SHALL be ignored. + + 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 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. Successful resource creation is indicated with a 201 ("Created") response code. Upon successful creation, the response body MUST contain the newly created resource. 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. When a resource is created, its URI must be returned in the response Location header. If the service provider determines creation of the requested resource @@ -266,25 +281,24 @@ server views of the new resource. When a resource is created, its URI must be returned in the response Location header. If the service provider determines creation of the requested resource conflicts with existing resources; e.g., a "User" resource with a duplicate "userName", the service provider MUST return a 409 error and SHOULD indicate the conflicting attribute(s) in the body of the response. Below, the client sends a POST request containing a user - POST /Users HTTP/1.1 Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { "schemas":["urn:scim:schemas:core:2.0:User"], "userName":"bjensen", "externalId":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", @@ -284,26 +298,27 @@ { "schemas":["urn:scim:schemas:core:2.0:User"], "userName":"bjensen", "externalId":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" } } + The server signals a successful creation with a status code of 201. The response includes a Location header indicating the User URI, and a representation of that user in the body of the response. HTTP/1.1 201 Created -Content-Type: application/json +Content-Type: application/scim+json Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 ETag: W/"e180ee84f0671b1" { "schemas":["urn:scim:schemas:core:2.0:User"], "id":"2819c223-7f76-453a-919d-413861904646", "externalId":"bjensen", "meta":{ "resourceType":"User", "created":"2011-08-01T21:32:44.882Z", @@ -339,27 +353,27 @@ To retrieve a known resource, clients send GET requests to the resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}". If the resource exists the server responds with a status code of 200 and includes the result in the body of the response. The below example retrieves a single User via the "/Users" endpoint. GET /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com - Accept: application/json + Accept: application/scim+json Authorization: Bearer h480djs93hd8 The server responds with: HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json Location: https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646 ETag: W/"f250dd84f0671c3" { "schemas":["urn:scim:schemas:core:2.0:User"], "id":"2819c223-7f76-453a-919d-413861904646", "externalId":"bjensen", "meta":{ "resourceType":"User", "created":"2011-08-01T18:29:49.793Z", @@ -389,52 +404,57 @@ 3.2.2. List/Query Resources SCIM defines a standard set of operations that can be used to filter, sort, and paginate response results. The operations are specified by adding query parameters to the resource's endpoint. Service providers MAY support additional query parameters not specified here, and Providers SHOULD ignore any query parameters they don't recognize. List and query responses MUST be identified using the following URI: - "urn:scim:schemas:core:2.0:ListResponse". The following attributes + "urn:scim:api:messages:2.0:ListResponse". The following attributes are defined for list and query responses: totalResults The total number of results returned by the list or query operation. This may not be equal to the number of elements in the resources attribute of the list response if pagination (Section 3.2.2.4) is requested. REQUIRED. Resources A multi-valued list of complex objects containing the requested resources. This may be a subset of the full set of - resources if pagination (Section 3.2.2.4) is requested. REQUIRED. + resources if pagination (Section 3.2.2.4) is requested. REQUIRED + if "totalResults" is non-zero. startIndex The 1-based index of the first result in the current set of list results. REQUIRED if pagination (Section 3.2.2.4) is requested. itemsPerPage The number of resources returned in a list response page. REQUIRED if pagination (Section 3.2.2.4) is requested. + A query that does not return any matches SHALL return success with + "totalResults" set to a value of 0. + The query example below requests the userName for all Users: GET /Users?attributes=userName Host: example.com - Accept: application/json + Accept: application/scim+json Authorization: Bearer h480djs93hd8 + The following is an example response to the query above: HTTP/1.1 200 OK - Content-Type: application/json + Content-Type: application/scim+json { - "schemas":["urn:scim:schemas:core:2.0:ListResponse"], + "schemas":["urn:scim:api:messages:2.0:ListResponse"], "totalResults":2, "Resources":[ { "userName":"bjensen" }, { "userName":"jsmith" } ] } @@ -774,31 +794,31 @@ | | current set of search results; e.g., 1. | +--------------+----------------------------------------------------+ Table 6: Pagination Response Elements For example, to retrieve the first 10 Users set the startIndex to 1 and the count to 10: GET /Users?startIndex=1&count=10 Host: example.com - Accept: application/json + Accept: application/scim+json Authorization: Bearer h480djs93hd8 The response to the query above returns metadata regarding paging similar to the following example (actual resources removed for brevity): { "totalResults":100, "itemsPerPage":10, "startIndex":1, - "schemas":["urn:scim:schemas:core:2.0"], + "schemas":["urn:scim:api:messages:2.0"], "Resources":[{ ... }] } Given the example above, to continue paging set the startIndex to 11 and re-fetch; i.e., /Users?startIndex=11&count=10 3.2.3. Querying Resources Using HTTP POST @@ -807,21 +827,21 @@ The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL be used to indicate the HTTP POST verb is intended to be a query operation. To create a new search result set, a SCIM client sends an HTTP POST request to the desired SCIM resource endpoint (ending in '/.search'). The body of the POST request MAY include any of the parameters as defined in Section 3.2.2. Search requests MUST be identified using the following URI: - 'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes + 'urn:scim:api:messages:2.0:SearchRequest'. The following attributes are defined for search requests: attributes A multi-valued list of strings indicating the names of resource attributes to return in the response overriding the set of attributes that would be returned by default. Attribute names MUST be in standard attribute notation (Section 3.8) form. See additional retrieval query parameters (Section 3.7). OPTIONAL. excludedAttributes A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of @@ -851,43 +871,43 @@ results per page. See pagination (Section 3.2.2.4). OPTIONAL. After receiving a HTTP POST request, a response is returned as specified in Section 3.2.2. The following example shows an HTTP POST Search request with search parameters attributes, filter, and count included: POST /.search Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { - "schemas": ["urn:scim:schemas:core:2.0:SearchRequest"], + "schemas": ["urn:scim:api:messages:2.0:SearchRequest"], "attributes": ["displayName", "userName"], "filter": "displayName sw \"smith\"", "startIndex": 1, "count": 10 } Figure 2: Example POST Search Request A search response is shown with the first page of results. For brevity reasons, only two matches are shown: one User and one Group. HTTP/1.1 200 OK - Content-Type: application/json + Content-Type: application/scim+json Location: https://example.com/.search { - "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], + "schemas": ["urn:scim:api:messages:2.0:ListResponse"], "totalResults":100, "itemsPerPage":10, "startIndex":1, "Resources":[ { "meta":{ "location": "https://example.com/Users/2819c223-7f76-413861904646", "resourceType":"User", "lastModified": ... @@ -907,93 +927,104 @@ ... ] } Figure 3: Example POST Search Response 3.3. Modifying Resources Resources can be modified in whole or in part via PUT or PATCH, respectively. Implementers MUST support PUT as specified in - Section 9.6 [RFC2616] . Resources such as Groups may be very large + Section 4.3 [RFC7231]. Resources such as Groups may be very large hence implementers SHOULD support PATCH [RFC5789] to enable partial resource modifications. -3.3.1. Modifying with PUT +3.3.1. Replacing with PUT - PUT performs a full update. Clients MAY retrieve the entire resource - in advance, add the desired modifications and use HTTP PUT which will - overwrite all previously stored data. Since the PUT request performs - a full update, clients MAY send attributes of the retrieved resource - and the service provider MUST process according to attribute - mutability as follows: + HTTP PUT is used to perform a full update of a resource's attributes. + Clients that MAY have previously retrieved the entire resource in + advance and revised it, MAY replace the resource using an HTTP PUT. + Because SCIM resource identifiers are typically assigned by the + service provider, HTTP PUT SHOULD 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. Omitting the attribute or specific values means - the attribute or specific value SHALL be removed; + attribute values. - immutable If values are provided for elements already set in the - attribute they MUST match existing data or an error is returned. - If the service provider has no existing values, a new value(s) MAY - be specified; and, + 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", the client MUST specify the attribute - in the PUT request. + If an attribute is "required", clients MUST specify the attribute in + the PUT request. - If a value provided for an immutable attribute with an existing value - is NOT matched, the server SHALL respond with an HTTP response code - of 400 and an appropriate human readable message indicating an - attempt to change an immutable attribute. + 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 Provider's views of the updated resource. Example: PUT /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { - "schemas":["urn:scim:schemas:core:2.0:User"], + "schemas":["urn:scim:api:messages:2.0:User"], "id":"2819c223-7f76-453a-919d-413861904646", "userName":"bjensen", "externalId":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara", "middleName":"Jane" }, + "roles":[], "emails":[ { "value":"bjensen@example.com" }, { "value":"babs@jensen.org" } ] } The service responds with the entire, updated User: HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json ETag: W/"b431af54f0671a2" Location:"https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646" { - "schemas":["urn:scim:schemas:core:2.0:User"], + "schemas":["urn:scim:api:messages:2.0:User"], "id":"2819c223-7f76-453a-919d-413861904646", "userName":"bjensen", "externalId":"bjensen", "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara", "middleName":"Jane" }, "emails":[ @@ -1022,20 +1053,23 @@ (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. + Each operation object MUST contain the following "schemas" URI: + "urn:scim:api:messages:2.0:PatchOp" + Operation objects MUST have exactly one "path" member which is a "String" containing an attribute path as specified by the following ABNF syntax rule: PATH = attrPath / valuePath [subAttr] Figure 4: SCIM Patch PATH Rule The rules, "attrPath", "valuePath", and "subAttr" are defined in Section 3.2.2.2. The "valuePath" rule allows specific values of a @@ -1051,25 +1085,25 @@ "path":"members[value eq \"2819c223-7f76-453a-919d-413861904646\"]" "path":"members[value eq \"2819c223-7f76-453a-919d-413861904646\"].displayName" 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 an - error as indicated below. + 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 an error as indicated below. Each patch operation represents a single action to be applied to the same SCIM resource specified by the request URI. Operations are applied sequentially in the order they appear in the array. Each operation in the sequence is applied to the target resource; the resulting resource becomes the target of the next operation. Evaluation continues until all operations are successfully applied or until an error condition is encountered. A patch request, regardless of the number of operations, SHALL be @@ -1099,40 +1133,39 @@ operation could be performed. invalid_value The operation "value" was missing or was not compatable with the targeted attribute's type The following is a non-normative example of an error response to a patch request. HTTP/1.1 400 Bad Request - Content-Type: application/json;charset=UTF-8 + Content-Type: application/scim+json;charset=UTF-8 Cache-Control: no-store Pragma: no-cache { - "schemas": ["urn:scim:schemas:core:2.0:Error"], + "schemas": ["urn:scim:api:messages:2.0:Error"], "Errors":[ { "error":"mutability", "error_description":"Attribute 'id' is readOnly." } ] } - On successful completion, the server MUST return either a 200 OK response code and the entire resource (subject to the "attributes" query parameter - see Additional Retrieval Query Parameters - (Section 3.7)) within the response body, or a 204 No Content response - code and the appropriate response headers for a successful patch - request. The server MUST return a 200 OK if the "attributes" + (Section 3.7) ) within the response body, or a 204 No Content + response code and the appropriate response headers for a successful + patch request. The server MUST return a 200 OK if the "attributes" parameter is specified on the request. 3.3.2.1. Add Operation The "add" operation performs one of the following functions, depending upon what the target location indicated by "path" references: o If the target location does not exist, the attribute and value is added. @@ -1157,26 +1190,27 @@ The operation MUST contain a "value" member whose content specifies the value to be added. The value MAY be a quoted value OR it may be a JSON object containing the sub-attributes of the complex attribute specified in the operation's "path". 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/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"add", "path":"members", "value":[ { "display": "Babs Jensen", "$ref": "https://example.com/v2/Users/2819c223...413861904646", "value": "2819c223-7f76-453a-919d-413861904646" } ] } @@ -1218,89 +1252,97 @@ to the resource and a success response should be returned. Note that server responses have been omitted for the rest of the PATCH examples. Remove a single member from a group. Some text removed for readability ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "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/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" - { "op":"remove","path":"members"} + { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], + "op":"remove","path":"members"} Removal of a value from a complex-multi-valued attribute (request headers removed for brevity): { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "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/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" [ { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"remove", "path":"members[value eq\"2819c223...919d-413861904646\"]" }, { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"add", "path":"members", "value": [ { "display": "James Smith", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "value": "08e1d05d...473d93df9210" } ] } ] The following example shows how to replace all the members of a group with a different members list. Some text removed for readabilty ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" [ - { "op":"remove","path":"members"}, + { "schemas": ["urn:scim:api:messages:2.0:PatchOp"], + "op":"remove","path":"members"}, { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"add", "path":"members", "value":[ { "display": "Babs Jensen", "$ref": "https://example.com/v2/Users/2819c223...413861904646", "value": "2819c223-7f76-453a-919d-413861904646" }, { "display": "James Smith", @@ -1334,52 +1376,54 @@ complex filter and a specific sub-attribute (e.g. "addresses[type eq "work"].streetAddress"), the matching sub-attribute of the matching record is replaced. The following example shows how to replace all the members of a group with a different members list in a single replace operation. Some text removed for readability ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"replace", "path":"members", "value":[ { "display": "Babs Jensen", "$ref": "https://example.com/v2/Users/2819c223...413861904646", "value": "2819c223...413861904646" }, { "display": "James Smith", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "value": "08e1d05d...473d93df9210" } ] } The following example shows how to change a User's entire "work" address. PATCH /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"replace", "path":"addresses[type eq \"work\"]", "value": { "type": "work", "streetAddress": "911 Universal City Plaza", "locality": "Hollywood", "region": "CA", "postalCode": "91608", "country": "US", @@ -1387,26 +1431,27 @@ "primary": true } } The following example shows how to change a User's address. Since address does not have a value Sub-Attribute, the existing address must be removed and the modified address added. PATCH /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { + "schemas": ["urn:scim:api:messages:2.0:PatchOp"], "op":"replace", "path":"addresses[type eq \"work\"].streetAddress", "value":"911 Universal City Plaza" } 3.4. Deleting Resources Clients request resource removal via DELETE. Service providers MAY choose not to permanently delete the resource, but MUST return a 404 error code for all operations associated with the previously deleted @@ -1432,41 +1477,41 @@ GET /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Authorization: Bearer h480djs93hd8 Server Response: HTTP/1.1 404 NOT FOUND { - "schemas": ["urn:scim:schemas:core:2.0:Error"], + "schemas": ["urn:scim:api:messages:2.0:Error"], "Errors":[ { "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "code":"404" } ] } 3.5. Bulk 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:scim:schemas:core:2.0:BulkRequest'. Bulk responses are + 'urn:scim:api:messages:2.0:BulkRequest'. Bulk responses are identified using the following URI: - 'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk + 'urn:scim:api:messages:2.0:BulkResponse'. Bulk requests and bulk responses share many attributes. Unless otherwise specified, each attribute below is present in both bulk requests and bulk responses. The following Singular Attribute is defined in addition to the common attributes defined in SCIM core schema. failOnErrors An Integer specifying the number of errors that the service provider will accept before the operation is terminated and an error response is returned. OPTIONAL in a request. Not valid in a response. @@ -1486,24 +1531,24 @@ bulkId serves as a surrogate resource id enabling clients to uniquely identify newly created resources in the Response and cross reference new resources in and across operations within a bulk request. REQUIRED when method is POST. version The current resource version. Version is REQUIRED if the service provider supports ETags and the method is PUT, DELETE, or PATCH. path The resource's relative path. If the method is POST the - value must specify a resource type endpoint; e.g., /Users or / - Groups whereas all other method values must specify the path to - a specific resource; e.g., /Users/2819c223-7f76-453a- - 919d-413861904646. REQUIRED in a request. + value must specify a resource type endpoint; e.g., /Users or + /Groups whereas all other method values must specify the path + to a specific resource; e.g., /Users/2819c223-7f76-453a-919d- + 413861904646. REQUIRED in a request. data The resource data as it would appear for a single POST, PUT or PATCH resource operation. REQUIRED in a request when method is POST, PUT and PATCH. location The resource endpoint URL. REQUIRED in a response, except in the event of a POST failure. status A complex type that contains information about the success or failure of one operation within the bulk job. REQUIRED in a @@ -1563,44 +1608,44 @@ The following example shows how to add, update, and remove a user. The failOnErrors attribute is set to '1' indicating the service provider should return on the first error. The POST operation's bulkId value is set to 'qwerty' enabling the client to match the new User with the returned resource id '92b725cd-9465-4e7d- 8c16-01f8e146b87a'. POST /v2/Bulk Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { - "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], + "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], "failOnErrors":1, "Operations":[ { "method":"POST", "path":"/Users", "bulkId":"qwerty", "data":{ - "schemas": ["urn:scim:schemas:core:2.0:User"], + "schemas": ["urn:scim:api:messages:2.0:User"], "userName":"Alice" } }, { "method":"PUT", "path":"/Users/b7c14771-226c-4d05-8860-134711653041", "version":"W\/\"3694e05e9dff591\"", "data":{ - "schemas": ["urn:scim:schemas:core:2.0:User"], + "schemas": ["urn:scim:api:messages:2.0:User"], "id":"b7c14771-226c-4d05-8860-134711653041", "userName":"Bob" } }, { "method": "PATCH", "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "version": "W/\"edac3253e2c0ef2\"", "data": {[ @@ -1619,24 +1664,24 @@ "method":"DELETE", "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b", "version":"W\/\"0ee8add0a938e1a\"" } ] } The service provider returns the following response. HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json { - "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], + "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], "Operations": [ { "location": "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a", "method": "POST", "bulkId": "qwerty", "version": "W\/\"oY4m4wn58tkVjJxK\"", "status": { "code": "201" } }, @@ -1666,46 +1711,46 @@ ] } The following response is returned if an error occurred when attempting to create the User 'Alice'. The service provider stops processing the bulk operation and immediately returns a response to the client. The response contains the error and any successful results prior to the error. HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json { - "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], + "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], "Operations": [ { "method": "POST", "bulkId": "qwerty", "status": { "code": "400", "description": "Request is unparseable, syntactically incorrect, or violates schema." } } ] } If the failOnErrors attribute is not specified or the service provider has not reached the error limit defined by the client the service provider will continue to process all operations. The following is an example in which all operations failed. HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json { - "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], + "schemas": ["urn:scim:api:messages:2.0:BulkResponse"], "Operations": [ { "method": "POST", "bulkId": "qwerty", "status": { "code": "400", "description": "Request is unparseable, syntactically incorrect, or violates schema." } }, { @@ -1742,27 +1787,27 @@ 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. The following example creates a User with the userName 'Alice' and a Group with the displayName 'Tour Guides' with Alice as a member. POST /v2/Bulk Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { - "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], + "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], "Operations": [ { "method": "POST", "path": "/Users", "bulkId": "qwerty", "data": { "schemas": ["urn:scim:schemas:core:2.0:User"], "userName": "Alice" } }, @@ -1780,24 +1825,24 @@ } ] } } ] } The service provider returns the following response. HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json { - "schemas": ["urn:scim:schemas:core:2.0:BulkResponse"], + "schemas": ["urn: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" } }, @@ -1806,30 +1851,30 @@ "method": "POST", "bulkId": "ytrewq", "version": "W\/\"lha5bbazU3fNvfe5\"", "status": { "code": "201" } } ] } - A subsequent request for the 'Tour Guides' Group ('e9e30dba- - f08f-4109-8486-d5c6a331660a') returns the following: + A subsequent request for the 'Tour Guides' Group ('e9e30dba-f08f- + 4109-8486-d5c6a331660a') returns the following: GET /v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a Host: example.com - Accept: application/json + Accept: application/scim+json Authorization: Bearer h480djs93hd8 HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json Location: https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a ETag: W/"lha5bbazU3fNvfe5" { "schemas": ["urn:scim:schemas:core:2.0:Group"], "id": "e9e30dba-f08f-4109-8486-d5c6a331660a", "displayName": "Tour Guides", "meta": { "resourceType": "Group", "created": "2011-08-01T18:29:49.793Z", @@ -1846,27 +1891,27 @@ ] } Extensions that include references to other resources MUST be handled in the same way by the service provider. The following example uses the bulkId attribute within the enterprise extension managerId attribute. POST /v2/Bulk Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { - "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], + "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], "Operations": [ { "method": "POST", "path": "/Users", "bulkId": "qwerty", "data": { "schemas": ["urn:scim:schemas:core:2.0:User"], "userName": "Alice" } }, @@ -1892,27 +1937,27 @@ ] } The service provider MUST try to resolve circular cross references between resources in a single bulk job but MAY stop after a failed attempt and instead return the status code 409 Conflict. The following example exhibits the potential conflict. POST /v2/Bulk Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... { - "schemas": ["urn:scim:schemas:core:2.0:BulkRequest"], + "schemas": ["urn:scim:api:messages:2.0:BulkRequest"], "Operations": [ { "method": "POST", "path": "/Groups", "bulkId": "qwerty", "data": { "schemas": ["urn:scim:schemas:core:2.0:Group"], "displayName": "Group A", "members": [ { @@ -1938,28 +1983,28 @@ } } ] } If the service provider resolved the above circular references the following is returned from a subsequent GET request. GET /v2/Groups?filter=displayName sw 'Group' Host: example.com - Accept: application/json + Accept: application/scim+json Authorization: Bearer h480djs93hd8 HTTP/1.1 200 OK -Content-Type: application/json +Content-Type: application/scim+json { - "schemas": ["urn:scim:schemas:core:2.0:ListResponse"], + "schemas": ["urn:scim:api:messages:2.0:ListResponse"], "totalResults": 2, "Resources": [ { "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97", "schemas": ["urn:scim:schemas:core:2.0:Group"], "displayName": "Group A", "meta": { "resourceType": "Group", "created": "2011-08-01T18:29:49.793Z", "lastModified": "2011-08-01T18:29:51.135Z", @@ -1999,56 +2044,59 @@ maximum payload size a client may send in a single request. 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. POST /v2/Bulk Host: example.com - Accept: application/json - Content-Type: application/json + Accept: application/scim+json + Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: 4294967296 ... HTTP/1.1 413 Request Entity Too Large -Content-Type: application/json +Content-Type: application/scim+json Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8 { - "schemas":["urn:scim:schemas:core:2.0:Error"], + "schemas":["urn:scim:api:messages:2.0:Error"], "Errors":[ { "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", "code":"413" } ] } 3.6. Data Input/Output Formats Servers MUST accept requests and respond with JSON structured responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default encoding format. Clients using other encodings MUST specify the format in which the - data is submitted via Section 14.17 HTTP header content-type[RFC2616] - and MAY specify the desired response data format via an HTTP Accept - Header; e.g.,"Accept: application/json" or via URI suffix; e.g., - - GET /Users/2819c223-7f76-453a-919d-413861904646.json + data is submitted via HTTP header "Content-Type" as specified in + Section 3.1.1.5 [RFC7231] and MAY specify the desired response data + format via an HTTP "Accept" header ( Section 5.3.2 [RFC7231] ); e.g., + "Accept: application/scim+json" or via URI suffix; e.g., + GET /Users/2819c223-7f76-453a-919d-413861904646.scim Host: example.com - Service providers MUST support the Accept Headers "Accept: - application/json" for [RFC7159]. The format defaults to JSON if no + + Service providers MUST support the accept header "Accept: + application/scim+json" and SHOULD support header "Accept: + application/json" both of which specify JSON documents conforming to + [RFC7159]. The format defaults to "application/scim+json" if no format is specified. Singular attributes are encoded as string name-value-pairs in JSON; e.g., "attribute": "value" Multi-valued attributes in JSON are encoded as arrays; e.g., "attributes": [ "value1", "value2" ] @@ -2148,26 +2196,26 @@ 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. 3.10. HTTP Response Codes The SCIM Protocol uses the response status codes defined in HTTP - Section 10 [RFC2616] to indicate operation success or failure. 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 URI: 'urn:scim:schemas:core:2.0:Error'. The following + following URI: 'urn:scim:api:messages:2.0:Error'. The following multi-valued attribute is defined in addition to those attributes defined in SCIM Core Schema: Errors The list of errors encountered by the service provider. The value attribute is a complex type with the following sub- attributes. description A human-readable explanation of the error. REQUIRED. code A string indicating the HTTP response code. REQUIRED. @@ -2178,21 +2226,21 @@ | Code | Applicability | Suggested Explanation | +--------------+---------------+------------------------------------+ | 307 | GET, POST, | The client is directed to repeat | | TEMPORARY | PUT, PATCH, | the same HTTP request at the | | REDIRECT | DELETE | location identified. The client | | | | SHOULD NOT use the location | | | | provided in the response as a | | | | permanent reference to the | | | | resource and SHOULD continue to | | | | use the original request URI | - | | | [I-D.ietf-httpbis-p2-semantics]. | + | | | [RFC7231]. | | 308 | GET, POST, | The client is directed to repeat | | PERMANENT | PUT, PATCH, | the same HTTP request at the | | REDIRECT | DELETE | location identified. The client | | | | SHOULD use the location provided | | | | in the response as the permanent | | | | reference to the resource | | | | [I-D.reschke-http-status-308]. | | 400 BAD | GET, POST, | Request is unparseable, | | REQUEST | PUT, PATCH, | syntactically incorrect, or | | | DELETE | violates schema | @@ -2223,51 +2271,51 @@ | | DELETE | | +--------------+---------------+------------------------------------+ Table 7: Defined error cases Error example in response to a non-existent GET request. HTTP/1.1 404 NOT FOUND { - "schemas": ["urn:scim:schemas:core:2.0:Error"], + "schemas": ["urn:scim:api:messages:2.0:Error"], "Errors":[ { "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "code":"404" } ] } 3.11. API Versioning The Base URL MAY be appended with a version identifier as a separate - segment in the URL path. At this time the only valid identifier is - 'v1'. If specified, the version identifier MUST appear in the URL - path immediately preceding the resource endpoint and conform to the - following scheme: the character 'v' followed by the desired SCIM - version number; e.g., a version 'v1' User request is specified as /v2 - /Users. When specified service providers MUST perform the operation - using the desired version or reject the request. When omitted - service providers SHOULD perform the operation using the most recent - API supported by the service provider. + segment in the URL path. At this time of this specification, the + identifier is 'v2'. If specified, the version identifier MUST appear + in the URL path immediately preceding the resource endpoint and + conform to the following scheme: the character 'v' followed by the + desired SCIM version number; e.g., a version 'v2' User request is + specified as /v2/Users. When specified service providers MUST + perform the operation using the desired version or reject the + request. When omitted service providers SHOULD perform the operation + using the most recent API supported by the service provider. 3.12. Versioning Resources - The API supports resource versioning via standard HTTP - ETagsSection 14.19 [RFC2616]. Service providers MAY support weak - ETags as the preferred mechanism for performing conditional - retrievals and ensuring clients do not inadvertently overwrite each - others changes, respectively. When supported SCIM ETags MUST be - specified as an HTTP header and SHOULD be specified within the - 'version' attribute contained in the resource's 'meta' attribute. + The API supports resource versioning via standard HTTP ETags + Section 2.3 [RFC7233]. Service providers MAY support weak ETags as + the preferred mechanism for performing conditional retrievals and + ensuring clients do not inadvertently overwrite each others changes, + respectively. When supported SCIM ETags MUST be specified as an HTTP + header and SHOULD be specified within the 'version' attribute + contained in the resource's 'meta' attribute. Example: POST /Users HTTP/1.1 Host: example.com Content-Type: application/json Authorization: Bearer h480djs93hd8 Content-Length: ... { @@ -2303,39 +2351,51 @@ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" }, "userName":"bjensen" } With the returned ETag, clients MAY choose to retrieve the resource only if the resource has been modified. - Conditional retrieval example using If-None-Match Section 14.26 - [RFC2616] header: + Conditional retrieval example using If-None-Match Section 3.2 + [RFC7233] header: GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName Host: example.com Accept: application/json Authorization: Bearer h480djs93hd8 If-None-Match: W/"e180ee84f0671b1" If the resource has not changed the service provider simply returns an empty body with a 304 "Not Modified" response code. If the service providers supports versioning of resources the client - MAY supply an If-Match Section 14.24 [RFC2616] header for PUT and - PATCH operations to ensure that the requested operation succeeds only - if the supplied ETag matches the latest service provider resource; - e.g., If-Match: W/"e180ee84f0671b1" + MAY supply an If-Match Section 3.1 [RFC7233] header for PUT and PATCH + operations to ensure that the requested operation succeeds only if + the supplied ETag matches the latest service provider resource; e.g., + If-Match: W/"e180ee84f0671b1" -4. Multi-Tenancy +4. Preparation and Comparison of Internationalized Strings + + To increase the likelihood that the input and comparison of unicode + usernames and passwords will work in ways that make sense for typical + users throughout the world there are special string preparation and + comparison methods (PRECIS) that MUST be followed for usernames and + passwords. Before comparing or evaluating uniqueness of a "userName" + or "password" attribute, service providers MUST use the "PRECIS" + profile described in Sections 4 and 5 respectively of + [I-D.ietf-precis-saslprepbis] and is based on the "PRECIS" framework + specification [I-D.ietf-precis-framework]. + +5. Multi-Tenancy A single service provider may expose the SCIM protocol to multiple clients. Depending on the nature of the service, the clients may have authority to access and alter resources initially created by other clients. Alternatively, clients may expect to access disjoint sets of resources, and may expect that their resources are inaccessible by other clients. These scenarios are called "multi- tenancy", where each client is understood to be or represent a "tenant" of the service provider. Clients may also be multi- tenanted. @@ -2353,26 +2412,27 @@ Service providers may implement any subset of the above cases. Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a scheme for multi-tenancy. The SCIM protocol does not prescribe the mechanisms whereby clients and service providers interact for: o Registering or provisioning Tenants + o Associating a subset of clients with a subset of the Tenants o Indicating which tenant is associated with the data in a request or response, or indicating which Tenant is the subject of a query -4.1. Associating Clients to Tenants +5.1. Associating Clients to Tenants The service provider MAY use the authentication mechanism (Section 2) to determine the identity of the client, and thus infer the associated Tenant. For implementations where a client is associated with more than one Tenant, the service provider MAY use one of the following methods for explicit specification of the Tenant. If any of these methods of allowing the client to explicitly specify @@ -2389,105 +2449,114 @@ o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/ Users" o A sub-domain: "https://{tenant_id}.example.com/v2/Groups" o The service provider may recognize a {tenant_id} provided by the client in an HTTP Header as the indicator of the desired target Tenant. -4.2. SCIM Identifiers with Multiple Tenants +5.2. SCIM Identifiers with Multiple Tenants Considerations for a Multi-Tenant Implementation: The service provider may choose to implement SCIM ids which are unique across all resources for all Tenants, but this is not required. The externalId, defined by the client, is required to be unique ONLY within the resources associated with the associated Tenant. -5. Security Considerations +6. Security Considerations -5.1. TLS Support +6.1. TLS Support - The SCIM Protocol is based on HTTP and thus subject to the security - considerations found in Section 15 of [RFC2616]. SCIM resources - (e.g., Users and Groups) can contain sensitive information. - Therefore, SCIM clients and service providers MUST implement TLS. - Which version(s) ought to be implemented will vary over time, and - depend on the widespread deployment and known security + The SCIM Protocol layers on top of Hypertext Transfer Protocol and + thus subject to the security considerations of HTTP Section 9 + [RFC7230] and its related specifications. + + SCIM resources (e.g., Users and Groups) can contain sensitive + information. Therefore, SCIM clients and service providers MUST + implement TLS. Which version(s) ought to be implemented will vary + over time, and depend on the widespread deployment and known security vulnerabilities at the time of implementation. At the time of this writing, TLS version 1.2 [RFC5246] is the most recent version, but has very limited actual deployment, and might not be readily available in implementation toolkits. TLS version 1.0 [RFC2246] is the most widely deployed version, and will give the broadest interoperability. -5.2. Querying Using HTTP GET +6.2. Request URI Information Leakage - Clients requesting information using query filters SHOULD give - consideration to the information content of the filters and whether - their exposure in a URL would represent a breach of security or - confidentiality through leakage in a web browser or logs. This is - particularly true for information that is legally considered - "personally identifiable information" or is otherwise restricted by - privacy laws. To ensure maximum security and confidentiality, - clients SHOULD query using HTTP POST (see Section 3.2.3). + Clients requesting information using query filters using HTTP GET + SHOULD give consideration to the information content of the filters + and whether their exposure in a URI would represent a breach of + security or confidentiality through leakage in a web browsers or + server logs. This is particularly true for information that is + legally considered "personally identifiable information" or is + otherwise restricted by privacy laws. In these situations to ensure + maximum security and confidentiality, clients SHOULD query using HTTP + POST (see Section 3.2.3 ). Servers that receive HTTP GET requests using filters that contain restricted or confidential information SHOULD respond with HTTP status 403 indicating the operation is FORBIDDEN. A detialed error, "confidential_restricted" may be returned indicating the request must be submitted using POST. A non-normative example: HTTP/1.1 403 FORBIDDEN { - "schemas": ["urn:scim:schemas:core:2.0:Error"], + "schemas": ["urn:scim:api:messages:2.0:Error"], "Errors":[ { "description":"Query filter involving 'name' is restricted or confidential", "error":"confidential_restricted" } ] } -5.3. Universal Identifiers -6. IANA Considerations +6.3. Case Insensitive Comparision & International Languages -6.1. Media Type Registration + 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. + +6.4. Universal Identifiers + +7. IANA Considerations + +7.1. Media Type Registration To: ietf-types@iana.org Subject: Registration of media type application/scim+json Type name: application Subtype name: scim+json Required parameters: none Optional parameters: none Encoding considerations: 8bit - Security considerations: See Section 5 + Security considerations: See Section 6 Interoperability considerations: The "application/scim+json" media type is intended to identify JSON structure data that conforms to the SCIM 2 api and schema specifications. Older versions of SCIM are known to informally use "application/json". Published specification: [[this document]] - Applications that use this media type: It is expected that applications that use this type may be special purpose applications intended for inter-domain provisioning. Clients may also be applications (e.g. mobile applications) that need to use SCIM for self-registration of user accounts. SCIM services may be offered by web applications wishin to offer support for standards based provisioning or may be a dedicated SCIM service provider such as a "cloud directory". Content may be treated as equivalent to "application/json" type for the purpose of displaying in web browsers. @@ -2507,54 +2576,85 @@ Restrictions on usage: For most client types, it is sufficient to recognize the content as equivalent to "application/json". Applications intending to use the SCIM API SHOULD use the application/scim+json media type. Author: Phil Hunt Change controller: IETF -7. References +7.2. SCIM API Message Schema Registry -7.1. Normative References + As per the IANA SCIM Schema Registry in [I-D.ietf-scim-core-schema], + the following registers and extends the SCIM Schema Registry to + define API request/response JSON schema URN identifier prefix of + "urn:scim:api:messages:2.0" which is part of the URN sub-Namespace + for SCIM. There is no specific associated resource type. - [I-D.ietf-httpbis-p2-semantics] - Fielding, R. and J. Reschke, "Hypertext Transfer Protocol - (HTTP/1.1): Semantics and Content", draft-ietf- - httpbis-p2-semantics-25 (work in progress), November 2013. + +---------------------------------------+-----------+---------------+ + | Schema URI | Name | Reference | + +---------------------------------------+-----------+---------------+ + | urn:scim:api:messages:2.0:ListRespons | List/Quer | See Section | + | e | y | 3.2.2 | + | | Response | | + | urn:scim:api:messages:2.0:SearchReque | POST | See Section | + | st | Query | 3.2.3 | + | | Request | | + | urn:scim:api:messages:2.0:PatchOp | Patch | See Section | + | | Operation | 3.3.2 | + | urn:scim:api:messages:2.0:BulkRequest | Bulk Oper | See Section | + | | ations | 3.5 | + | | Request | | + | urn:scim:api:messages:2.0:BulkRespons | Bulk Oper | See Section | + | e | ations | 3.5 | + | | Response | | + | urn:scim:api:messages:2.0:Error | Error | See Section | + | | Response | 3.10 | + +---------------------------------------+-----------+---------------+ + + SCIM Schema URIs for Data Resources + +8. References + +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, "System for Cross-Domain Identity Management: Core - Schema", draft-ietf-scim-core-schema-03 (work in - progress), February 2014. - - [I-D.reschke-http-status-308] - Reschke, J., "The Hypertext Transfer Protocol (HTTP) - Status Code 308 (Permanent Redirect)", draft-reschke-http- - status-308-07 (work in progress), March 2012. + Schema", draft-ietf-scim-core-schema-05 (work in + progress), May 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. [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. + [RFC3454] Hoffman, P. and M. Blanchet, "Preparation of + Internationalized Strings ("stringprep")", RFC 3454, + December 2002. + [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. @@ -2563,21 +2663,46 @@ [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC 5789, March 2010. [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization Framework: Bearer Token Usage", RFC 6750, October 2012. [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data Interchange Format", RFC 7159, March 2014. -7.2. Informative References + [RFC7230] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol + (HTTP/1.1): Message Syntax and Routing", RFC 7230, June + 2014. + + [RFC7231] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol + (HTTP/1.1): Semantics and Content", RFC 7231, June 2014. + + [RFC7233] Fielding, R., Lafon, Y., and J. Reschke, "Hypertext + Transfer Protocol (HTTP/1.1): Range Requests", RFC 7233, + June 2014. + + [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol + (HTTP/1.1): Authentication", RFC 7235, June 2014. + +8.2. Informative References + + [I-D.ietf-precis-framework] + Saint-Andre, P. and M. Blanchet, "PRECIS Framework: + Preparation and Comparison of Internationalized Strings in + Application Protocols", draft-ietf-precis-framework-17 + (work in progress), May 2014. + + [I-D.reschke-http-status-308] + Reschke, J., "The Hypertext Transfer Protocol (HTTP) + Status Code 308 (Permanent Redirect)", draft-reschke-http- + status-308-07 (work in progress), March 2012. [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. @@ -2658,20 +2783,42 @@ 70 - Remove SCIM_TENANT_ID header 72 - Added text to indicate UTF-8 is default and mandatory encoding format per BCP18 74 - Added security considerations for using GET with confidential attribute filters - corrected error response in JSON PATCH operation + Draft 06 - PH - Revisions based on the following tickets and + editorial changes + + 41 - Revised content types from application/json to application/ + scim+json, registered API schemas + + 63 - Revised uri schema prefixes for API json message schemas + + 66 - Updated references for RFC2616 to HTTPbis + + 75 - Added security considerations for International Strings and + "PRECIS" support + + 76 - Clarified handling of PUT (& POST) with regards to mutability + and default values + + - Corrected version numbers in sec 3.11 API Versioning to v2 (from + v1) + + - Clarified that no filter matches should return success + totalResults=0 + Authors' Addresses Phil Hunt (editor) Oracle Corporation Email: phil.hunt@yahoo.com Kelly Grizzle SailPoint