--- 1/draft-ietf-scim-api-15.txt 2015-03-08 13:14:33.242718256 -0700 +++ 2/draft-ietf-scim-api-16.txt 2015-03-08 13:14:33.378721549 -0700 @@ -1,25 +1,25 @@ Network Working Group P. Hunt, Ed. Internet-Draft Oracle Intended status: Standards Track K. Grizzle -Expires: August 14, 2015 SailPoint +Expires: September 9, 2015 SailPoint M. Ansari Cisco E. Wahlstroem Nexus Technology C. Mortimore Salesforce - February 10, 2015 + March 8, 2015 System for Cross-Domain Identity Management: Protocol - draft-ietf-scim-api-15 + draft-ietf-scim-api-16 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 August 14, 2015. + This Internet-Draft will expire on September 9, 2015. Copyright Notice Copyright (c) 2015 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,64 +62,66 @@ described in the Simplified BSD License. Table of Contents 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 . . . . . . . . . . . . . . . . . . . 9 - 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 9 - 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 - 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 10 - 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 . . . . . . . . . . . . . . . . . . . 41 - 3.5. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 42 - 3.5.1. Circular Reference Processing . . . . . . . . . . . . 44 - 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. Service Provider Configuration Endpoints . . . . . . . . . . 67 - 5. Preparation and Comparison of Internationalized Strings . . . 69 - 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 70 - 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 70 - 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 71 - 7. Security Considerations . . . . . . . . . . . . . . . . . . . 71 - 7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 71 - 7.2. Disclosure of Sensitive Information in URIs . . . . . . . 72 - 7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 72 - 7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 73 - 7.5. Secure Storage and Handling of Sensitive Data . . . . . . 73 - 7.6. Case Insensitive Comparision & International Languages . 74 - 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 74 - 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 74 - 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 75 - 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 76 - 9.1. Normative References . . . . . . . . . . . . . . . . . . 76 - 9.2. Informative References . . . . . . . . . . . . . . . . . 77 - Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 78 - Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 78 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 78 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 82 + 3.1. Introduction . . . . . . . . . . . . . . . . . . . . . . 5 + 3.2. SCIM Endpoints . . . . . . . . . . . . . . . . . . . . . 6 + 3.3. Creating Resources . . . . . . . . . . . . . . . . . . . 8 + 3.3.1. Resource Types . . . . . . . . . . . . . . . . . . . 10 + 3.4. Retrieving Resources . . . . . . . . . . . . . . . . . . 10 + 3.4.1. Retrieving a known Resource . . . . . . . . . . . . . 10 + 3.4.2. Query Resources . . . . . . . . . . . . . . . . . . . 11 + 3.4.3. Querying Resources Using HTTP POST . . . . . . . . . 22 + 3.5. Modifying Resources . . . . . . . . . . . . . . . . . . . 25 + 3.5.1. Replacing with PUT . . . . . . . . . . . . . . . . . 26 + 3.5.2. Modifying with PATCH . . . . . . . . . . . . . . . . 28 + 3.6. Deleting Resources . . . . . . . . . . . . . . . . . . . 42 + 3.7. Bulk Operations . . . . . . . . . . . . . . . . . . . . . 43 + 3.7.1. Circular Reference Processing . . . . . . . . . . . . 45 + 3.7.2. BulkdId Temporary Identifiers . . . . . . . . . . . . 48 + 3.7.3. Response and Error Handling . . . . . . . . . . . . . 52 + 3.7.4. Maximum Operations . . . . . . . . . . . . . . . . . 58 + 3.8. Data Input/Output Formats . . . . . . . . . . . . . . . . 59 + 3.9. Additional Operation Response Parameters . . . . . . . . 60 + 3.10. Attribute Notation . . . . . . . . . . . . . . . . . . . 61 + 3.11. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 61 + 3.12. HTTP Status and Error Response Handling . . . . . . . . . 62 + 3.13. API Versioning . . . . . . . . . . . . . . . . . . . . . 66 + 3.14. Versioning Resources . . . . . . . . . . . . . . . . . . 66 + 4. Service Provider Configuration Endpoints . . . . . . . . . . 68 + 5. Preparation and Comparison of Internationalized Strings . . . 70 + 6. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 71 + 6.1. Associating Clients to Tenants . . . . . . . . . . . . . 71 + 6.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 72 + 7. Security Considerations . . . . . . . . . . . . . . . . . . . 72 + 7.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 72 + 7.2. Disclosure of Sensitive Information in URIs . . . . . . . 73 + 7.3. Anonymous Requests . . . . . . . . . . . . . . . . . . . 73 + 7.4. HTTP Considerations . . . . . . . . . . . . . . . . . . . 74 + 7.5. Secure Storage and Handling of Sensitive Data . . . . . . 74 + 7.6. Case Insensitive Comparision & International Languages . 75 + 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 75 + 8.1. Media Type Registration . . . . . . . . . . . . . . . . . 75 + 8.2. SCIM Message URI Registry . . . . . . . . . . . . . . . . 76 + 9. References . . . . . . . . . . . . . . . . . . . . . . . . . 77 + 9.1. Normative References . . . . . . . . . . . . . . . . . . 77 + 9.2. Informative References . . . . . . . . . . . . . . . . . 78 + Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 79 + Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 79 + Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 79 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 83 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. @@ -160,21 +162,21 @@ scheme, a domain name and some initial path [RFC3986]. 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 (no path pre-fix). It is expected that SCIM servers may be deployed using any URI path 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 ). + Section 3.13 ). 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 (see [RFC6749], [RFC6750]) is RECOMMENDED. Appropriate security considerations of the selected authentication and authorization schemes SHOULD be taken. Because this protocol uses HTTP response @@ -190,20 +192,80 @@ Authorization: Bearer h480djs93hd8 When processing requests, the service provider SHOULD consider the subject performing the request and whether the action is appropriate given the subject and the resource affected by the request. The subject performing the request is usually determined from the "Authorization" header present in the request. 3. SCIM Protocol +3.1. Introduction + + SCIM is a protocol that is based on HTTP protocol [RFC7230]. Along + with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to + convey both SCIM resources, as well as protocol specific payload + messages that convey request parameters and response information such + as errors. Both resources and messages are passed in the form of + JSON based structures in the message body of an HTTP request or + response. To identify this content, SCIM uses a media type of + "application/scim+json" (see Section 8.1). + + A SCIM "resource" is a JSON object that may be created, maintained, + and retrieved through HTTP request methods as described in this + document. Each JSON resource representation contains a "schemas" + attribute that contains a list of one or more URIs that indicate + included SCIM schemas that are used to indicate the attributes + contained within a resource. Specific information about what + attributes are defined within a schema MAY be obtained by querying a + SCIM service provider's "/Schemas" endpoint for a schema definition + (see Section 8.7 [I-D.ietf-scim-core-schema]). Responses from this + endpoint describe how a service provider supports a schema and in + particular how attribute qualities such as cardinality, case- + exactness, mutability, uniqueness, returnability, and whether an + attribute is required. While SCIM schemas and associated extension + model are defined in [I-D.ietf-scim-core-schema], SCIM clients should + expect that some attribute schema MAY change from service provider to + service provider, particularly across administrative domains. In + cases where SCIM may be used as an open protocol in front of an + application service, it is quite reasonable to expect that some + service providers MAY only support a sub-set of the schema defined in + [I-D.ietf-scim-core-schema]. + + A SCIM message conveys protocol parameters about a SCIM request or + response that are defined by this specification. As with a SCIM + resource, a SCIM message is a JSON object that contains a "schemas" + attribute with a URI whose namespace prefix that MUST begin with + "urn:ietf:params:scim:api:". As SCIM protocol messages are fixed and + defined by SCIM specifications and registered extensions, SCIM + message schemas using the above prefix URN SHALL NOT be discoverable + using the "/Schemas" endpoint. + + As SCIM is intended for use within cross-domain environments where + schema and implementations MAY vary, techniques such as document + validation, such as in [XML-Schema], are not recommended. A SCIM + service provider interprets a request in the context of its own + schema (which may be different from the client's schema) and + following the defined processing rules for each request. The + following sections in this document define the processing rules for + SCIM and provide allowances for schema differences where appropriate. + For example, in a SCIM PUT request, "readOnly" attributes are + ignored, while "readWrite" attributes are updated. There is no need + for a SCIM client to discover which attributes are "readOnly" and + does not need to remove them from a PUT request in advance in order + to be accepted. Similarly a SCIM client SHOULD NOT expect a service + provider to return SCIM resources with exactly the same schema and + values as submitted. SCIM responses SHALL reflect resource state as + interpreted by the SCIM service provider. + +3.2. SCIM Endpoints + 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 convention of pluralizing 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. @@ -221,61 +283,61 @@ 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 3.2.1), Retrieve, Add, - POST (Section 3.1), Modify Users - PUT (Section 3.3.1), - PATCH (Section 3.3.2), - DELETE (Section 3.4) - Group /Groups GET (Section 3.2.1), Retrieve, Add, - POST (Section 3.1), Modify Groups - PUT (Section 3.3.1), - PATCH (Section 3.3.2), - DELETE (Section 3.4) + User /Users GET (Section 3.4.1), Retrieve, Add, + POST (Section 3.3), Modify Users + PUT (Section 3.5.1), + PATCH (Section 3.5.2), + DELETE (Section 3.6) + Group /Groups GET (Section 3.4.1), Retrieve, Add, + POST (Section 3.3), Modify Groups + PUT (Section 3.5.1), + PATCH (Section 3.5.2), + DELETE (Section 3.6) Self /Me GET, POST, PUT, PATCH, Alias for operations - DELETE (Section 3.9) against a resource + DELETE (Section 3.11) against a resource mapped to an authenticated Subject (e.g. User). Service /ServiceProvider GET (Section 4) Retrieve service Provider Config provider's Config configuration Resource /ResourceTypes GET (Section 4) Retrieve supported Type resource types Schema /Schemas GET (Section 4) Retrieve one or more supported schemas. - Bulk /Bulk POST (Section 3.5) Bulk updates to one + Bulk /Bulk POST (Section 3.7) Bulk updates to one or more resources - Search [prefix]/.search POST (Section 3.2.3) Search from system + Search [prefix]/.search POST (Section 3.4.3) Search from system root or 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 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. 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). + of the response (see Section 3.12). -3.1. Creating Resources +3.3. Creating Resources To create new resources, clients send HTTP POST requests to the resource endpoint such as: "/Users" or "/Groups". The server SHALL process attributes according to the following mutability rules: o For attributes in the request body, whose mutability is "readOnly", SHALL be ignored. @@ -297,21 +359,21 @@ 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. 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 an HTTP Status - 409, with "scimType" error code of "uniqueness" as per Section 3.10. + 409, with "scimType" error code of "uniqueness" as per Section 3.12. Below, in the following example, a client sends a POST request containing a "User" to the "/Users" endpoint. POST /Users HTTP/1.1 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... @@ -350,37 +412,38 @@ "version":"W\/\"e180ee84f0671b1\"" }, "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" }, "userName":"bjensen" } -3.1.1. Resource Types +3.3.1. Resource Types When adding a resource to a specific endpoint, the meta attribute "resourceType" SHALL be set by the HTTP service provider to the corresponding resource type for the endpoint. For example, "/Users" will set "resourceType" to "User", and "/Groups" will set "resourceType" to "Group". -3.2. Retrieving Resources +3.4. Retrieving Resources - Resources are retrieved via opaque, unique URLs or via Query. The - attributes returned are defined in the server's attribute schema (see - Section 10 [I-D.ietf-scim-core-schema]) and request parameters (see - Section 3.7). By default, resource attributes returned in a response - are those whose schema "returned" setting is "always" or "default". + Resources are retrieved via opaque, unique URLs or via Query (see + Section 3.4.2). The attributes returned are defined in the server's + attribute schema (see Section 10 [I-D.ietf-scim-core-schema]) and + request parameters (see Section 3.9). By default, resource + attributes returned in a response are those whose schema "returned" + setting is "always" or "default". -3.2.1. Retrieving a known Resource +3.4.1. Retrieving a known Resource To retrieve a known resource, clients send GET requests to the resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or "/Schemas/{id}". If the resource exists the server responds with HTTP Status code 200 (OK) and includes the result in the body of the response. The below example retrieves a single User via the "/Users" endpoint. @@ -422,41 +485,41 @@ } ], "emails":[ { "value":"bjensen@example.com", "type":"work" } ] } -3.2.2. Query Resources +3.4.2. Query Resources The SCIM protocol defines a standard set of query parameters that can be used to filter, sort, and paginate to return zero or more resources in a query response. Queries MAY be made against a single resource or a resource type endpoint (e.g. "/Users"). SCIM service providers MAY support additional query parameters not specified here and SHOULD ignore any query parameters they do not recognize. Responses MUST be identified using the following URI: "urn:ietf:params:scim:api:messages:2.0:ListResponse". The following attributes are defined for 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. + (Section 3.4.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.4.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 when partial results returned due to pagination. itemsPerPage The number of resources returned in a list response page. REQUIRED when partial results returned due to pagination. A query that does not return any matches SHALL return success (HTTP @@ -480,21 +543,21 @@ "Resources":[ { "userName":"bjensen" }, { "userName":"jsmith" } ] } -3.2.2.1. Query Endpoints +3.4.2.1. Query Endpoints Queries MAY be performed against a SCIM resource object, a resource type endpoint, or a SCIM server root. For example: "/Users/{id}" "/Users" "/Groups" @@ -506,27 +569,27 @@ filter=(meta.resourceType eq User) or (meta.resourceType eq Group) If a SCIM service provider determines that too many results would be returned (e.g. because a client queried a resource type endpoint or the server base URI), the server SHALL reject the request by returning an HTTP response with "status" 400 and json attribute "scimType" set to "tooMany" (see Table 8). When processing query operations across endpoints that include more than one SCIM resource type (e.g. a query from the server root - endpoint), filters MUST be processed as outlined in Section 3.2.2.2. + endpoint), filters MUST be processed as outlined in Section 3.4.2.2. For filtered attributes that are not part of a particular resource type, the service provider SHALL treat the attribute as if there is no attribute value. For example, a presence or equality filter for an undefined attribute evaluates as FALSE. -3.2.2.2. Filtering +3.4.2.2. Filtering Filtering is an OPTIONAL parameter for SCIM service providers. Clients MAY discover service provider filter capabilities by looking at the "filter" attribute of the "ServiceProviderConfig" (see Section 8 [I-D.ietf-scim-core-schema]). Clients MAY request a subset of resources by specifying the "filter" query parameter containing a filter expression. When specified only those resources matching the filter expression SHALL be returned. The expression language that is used in the filter parameter supports references to attributes and literals. @@ -703,21 +766,21 @@ Filters MUST be evaluated using standard order of operations [Order-Operations]. Attribute operators have the highest precedence, followed by the grouping operator (i.e, parentheses), followed by the logical AND operator, followed by the logical OR operator. If the specified attribute in a filter expression is a multi-valued attribute, the resource MUST match if any of the instances of the given attribute match the specified criterion; e.g. if a User has multiple emails values, only one has to match for the entire User to match. For complex attributes, a fully qualified Sub-Attribute MUST - be specified using standard attribute notation (Section 3.8). For + be specified using standard attribute notation (Section 3.10). For example, to filter by userName the parameter value is userName and to filter by first name, the parameter value is name.givenName. Providers MAY support additional filter operations if they choose. Providers MUST decline to filter results if the specified filter operation is not recognized and return a HTTP 400 error with an appropriate human readable response. For example, if a client specified an unsupported operator named 'regex' the service provider should specify an error response description identifying the client error; e.g., 'The operator 'regex' is not supported.' @@ -769,53 +832,53 @@ filter=userType eq "Employee" and (emails.type eq "work") filter=userType eq "Employee" and emails[type eq "work" and value co "@example.com"] filter=emails[type eq "work" and value co "@example.com"] or ims[type eq "xmpp" and value co "@foo.com"] Figure 2: Example Filters -3.2.2.3. Sorting +3.4.2.3. Sorting Sort is OPTIONAL. Sorting allows clients to specify the order in which resources are returned by specifying a combination of sortBy and sortOrder URL parameters. sortBy: The sortBy parameter specifies the attribute whose value SHALL be used to order the returned responses. If the sortBy attribute corresponds to a singular attribute, resources are sorted according to that attribute's value; if it's a multi-valued attribute, resources are sorted by the value of the primary attribute (see Section 2.2 [I-D.ietf-scim-core-schema]), if any, or else the first value in the list, if any. If the attribute is complex the attribute name must be a path to a sub-attribute in - standard attribute notation (Section 3.8) ; e.g., + standard attribute notation (Section 3.10) ; e.g., "sortBy=name.givenName". For all attribute types, if there is no data for the specified "sortBy" value they are sorted via the "sortOrder" parameter; i.e., they are ordered last if ascending and first if descending. sortOrder: The order in which the sortBy parameter is applied. Allowed values are "ascending" and "descending". If a value for sortBy is provided and no sortOrder is specified, the sortOrder SHALL default to ascending. String type attributes are case insensitive by default unless the attribute type is defined as a case exact string. "sortOrder" MUST sort according to the attribute type; i.e., for case insensitive attributes, sort the result using case insensitive, unicode alphabetic sort order, with no specific locale implied and for case exact attribute types, sort the result using case sensitive, Unicode alphabetic sort order. -3.2.2.4. Pagination +3.4.2.4. Pagination Pagination parameters can be used together to "page through" large numbers of resources so as not to overwhelm the client or service provider. Pagination is not session based hence clients SHOULD never assume repeatable results. For example, a request for a list of 10 resources beginning with a startIndex of 1 may return different results when repeated as a resource in the original result could be deleted or new ones could be added in-between requests. Pagination parameters and general behavior are derived from the OpenSearch Protocol [OpenSearch]. @@ -879,93 +942,93 @@ "Resources":[{ ... }] } Figure 3: ListResponse format for returning multiple 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.2.5. Attributes +3.4.2.5. Attributes The following attributes control which attributes SHALL be returned with a returned resource. SCIM clients MAY use up to one of these two OPTIONAL parameters which MUST be supported by SCIM service providers: 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). + MUST be in standard.attribute notation (Section 3.10) form. See + additional retrieval query parameters (Section 3.9). excludedAttributes A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return. This parameter SHALL have no effect on attributes whose schema "returned" setting is "always" see Server Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in - standard attribute notation (Section 3.8) form. See additional - retrieval query parameters (Section 3.7). + standard attribute notation (Section 3.10) form. See additional + retrieval query parameters (Section 3.9). -3.2.3. Querying Resources Using HTTP POST +3.4.3. Querying Resources Using HTTP POST Clients MAY execute queries without passing parameters on the URL by using the HTTP POST verb combined with the '/.search' path extension. 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 query 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. + defined in Section 3.4.2. Query requests MUST be identified using the following URI: 'urn:ietf:params:scim:api:messages:2.0:SearchRequest'. The following attributes are defined for query 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. + MUST be in standard attribute notation (Section 3.10) form. See + additional retrieval query parameters (Section 3.9). OPTIONAL. excludedAttributes A multi-valued list of strings indicating the names of resource attributes to be removed from the default set of attributes to return. This parameter SHALL have no effect on attributes whose schema "returned" setting is "always" see Server Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in - standard attribute notation (Section 3.8) form. See additional - retrieval query parameters (Section 3.7). OPTIONAL. + standard attribute notation (Section 3.10) form. See additional + retrieval query parameters (Section 3.9). OPTIONAL. filter The filter string used to request a subset of resources. The - filter string MUST be a valid filter (Section 3.2.2.2) expression. + filter string MUST be a valid filter (Section 3.4.2.2) expression. OPTIONAL. sortBy A string indicating the attribute whose value SHALL be used to order the returned responses. The sortBy attribute MUST be in - standard attribute notation (Section 3.8) form. See sorting - (Section 3.2.2.3). OPTIONAL. + standard attribute notation (Section 3.10) form. See sorting + (Section 3.4.2.3). OPTIONAL. sortOrder A string indicating the order in which the sortBy parameter is applied. Allowed values are "ascending" and - "descending". See sorting (Section 3.2.2.3). OPTIONAL. + "descending". See sorting (Section 3.4.2.3). OPTIONAL. startIndex An integer indicating the 1-based index of the first - query result. See pagination (Section 3.2.2.4). OPTIONAL. + query result. See pagination (Section 3.4.2.4). OPTIONAL. count An integer indicating the desired maximum number of query - results per page. See pagination (Section 3.2.2.4). OPTIONAL. + results per page. See pagination (Section 3.4.2.4). OPTIONAL. After receiving a HTTP POST request, a response is returned as - specified in Section 3.2.2. + specified in Section 3.4.2. The following example shows an HTTP POST Query request with search parameters attributes, filter, and count included: POST /.search Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 Content-Length: ... @@ -1011,29 +1074,29 @@ "lastModified": ... }, "displayName":"Smith Family" }, ... ] } Figure 5: Example POST Query Response -3.3. Modifying Resources +3.5. Modifying Resources Resources can be modified in whole or in part via PUT or PATCH, respectively. Implementers MUST support PUT as specified in Section 4.3 [RFC7231]. Resources such as Groups may be very large hence implementers SHOULD support HTTP PATCH [RFC5789] to enable partial resource modifications. -3.3.1. Replacing with PUT +3.5.1. Replacing with PUT 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 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 @@ -1127,21 +1190,21 @@ "meta": { "resourceType":"User", "created":"2011-08-08T04:56:22Z", "lastModified":"2011-08-08T08:00:12Z", "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "version":"W\/\"b431af54f0671a2\"" } } -3.3.2. Modifying with PATCH +3.5.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 each request MUST contain the following "schemas" @@ -1182,21 +1245,21 @@ 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 7: 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 + Section 3.4.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\"]" @@ -1209,23 +1272,23 @@ Figure 8: 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 MUST 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. + error response as defined in Section 3.12. - The attribute notation rules described in Section 3.8 apply for + The attribute notation rules described in Section 3.10 apply for describing attribute paths. For all operations, the value of the "schemas" attribute on the SCIM service provider's representation of the resource SHALL be assumed by default. If one of the PATCH operations modifies the "schemas" attribute, subsequent operations SHALL assume the modified state of the "schemas" attribute. Clients MAY implicitly modify the "schemas" attribute by adding (or replacing) an attribute with its fully qualified name including schema URN. For example, adding the attribute "urn:ietf:params:scim: schemas:extension:enterprise:2.0:User:employeeNumber", automatically adds the value @@ -1244,31 +1307,31 @@ "primary" attribute to "true", SHALL cause the server to automatically set "primary" to "false" for any other values in the array as only one value MAY be primary. A patch request, regardless of the number of operations, SHALL be treated as atomic. If a single operation encounters an error condition, the original SCIM resource MUST be restored, and a failure status SHALL be returned. If a request fails, the server SHALL return an HTTP response status - code and a JSON detail error response as defined in Section 3.10. + code and a JSON detail error response as defined in Section 3.12. 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 + (Section 3.9) ) 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 +3.5.2.1. Add Operation The "add" operation is used to add a new attribute value to an existing resource. 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 result of the add operation depends upon what the target location @@ -1361,21 +1424,21 @@ "nickname":"Babs" }] } In the above example, an additional value is added to the multi- valued attribute "emails". The second attribute, "nickname" is added to the User resource. If the resource already had an existing "nickname", the value is replaced per the processing rules above for single-valued attributes. -3.3.2.2. Remove Operation +3.5.2.2. Remove Operation The "remove" operation removes the value at the target location specified by the required attribute "path". The operation performs the following functions depending on the target location specified by "path" : o If "path" is unspecified, the operation fails with HTTP status "400" and "scimType" of "noTarget". o If the target location is a single-value attribute, the attribute @@ -1395,21 +1458,21 @@ o If the target location is a complex-multi-valued attribute and a complex filter is specified based on the attribute's sub- attributes, the matching records are removed. Sub-attributes whose values have been removed SHALL be considered unassigned. If the complex-multi-valued attribute has no remaining records, the attribute SHALL be considered unassigned. If an attribute is removed or becomes unassigned and is defined as a required attribute or a read-only attribute, the server SHALL return an HTTP response status code and a JSON detail error response as - defined in Section 3.10 with a "scimType" error of "mutability". + defined in Section 3.12 with a "scimType" error of "mutability". The following example shows how to remove a member from a group. As with the previous example, the "display" sub-attribute is optional. If the user was not a member of this group, no changes should be made 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 @@ -1510,21 +1573,21 @@ }, { "display": "James Smith", "$ref": "https://example.com/v2/Users/08e1d05d...473d93df9210", "value": "08e1d05d-121c-4561-8b96-473d93df9210" }] } ] } -3.3.2.3. Replace Operation +3.5.2.3. Replace Operation The "replace" operation replaces the value at the target location specified by the "path". The operation performs the following functions depending on the target location specified by "path" : o If the "path" parameter is omitted, the target is assumed to be the resource itself. In this case, the "value" attribute SHALL contain a list of one or more attributes that are to be replaced. o If the target location is a single-value attribute, the attributes @@ -1660,21 +1723,21 @@ }, { "value":"babs@jensen.org", "type":"home" } ], "nickname":"Babs" }] } -3.4. Deleting Resources +3.6. 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 Id. Service providers MUST also omit the resource from future query results. In addition the service provider SHOULD NOT consider the deleted resource in conflict calculation. For example if a User resource is deleted, a CREATE request for a User resource with the same userName as the previously deleted resource should not fail with a 409 error due to userName conflict. @@ -1704,21 +1767,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 Operations +3.7. 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: @@ -1772,50 +1835,50 @@ except in the event of a POST failure. response The HTTP response body to the specified request operation. When indicating a response with an HTTP status other than a 200 series response, the response body MUST be included. For normal completion, the server MAY elect to omit the response body. status The HTTP response status code to the requested operation. When indicating an error, the "response" attribute MUST contain - the detailed error response as per Section 3.10. + the detailed error response as per Section 3.12. If a bulk job is processed successfully the HTTP response code 200 OK MUST be returned, otherwise an appropriate HTTP error code MUST be returned. The service provider MUST continue performing as many changes as possible and disregard partial failures. The client MAY override this behavior by specifying a value for the "failOnErrors" attribute. The failOnErrors attribute defines the number of errors that the service provider should accept before failing the remaining operations returning the response. To be able to reference a newly created resource the attribute bulkId MUST be specified when creating new resources. The "bulkId" is defined by the client as a surrogate identifier in a POST operation - (see Section 3.5.2). The service provider MUST return the same + (see Section 3.7.2). The service provider MUST return the same "bulkId" together with the newly created resource. The "bulkId" can then be used by the client to map the service provider id with the "bulkId" of the created resource. A SCIM service provider MAY elect to optimize a sequence operations received (e.g. to improve processing performance). When doing so, the service provider MUST ensure the clients intent is preserved and the same stateful result is achieved as for non-optimized processing. For example, before a "User" can be added to a "Group", they must first be created. Processing these requests out of order, might result in a failure to add the new "User" to the "Group". -3.5.1. Circular Reference Processing +3.7.1. Circular Reference Processing 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/scim+json Content-Type: application/scim+json @@ -1911,21 +1974,21 @@ "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 +3.7.2. BulkdId Temporary Identifiers 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. @@ -2082,21 +2145,21 @@ "manager": { "managerId": "batchId:qwerty", "displayName": "Alice" } } } } ] } -3.5.3. Response and Error Handling +3.7.3. Response and Error Handling The service provider response MUST include the result of all processed operations. A "location" attribute that includes the resource's endpoint MUST be returned for all operations excluding failed POSTs. The status attribute includes information about the success or failure of one operation within the bulk job. The attribute status MUST include the code attribute that holds the HTTP response code that would have been returned if a single HTTP request would have been used. If an error occurred the status MUST also include the description attribute containing a human readable @@ -2318,21 +2381,21 @@ "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "method": "POST", "bulkId": "ytrewq", "version": "W\/\"lha5bbazU3fNvfe5\"", "status": "201" } ] } -3.5.4. Maximum Operations +3.7.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. 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 @@ -2353,21 +2416,21 @@ 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 +3.8. 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 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., @@ -2388,50 +2451,50 @@ Multi-valued attributes in JSON are encoded as arrays; e.g., "attributes": [ "value1", "value2" ] Elements with nested elements are represented as objects in JSON; e.g, "attribute": { "subattribute1": "value1", "subattribute2": "value2" } -3.7. Additional Operation Response Parameters +3.9. Additional Operation Response Parameters For any SCIM operation where a resource representation is returned (e.g. HTTP GET), the attributes returned are defined as the minimum attribute set plus default attributes set. The minimum set are those attributes whose schema have "returned" set to "always". The default attribute set are those attributes whose schema have "returned" set to "default". Clients MAY request a partial resource representation on any operation that returns a resource within the response by specifying either of the mutually exclusive URL query parameters "attributes" OR "excludedAtributes" as follows: attributes When specified the default list of attributes SHALL be overridden and each resource returned MUST contain the minimum set of resource attributes and any attributes or sub- attributes explicitly requested by the "attributes" parameter. The query parameter attributes value is a comma separated list of resource attribute names in standard - attribute notation (Section 3.8) form (e.g. userName, name, + attribute notation (Section 3.10) form (e.g. userName, name, emails). excludedAttributes When specified, each resource returned MUST contain the minimal set of resource attributes. Additionally, the default set of attributes minus those attributes listed in "excludedAttributes" are also returned. The query parameter attributes value is a comma separated list of resource attribute names in standard attribute - notation (Section 3.8) form (e.g. userName, name, emails). + notation (Section 3.10) form (e.g. userName, name, emails). . GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8 Giving the response HTTP/1.1 200 OK @@ -2447,40 +2510,40 @@ "meta":{ "resourceType": "User", "created":"2011-08-01T18:29:49.793Z", "lastModified":"2011-08-01T18:29:49.793Z", "location": "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646", "version":"W\/\"a330bc54f0671c9\"" } } -3.8. Attribute Notation +3.10. Attribute Notation All operations share a common scheme for referencing simple and complex attributes. In general, attributes are identified by prefixing the attribute name with its schema URN separated by a ':' character; e.g., the core User resource attribute 'userName' is identified as "urn:ietf:params:scim:schemas:core:2.0:User:userName". Clients MAY omit core schema attribute URN prefixes though MUST fully qualify extended attributes with the associated resource URN; e.g., the attribute 'age' defined in "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is fully encoded as "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age". A Complex attributes' Sub-Attributes are referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute name}.{Sub-Attribute name}. For example, the fully qualified path for a User's givenName is "urn:ietf:params:scim:schemas:core:2.0:User:name.givenName" All facets (URN, attribute and Sub-Attribute name) of the fully encoded Attribute name are case insensitive. -3.9. "/Me" Authenticated Subject Alias +3.11. "/Me" Authenticated Subject Alias A client MAY use a URL of the form "/Me" as a URI alias for the User or other resource associated with the currently authenticated subject for any SCIM operation. A service provider MAY respond in ONE of 3 ways: o A service provider that does NOT support this feature SHOULD respond with status 403 (FORBIDDEN). o A service provider MAY choose to redirect the client using HTTP @@ -2493,21 +2556,21 @@ 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 7.3 for information on security considerations related to this operation. -3.10. HTTP Status and Error Response Handling +3.12. 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 attributes are defined for a SCIM error response using a JSON body: @@ -2575,81 +2638,81 @@ +--------------+---------------+------------------------------------+ Table 7: SCIM HTTP Status Code Usage For HTTP Status 400 (Bad Request) responses, the following detail error types are defined: +--------------+------------------------------+---------------------+ | scimType | Description | Applicability | +--------------+------------------------------+---------------------+ - | invalidFilte | The specified filter syntax | GET(Section 3.2.2), | + | invalidFilte | The specified filter syntax | GET(Section 3.4.2), | | r | was invalid (does not comply | POST (Search - | - | | with Figure 1) or the | Section 3.2.3), | + | | with Figure 1) or the | Section 3.4.3), | | | specified attribute and | PATCH (Path Filter | - | | filter comparison | - Section 3.3.2) | + | | filter comparison | - Section 3.5.2) | | | combination is not | | | | supported. | | - | tooMany | The specified filter yields | GET(Section 3.2.2), | + | tooMany | The specified filter yields | GET(Section 3.4.2), | | | many more results than the | POST (Search - | - | | server is willing calculate | Section 3.2.3) | + | | server is willing calculate | Section 3.4.3) | | | or process. For example, a | | | | filter such as "(userName | | | | pr)" by itself would return | | | | all entries with a | | | | "userName" and MAY not be | | | | acceptable to the service | | | | provider. | | | uniqueness | One or more of attribute | POST (Create - | - | | values is already in use or | Section 3.1), PUT | - | | is reserved. | (Section 3.3.1), | + | | values is already in use or | Section 3.3), PUT | + | | is reserved. | (Section 3.5.1), | | | | PATCH (Section | - | | | 3.3.2) | + | | | 3.5.2) | | mutability | The attempted modification | PUT (Section | - | | is not compatible with the | 3.3.1), PATCH | - | | target attributes mutability | (Section 3.3.2) | + | | is not compatible with the | 3.5.1), PATCH | + | | target attributes mutability | (Section 3.5.2) | | | or current state (e.g. | | | | modification of an immutable | | | | attribute with an existing | | | | value). | | | invalidSynta | The request body message | POST (Search - | - | x | structure was invalid or did | Section 3.2.2, | + | x | structure was invalid or did | Section 3.4.2, | | | not conform to the request | Create - Section | - | | schema. | 3.1, Bulk - Section | - | | | 3.5), PUT (Section | - | | | 3.3.1) | + | | schema. | 3.3, Bulk - Section | + | | | 3.7), PUT (Section | + | | | 3.5.1) | | invalidPath | The path attribute was | PATCH (Section | - | | invalid or malformed (see | 3.3.2) | + | | invalid or malformed (see | 3.5.2) | | | Figure 7). | | | noTarget | The specified "path" did not | PATCH (Section | - | | yield an attribute or | 3.3.2) | + | | yield an attribute or | 3.5.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 | + | | missing, or the value | 3.4.2), POST | | | specified was not compatible | (Create - Section | - | | with the operation or | 3.1, Query - | - | | attribute type (see Section | Section 3.2.2), PUT | - | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), | + | | with the operation or | 3.3, Query - | + | | attribute type (see Section | Section 3.4.2), PUT | + | | 2.1 [I-D.ietf-scim-core-sche | (Section 3.5.1), | | | ma]), or schema (see Section | PATCH (Section | - | | 4 [I-D.ietf-scim-core-schema | 3.3.2) | + | | 4 [I-D.ietf-scim-core-schema | 3.5.2) | | | ]). | | | invalidVers | The specified SCIM protocol | GET (Section | - | | version is not supported | 3.2.2), POST (ALL), | - | | (see Section 3.11). | PUT (Section | - | | | 3.3.1), PATCH | - | | | (Section 3.3.2), | + | | version is not supported | 3.4.2), POST (ALL), | + | | (see Section 3.13). | PUT (Section | + | | | 3.5.1), PATCH | + | | | (Section 3.5.2), | | | | DELETE (Section | - | | | 3.4) | + | | | 3.6) | +--------------+------------------------------+---------------------+ Table 8: Table of SCIM Detail Error Keyword Values Note that in the table above (Table 8), the applicability table applies to the normal HTTP method but MAY apply within a SCIM Bulk operation (via HTTP POST). Error example in response to a non-existent GET request. @@ -2673,35 +2736,35 @@ } [[Editor's note: while the detail error codes seem to have consensus, there is a question about whether the error codes should be extensible so that individual service providers may define site specific codes. Should all scimTypes be URIs, so that scimTypes can be registered via IANA? Should there be a separate field defined for this purpose? Or, should custom signalling (for non-protocol/schema errors, be out of scope?]] -3.11. API Versioning +3.13. API Versioning The Base URL MAY be appended with a version identifier as a separate 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 SCIM protocol version supported by the service provider. -3.12. Versioning Resources +3.14. Versioning Resources The SCIM protocol 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: @@ -2807,21 +2870,21 @@ resources available on a SCIM Service Provider (e.g. Users and Groups). Each resource type defines the endpoints, the core schema URI that defines the resource, and any supported schema extensions. The attributes defining a resource type can be found in Section 6 [I-D.ietf-scim-core-schema], and an example representation can be found in Section 8.6 [I-D.ietf-scim-core-schema]. In cases where a request is for a specific "ResourceType" or "Schema", the single JSON object is returned in the same way a single - User or Group is retrieved as per Section 3.2.1. When returning + User or Group is retrieved as per Section 3.4.1. When returning multiple ResourceTypes or Schemas, the message form described by "urn:ietf:params:scim:api:messages:2.0:ListResponse" (ListResponse) form SHALL be used as shown in Figure 3 and Figure 9 below. Query parameters described in section 3.2 such as, sorting, attributes, and paging SHALL be ignored. If a "filter" is provided, the service provider SHOULD respond with HTTP Status 403 (FORBIDDEN) to ensure clients cannot incorrectly assume any matching conditions specified in a filter are true. The following is a non-normative example of an HTTP GET to the @@ -2980,21 +3043,21 @@ As mentioned in ,Section 9.4 [RFC7231], SCIM 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 ). + Section 3.4.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 detailed error, "confidential_restricted" may be returned indicating the request must be submitted using POST. A non-normative example: HTTP/1.1 403 FORBIDDEN { @@ -3154,50 +3217,50 @@ the following registers and extends the SCIM Schema Registry to define SCIM protocol request/response JSON schema URN identifier prefix of "urn:ietf:params:scim:api:messages:2.0" which is part of the URN sub-Namespace for SCIM. There is no specific associated resource type. +---------------------------------+-----------------+---------------+ | Schema URI | Name | Reference | +---------------------------------+-----------------+---------------+ | urn:ietf:params:scim:api: | List/Query | See Section | - | messages:2.0:ListResponse | Response | 3.2.2 | + | messages:2.0:ListResponse | Response | 3.4.2 | | urn:ietf:params:scim:api: | POST Query | See Section | - | messages:2.0:SearchRequest | Request | 3.2.3 | + | messages:2.0:SearchRequest | Request | 3.4.3 | | urn:ietf:params:scim:api: | Patch Operation | See Section | - | messages:2.0:PatchOp | | 3.3.2 | + | messages:2.0:PatchOp | | 3.5.2 | | urn:ietf:params:scim:api: | Bulk Operations | See Section | - | messages:2.0:BulkRequest | Request | 3.5 | + | messages:2.0:BulkRequest | Request | 3.7 | | urn:ietf:params:scim:api: | Bulk Operations | See Section | - | messages:2.0:BulkResponse | Response | 3.5 | + | messages:2.0:BulkResponse | Response | 3.7 | | urn:ietf:params:scim:api: | Error Response | See Section | - | messages:2.0:Error | | 3.10 | + | messages:2.0:Error | | 3.12 | +---------------------------------+-----------------+---------------+ Table 9: SCIM Schema URIs for Data Resources 9. References 9.1. Normative References [I-D.ietf-precis-saslprepbis] Saint-Andre, P. and A. Melnikov, "Preparation, Enforcement, and Comparison of Internationalized Strings Representing Usernames and Passwords", draft-ietf-precis- - saslprepbis-13 (work in progress), December 2014. + saslprepbis-14 (work in progress), March 2015. [I-D.ietf-scim-core-schema] Hunt, P., Grizzle, K., Wahlstroem, E., and C. Mortimore, "System for Cross-Domain Identity Management: Core - Schema", draft-ietf-scim-core-schema-16 (work in - progress), February 2015. + Schema", draft-ietf-scim-core-schema-17 (work in + progress), March 2015. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [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. @@ -3227,21 +3290,21 @@ [RFC7235] Fielding, R. and J. Reschke, "Hypertext Transfer Protocol (HTTP/1.1): Authentication", RFC 7235, June 2014. 9.2. Informative References [I-D.ietf-precis-framework] Saint-Andre, P. and M. Blanchet, "PRECIS Framework: Preparation, Enforcement, and Comparison of Internationalized Strings in Application Protocols", - draft-ietf-precis-framework-22 (work in progress), + draft-ietf-precis-framework-23 (work in progress), February 2015. [OpenSearch] Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . [Order-Operations] Wikipedia, "Order of Operations: Programming Languages", . [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC 6749, October 2012. @@ -3252,20 +3315,24 @@ [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. [RFC7238] Reschke, J., "The Hypertext Transfer Protocol Status Code 308 (Permanent Redirect)", RFC 7238, June 2014. + [XML-Schema] + Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes + Second Edition", October 2004. + Appendix A. Contributors Samuel Erdtman (samuel@erdtman.se) Patrick Harding (pharding@pingidentity.com) Appendix B. Acknowledgments The editors would like to acknowledge the contribution and work of the past draft editors: @@ -3460,20 +3526,24 @@ be returned per the response example in figure 4. Clarifications and improvements to examples in PATCH replace operations Updated references to saslprep and precis frameworks Draft 15 - PH - Clarifications on returning "path" handling during PATCH "replace" operations. Updated references. + Draft 16 - PH - Clarification of SCIM protocol definitions of + resources vs messages and general process rules regarding schema + including validation. + Authors' Addresses Phil Hunt (editor) Oracle Corporation Email: phil.hunt@yahoo.com Kelly Grizzle SailPoint