--- 1/draft-ietf-scim-api-07.txt 2014-08-01 16:14:33.522084478 -0700 +++ 2/draft-ietf-scim-api-08.txt 2014-08-01 16:14:33.642087372 -0700 @@ -1,31 +1,33 @@ Network Working Group P. Hunt, Ed. Internet-Draft Oracle Intended status: Standards Track K. Grizzle -Expires: January 4, 2015 SailPoint +Expires: February 2, 2015 SailPoint M. Ansari Cisco E. Wahlstroem - Technology Nexus + Nexus Technology C. Mortimore Salesforce - July 3, 2014 + August 1, 2014 System for Cross-Domain Identity Management:Protocol - draft-ietf-scim-api-07 + draft-ietf-scim-api-08 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 + is designed to make managing user identity in multi-domain based + applications and services easier using HTTP Protocol. 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 integration, while applying existing authentication, authorization, and privacy models. It's intent is to reduce the cost and complexity of user management operations by providing a common user schema and extension model, as well as binding documents to provide patterns for exchanging this schema using standard protocols. In essence, make it fast, cheap, and easy to move users in to, out of, and around the cloud. Status of This Memo @@ -36,21 +38,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 January 4, 2015. + This Internet-Draft will expire on February 2, 2015. Copyright Notice Copyright (c) 2014 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -58,264 +60,253 @@ to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as 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 . . . . . . . . . . . . . . . . . . . . . . . 3 + 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 2. Authentication and Authorization . . . . . . . . . . . . . . 4 - 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 - 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 7 - 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. SCIM Protocol . . . . . . . . . . . . . . . . . . . . . . . . 4 + 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 + 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8 + 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8 + 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8 + 3.2.2. Query Resources . . . . . . . . . . . . . . . . . . . 9 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 23 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26 - 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 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 Error Responses . . . . . . . . . . . . . . . . . . 53 - 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 57 - 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 57 - 4. Preparation and Comparison of Internationalized Strings . . . 59 - 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 59 - 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 60 - 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 61 - 6. Security Considerations . . . . . . . . . . . . . . . . . . . 61 - 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 61 - 6.2. Request URI Information Leakage . . . . . . . . . . . . . 61 - 6.3. Case Insensitive Comparision & International Languages . 62 - 6.4. Universal Identifiers . . . . . . . . . . . . . . . . . . 62 - 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 62 - 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 62 - 7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 63 - 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 64 - 8.1. Normative References . . . . . . . . . . . . . . . . . . 64 - 8.2. Informative References . . . . . . . . . . . . . . . . . 66 - Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 66 - Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 66 - Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 66 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68 + 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 36 + 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 36 + 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 51 + 3.7. Additional Operation Response Parameters . . . . . . . . 52 + 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 53 + 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 54 + 3.10. HTTP Status and Error Response Handling . . . . . . . . . 54 + 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 58 + 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 58 + 4. Preparation and Comparison of Internationalized Strings . . . 60 + 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 60 + 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 61 + 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 62 + 6. Security Considerations . . . . . . . . . . . . . . . . . . . 62 + 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 62 + 6.2. Disclosure of Sensitive Information in URIs . . . . . . . 62 + 6.3. HTTP Considerations . . . . . . . . . . . . . . . . . . . 63 + 6.4. Secure Storage and Handling of Sensitive Data . . . . . . 63 + 6.5. Case Insensitive Comparision & International Languages . 64 + 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 64 + 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 64 + 7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 65 + 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 66 + 8.1. Normative References . . . . . . . . . . . . . . . . . . 66 + 8.2. Informative References . . . . . . . . . . . . . . . . . 67 + Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 68 + Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 68 + Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 68 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 71 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. + 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. 1.1. Intended Audience - This document is intended as a guide to SCIM API usage for both - identity service providers and clients. + This document is intended as a guide to SCIM API usage for both SCIM + HTTP service providers and HTTP clients that may provision + information to service providers or retrieve information from them. 1.2. Notational Conventions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. These keywords are capitalized when used to unambiguously specify requirements of the protocol or application features and behavior that affect the interoperability and security of implementations. When these words are not capitalized, they are meant in their natural-language sense. 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/" + Base URI: The SCIM HTTP protocol is described in terms of a path + relative to a Base URI. The Base URI 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 ). 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 + Because SCIM builds on the HTTP protocol, it does not define a scheme + for authentication and authorization. SCIM depends on standard HTTP + authentication schemes. Implementers SHOULD support existing authentication/authorization schemes. In particular, OAuth2 [RFC6750] is RECOMMENDED. Appropriate security considerations of the selected authentication and authorization schemes SHOULD be taken. Because this protocol uses HTTP response status codes as the primary means of reporting the result of a request, servers are advised to respond to unauthorized or unauthenticated requests using the 401 response code in accordance with Section 3.1 of [RFC7235]. - All examples assume OAuth2 bearer token [RFC6750] ; e.g., + All examples show an OAuth2 bearer token [RFC6750] (though it is not + required) ; e.g., GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1 Host: example.com Authorization: Bearer h480djs93hd8 The context of the request (i.e. the user for whom data is being requested) MUST be inferred by service providers. -3. API +3. SCIM Protocol 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. - GET Retrieves a complete or partial resource. + GET Retrieves one or more complete or partial resources. - POST Create new resources, create a search request, or bulk modify - resources. + POST Depending on the endpoint, creates new resources, create a + search request, or may be used to bulk modify resources. PUT Modifies a resource by replacing existing attributes with a - specified set of replacement attributes (replace). PUT SHOULD NOT + specified set of replacement attributes (replace). PUT MUST 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 | - | | | 3.2.1), POST | dify Users | - | | | (Section | | - | | | 3.1), PUT | | - | | | (Section | | - | | | 3.3.1), PATCH | | - | | | (Section | | - | | | 3.3.2), | | - | | | DELETE | | - | | | (Section 3.4) | | - | Group | /Groups | GET (Section | Retrieve/Add/Mo | - | | | 3.2.1), POST | dify Groups | - | | | (Section | | - | | | 3.1), PUT | | - | | | (Section | | - | | | 3.3.1), PATCH | | - | | | (Section | | - | | | 3.3.2), | | - | | | DELETE | | - | | | (Section 3.4) | | - | Service | /ServiceProviderCo | GET (Section | Retrieve the | - | Provider C | nfigs | 3.2.1) | service | - | onfigurati | | | provider's | - | on | | | configuration | - | Resource | /ResourceTypes | GET (Section | Retrieve the | - | Type | | 3.2.1) | supported | - | | | | resource types | - | Schema | /Schemas | GET (Section | Retrieve a | - | | | 3.2.1) | resource's | - | | | | schema | - | Bulk | /Bulk | POST (Section | Bulk modify | - | | | 3.5) | resources | - | Search | [prefix]/.search | POST (Section | Perform a | - | | | 3.2.3) | search at | - | | | | system root or | - | | | | within a | - | | | | resource | - | | | | endpoint for | - | | | | one or more | - | | | | resource types | - | | | | using POST. | - +------------+--------------------+---------------+-----------------+ + 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) + Service /ServiceProvider GET (Section 3.2.1) Retrieve service + Provider Configs provider's + Config configuration + Resource /ResourceTypes GET (Section 3.2.1) Retrieve supported + Type resource types + Schema /Schemas GET (Section 3.2.1) Retrieve one or more + supported schemas. + Bulk /Bulk POST (Section 3.5) Bulk updates to one + or more resources + Search [prefix]/.search POST (Section 3.2.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. - 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. + Error status codes SHOULD be transmitted via the HTTP status code of + the response (if possible), and SHOULD also be specified in the body + of the response (see Section 3.10). 3.1. Creating Resources - To create new resources, clients send POST requests to the resource - container endpoint such as: "/Users" or "/Groups". + To create new resources, clients send HTTP POST requests to the + resource endpoint such as: "/Users" or "/Groups". - Attributes whose mutability is "readOnly", that are included in the - request body SHALL be ignored. + Attributes in the request body, whose mutability is "readOnly", 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. + attributes SHALL be defaulted. Clients that intend to override + server defaulted attributes, MAY specify "null" for a single-valued + attribute or an empty array "[]" for a multi-valued attribute to + clear all values. - 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. + When the service provider successfully creates the new resource, an + HTTP response SHALL be returned with HTTP status "201" ("Created"). + The response body SHOULD contain the service provider's + representation of the newly created resource. The URI of the created + resource SHALL included in the HTTP "Location" header and in JSON + resource representation under the attribute "meta.location". Since + the server is free to alter and/or ignore POSTed content, returning + the full representation can be useful to the client, enabling it to + correlate the client and server views of the new resource. 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. + duplicate "userName", the service provider MUST return an HTTP Status + 409, with "scimType" error code of "uniqueness" as per Section 3.10. + + Below, in the following example, a client sends a POST request + containing a "User" to the "/Users" endpoint. - Below, the client sends a POST request containing a user POST /Users HTTP/1.1 Host: example.com 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", "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. + In response to the example request above, the server signals a + successful creation with an HTTP status code 201 (Created) and + returns a representation of the resource created. HTTP/1.1 201 Created 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", @@ -329,39 +320,41 @@ "name":{ "formatted":"Ms. Barbara J Jensen III", "familyName":"Jensen", "givenName":"Barbara" }, "userName":"bjensen" } 3.1.1. Resource Types When adding a resource to a specific endpoint, the meta attribute - "resourceType" SHALL be set by the service provider to the - corresponding resource Type for the endpoint. For example, "/Users" + "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 - "User" and "Group" resources are retrieved via opaque, unique URLs or - via Query. Service providers MAY choose to respond with a sub-set of - resource attributes, though MUST minimally return the resource id and - meta attributes. + 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". 3.2.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}". + resource endpoint; e.g., "/Users/{id}" or "/Groups/{id}", or + "/Schemas/{id}". - If the resource exists the server responds with a status code of 200 - and includes the result in the body of the response. + 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. GET /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Accept: application/scim+json Authorization: Bearer h480djs93hd8 The server responds with: @@ -394,52 +387,52 @@ } ], "emails":[ { "value":"bjensen@example.com", "type":"work" } ] } -3.2.2. List/Query Resources +3.2.2. 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 (see following - sub-sections). Service providers MAY support additional query - parameters not specified here, and Providers SHOULD ignore any query - parameters they don't recognize. + 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. - List and query responses MUST be identified using the following URI: + Responses MUST be identified using the following URI: "urn:scim:api:messages:2.0:ListResponse". The following attributes - are defined for list and query responses: + 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. 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 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. + of list results. REQUIRED when partial results returned due to + pagination. itemsPerPage The number of resources returned in a list response - page. REQUIRED if pagination (Section 3.2.2.4) is requested. + page. REQUIRED when partial results returned due to pagination. - A query that does not return any matches SHALL return success with - "totalResults" set to a value of 0. + A query that does not return any matches SHALL return success (HTTP + Status 200) 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/scim+json Authorization: Bearer h480djs93hd8 The following is an example response to the query above: @@ -454,55 +447,65 @@ "userName":"bjensen" }, { "userName":"jsmith" } ] } 3.2.2.1. Query Endpoints - Queries MAY be performed against a SCIM resource object or a resource - type endpoint. For example: + Queries MAY be performed against a SCIM resource object, a resource + type endpoint, or a SCIM server root. For example: - "/Users/{userid}" + "/Users/{id}" "/Users" "/Groups" - A server MAY support searches against the server root (e.g. "/"). A - search against a server root indicates that ALL resources within the + A query against a server root indicates that ALL resources within the server SHALL be included subject to filtering. A filter expression using "meta.resourceType" MAY be used to restrict results to one or - more specific resource types (e.g. "User" ). + more specific resource types (to exclude others). For example: - When processing search operations across endpoints that include more - than one SCIM resource type (e.g. a search from the server root - endpoint), filters MUST be processed in the same fashion as outlined - in Section 3.2.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. + 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. + 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 - Filtering is OPTIONAL. Clients may request a subset of resources by - specifying the 'filter' URL 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 + 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. - The attribute name and attribute operator are case insensitive. For - example, the following two expressions will evaluate to the same - logical value: + Attribute names and attribute operators used in filters are case + insensitive. For example, the following two expressions will + evaluate to the same logical value: filter=userName Eq "john" filter=Username eq "john" The filter parameter MUST contain at least one valid Boolean expression. Each expression MUST contain an attribute name followed by an attribute operator and optional value. Multiple expressions MAY be combined using the two logical operators. Furthermore expressions can be grouped together using "()". @@ -524,53 +527,72 @@ | | | substring of the attribute value, | | | | starting at the beginning of the | | | | attribute value. This criterion is | | | | satisfied if the two strings are | | | | identical. | | ew | ends with | The entire operator value must be a | | | | substring of the attribute value, | | | | matching at the end of the attribute | | | | value. This criterion is satisfied if | | | | the two strings are identical. | - | pr | present | If the attribute has a non-empty value, | - | | (has value) | or if it contains a non-empty node for | - | | | complex attributes there is a match. | + | pr | present | If the attribute has a non-empty or non- | + | | (has value) | null value, or if it contains a non- | + | | | empty node for complex attributes there | + | | | is a match. | | gt | greater | If the attribute value is greater than | | | than | operator value, there is a match. The | | | | actual comparison is dependent on the | | | | attribute type. For string attribute | | | | types, this is a lexicographical | | | | comparison and for DateTime types, it is | - | | | a chronological comparison. | + | | | a chronological comparison. For Integer | + | | | attributes it is a comparison by numeric | + | | | value. Boolean and Binary attributes | + | | | SHALL cause a failed response (HTTP | + | | | Status 400) with scimType of | + | | | invlaidFiler. | | ge | greater | If the attribute value is greater than | | | than or | or equal to the operator value, there is | | | equal | a match. The actual comparison is | | | | dependent on the attribute type. For | | | | string attribute types, this is a | | | | lexicographical comparison and for | | | | DateTime types, it is a chronological | - | | | comparison. | + | | | comparison. For Integer attributes it is | + | | | a comparison by numeric value. Boolean | + | | | and Binary attributes SHALL cause a | + | | | failed response (HTTP Status 400) with | + | | | scimType of invlaidFiler. | | lt | less than | If the attribute value is less than | | | | operator value, there is a match. The | | | | actual comparison is dependent on the | | | | attribute type. For string attribute | | | | types, this is a lexicographical | | | | comparison and for DateTime types, it is | - | | | a chronological comparison. | + | | | a chronological comparison. For Integer | + | | | attributes it is a comparison by numeric | + | | | value. Boolean and Binary attributes | + | | | SHALL cause a failed response (HTTP | + | | | Status 400) with scimType of | + | | | invlaidFiler. | | le | less than | If the attribute value is less than or | | | or equal | equal to the operator value, there is a | | | | match. The actual comparison is | | | | dependent on the attribute type. For | | | | string attribute types, this is a | | | | lexicographical comparison and for | | | | DateTime types, it is a chronological | - | | | comparison. | + | | | comparison. For Integer attributes it is | + | | | a comparison by numeric value. Boolean | + | | | and Binary attributes SHALL cause a | + | | | failed response (HTTP Status 400) with | + | | | scimType of invlaidFiler. | +----------+-------------+------------------------------------------+ Table 2: Attribute Operators +----------+-------------+------------------------------------------+ | Operator | Description | Behavior | +----------+-------------+------------------------------------------+ | and | Logical And | The filter is only a match if both | | | | expressions evaluate to true. | | or | Logical or | The filter is a match if either | @@ -614,21 +636,21 @@ nameChar = "-" / "_" / DIGIT / ALPHA attrPath = [URI ":"] ATTRNAME *1subAttr ; SCIM attribute name ; URI is SCIM "schema" URI subAttr = "." ATTRNAME ; a sub-attribute of a complex attribute - attrExpr = (attrPath SP "pr") / + attrExp = (attrPath SP "pr") / (attrPath SP compareOp SP compValue) compValue = false / null / true / number / string ; rules from JSON (RFC7159) compareOp = "eq" / "ne" / "co" / "sw" / "ew" / "gt" / "lt" / "ge" / "le" @@ -662,21 +684,21 @@ 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.' String type attributes are case insensitive by default unless the attribute type is defined as case exact. Attribute comparison operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string attributes unless the attribute is defined as case exact. By default all string attributes are case insensitive. - Clients MAY search by schema or schema extensions by using a filter + Clients MAY query by schema or schema extensions by using a filter expression including the "schemas" attribute. The following are examples of valid filters. Some attributes (e.g. rooms and rooms.number) are hypothetical extensions and are not part of SCIM core schema: filter=userName eq "bjensen" filter=name.familyName co "O'Malley" @@ -708,48 +730,49 @@ 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"] filter=addresses[state eq "CA" and rooms[type eq "bedroom" and number gt 2]] - Example Filters + Figure 2: Example Filters 3.2.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, 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., + 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., "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 caee insensitive attributes, sort 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 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 @@ -759,50 +782,50 @@ deleted or new ones could be added in-between requests. Pagination parameters and general behavior are derived from the OpenSearch Protocol [OpenSearch]. The following table describes the URL pagination parameters. +------------+----------------------------+-------------------------+ | Parameter | Description | Default | +------------+----------------------------+-------------------------+ | startIndex | The 1-based index of the | 1 | - | | first search result. A | | + | | first query result. A | | | | value less than 1 SHALL be | | | | interpreted as 1. | | | count | Non-negative Integer. | None. When specified | | | Specifies the desired | the service provider | - | | maximum number of search | MUST not return more | + | | maximum number of query | MUST not return more | | | results per page; e.g., | results than specified | | | 10. A negative value SHALL | though MAY return fewer | | | be interpreted as "0". A | results. If | | | value of "0" indicates no | unspecified, the | | | resource results are to be | maximum number of | | | returned except for | results is set by the | | | "totalResults". | service provider. | +------------+----------------------------+-------------------------+ Table 5: Pagination Request parameters The following table describes the query response pagination attributes specified by the service provider. +--------------+----------------------------------------------------+ | Element | Description | +--------------+----------------------------------------------------+ | itemsPerPage | Non-negative Integer. Specifies the number of | - | | search results returned in a query response page; | + | | query results returned in a query response page; | | | e.g., 10. | | totalResults | Non-negative Integer. Specifies the total number | | | of results matching the client query; e.g., 1000. | | startIndex | The 1-based index of the first result in the | - | | current set of search results; e.g., 1. | + | | current set of query 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/scim+json @@ -820,52 +843,55 @@ ... }] } 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 The following attributes control which attributes SHALL be returned - with a returned resource. + 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). OPTIONAL. + MUST be in standard.attribute notation (Section 3.8) form. See + additional retrieval query parameters (Section 3.7). 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. + retrieval query parameters (Section 3.7). 3.2.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 search result set, a SCIM client sends an HTTP POST + 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. - Search requests MUST be identified using the following URI: + Query requests MUST be identified using the following URI: 'urn:scim:api:messages:2.0:SearchRequest'. The following attributes - are defined for search requests: + 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. 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 @@ -881,49 +907,49 @@ 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. 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. startIndex An integer indicating the 1-based index of the first - search result. See pagination (Section 3.2.2.4). OPTIONAL. + query result. See pagination (Section 3.2.2.4). OPTIONAL. - count An integer indicating the desired maximum number of search + count An integer indicating the desired maximum number of query 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 + 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: ... { "schemas": ["urn:scim:api:messages:2.0:SearchRequest"], "attributes": ["displayName", "userName"], - "filter": "displayName sw \"smith\"", + "filter": "(displayName sw \"smith\") and (meta.resourceType eq \"User\")", "startIndex": 1, "count": 10 } - Figure 2: Example POST Search Request + Figure 3: Example POST Query Request - A search response is shown with the first page of results. For + A query 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/scim+json Location: https://example.com/.search { "schemas": ["urn:scim:api:messages:2.0:ListResponse"], "totalResults":100, "itemsPerPage":10, "startIndex":1, @@ -944,38 +970,37 @@ "https://example.com/Groups/c8596b90-7539-4f20968d1908", "resourceType":"Group", "lastModified": ... }, "displayName":"Smith Family" }, ... ] } - Figure 3: Example POST Search Response + Figure 4: Example POST Query 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 4.3 [RFC7231]. Resources such as Groups may be very large - hence implementers SHOULD support PATCH [RFC5789] to enable partial - resource modifications. + hence implementers SHOULD support HTTP PATCH [RFC5789] to enable + partial resource modifications. 3.3.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 SHOULD NOT be used to create new - resources. + service provider, HTTP PUT MUST NOT be used to create new resources. As the operation intent is to replace all attributes, SCIM clients MAY send all attributes regardless of each attribute's mutability. The server will apply attribute by attribute replace according to the following attribute mutability rules: readWrite, writeOnly Any values provided SHALL replace the existing attribute values. immutable If value(s) are already set for the attribute, the input @@ -995,22 +1020,22 @@ 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: + enabling the client to correlate the client's and the service + provider's views of the updated resource. Example: PUT /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" { "schemas":["urn:scim:api:messages:2.0:User"], @@ -1085,78 +1110,107 @@ 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 + Figure 5: SCIM Patch PATH Rule - The rules, "attrPath", "valuePath", and "subAttr" are defined in + The ABNF rules, "attrPath", "valuePath", and "subAttr" are defined in Section 3.2.2.2. The "valuePath" rule allows specific values of a complex, multi-valued attribute to be selected. Valid examples of "path" values are as follows: "path":"members" "path":"name.familyName" "path":"addresses[type eq \"work\"]" "path":"members[value eq \"2819c223-7f76-453a-919d-413861904646\"]" "path":"members[value eq \"2819c223-7f76-453a-919d-413861904646\"].displayName" + Figure 6: Example Path Values + 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. + return the appropriate HTTP response status code and a JSON detail + error response as defined in Section 3.10. + + The attribute notation rules described in Section 3.8 apply for + describing attribute paths. For all operations, the value of the + "schemas" attribute on the 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:scim:schemas:extension:enterprise:2.0:User:employeeNumber", + automatically adds the value + "urn:scim:schemas:extension:enterprise:2.0:User" to the resource's + "schemas" attribute. 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. + For a multi-valued attributes, a patch operation that sets a value's + "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 + 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. 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" 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: + 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 + indicated by "path" references: o If the target location does not exist, the attribute and value is added. o If the target location specifies a multi-valued attribute, a new value is added to the attribute. o if the target location specifies a single-valued attribute, the existing value is replaced. @@ -1164,25 +1218,20 @@ (has no value), the attribute is added with the new value. o If the target location exists, the value is replaced. o If the target location already contains the value specified, no changes SHOULD be made to the resource and a success response SHOULD be returned. Unless other operations change the resource, this operation SHALL NOT change the modify timestamp of the 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 following example shows how to add a member to a group. Some text removed for readability ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce Host: example.com Accept: application/scim+json Content-Type: application/scim+json Authorization: Bearer h480djs93hd8 If-Match: W/"a330bc54f0671c9" @@ -1210,35 +1259,47 @@ ETag: W/"b431af54f0671a2" Location: "https://example.com/Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce" 3.3.2.2. Remove Operation The "remove" operation removes 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 target location is a single-value attribute, the attribute - and its associated value is removed. + and its associated value is removed and the attribute SHALL be + considered unassigned. o If the target location is a multi-valued attribute and no filter - is specified, the attribute and all values are removed. + is specified, the attribute and all values are removed and the + attribute SHALL be considered unassigned. o If the target location is a multi-valued attribute and a complex filter is specified comparing a "value", the values matched by the - filter are removed. + filter are removed. If after removal of the selected values, no + other values remain, the multi-valued attribute SHALL be + considered unassigned. 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. + 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". The following example shows how to remove a member from a group. As - with the previous example, the "display" Sub-Attribute is optional. + 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 readability ("..."): PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce @@ -1433,21 +1493,21 @@ "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 Id. Service providers MUST also omit the resource from future query - results. In addition the service provider MUST not consider the + 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. DELETE /Users/2819c223-7f76-453a-919d-413861904646 Host: example.com Authorization: Bearer h480djs93hd8 If-Match: W/"c310cd84f0281b7" @@ -1510,91 +1570,94 @@ method The HTTP method of the current operation. Possible values are POST, PUT, PATCH or DELETE. REQUIRED. bulkId The transient identifier of a newly created resource, unique within a bulk request and created by the client. The 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. + version The current resource version. Version is MAY be used if + the service provider supports ETags and the method is PUT, + PATCH, or DELETE. 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. 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 - response. - - code The HTTP response code that would have been returned if a - a single HTTP request would have been used. REQUIRED. + 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. - description A human readable error message. REQUIRED when an - error occurred. + 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. 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 failOnErrors attribute. The - failOnErrors attribute defines the number of errors that the service - provider should accept before failing the remaining operations - returning the response. + 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. 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. - There can be more then one operation per resource in each bulk job. - The Service client MUST take notice of the unordered structure of - JSON and the service provider can process operations in any order. - For example, if the Service client sends two PUT operations in one - request, the outcome is non-deterministic. + 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". The service provider response MUST include the result of all - processed operations. A location attribute that includes the + processed operations. A "location" attribute that includes the resource's end point 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 explanation of the error. - "status": { - "code": "201" - } + "status": "201" The following is an example of a status in a failed operation. -"status": { - "code": "400", - "description": "Request is unparseable, syntactically incorrect, or violates schema." +"status": "400", +"response":{ + "schemas": ["urn:scim:api:messages:2.0:Error"], + "scimType":"invalidSyntax" + "detail":"Request is unparseable, syntactically incorrect, or violates schema.", + "status":"400" } 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 @@ -1658,114 +1720,118 @@ Content-Type: application/scim+json { "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" - } + "status": "201" }, { "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", "method": "PUT", "version": "W\/\"huJj29dMNgu3WXPD\"", - "status": { - "code": "200" - } + "status": "200" }, { "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "method": "PATCH", "version": "W\/\"huJj29dMNgu3WXPD\"", - "status": { - "code": "200" - } + "status": "200" }, { "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", "method": "DELETE", - "status": { - "code": "204" - } + "status": "204" } ] } 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/scim+json { "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." + "status": "400", + "response":{ + "schemas": ["urn:scim:api:messages:2.0:Error"], + "scimType":"invalidSyntax" + "detail":"Request is unparseable, syntactically incorrect, or violates schema.", + "status":"400" } } ] } 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/scim+json { "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." + "status": "400", + "response":{ + "schemas": ["urn:scim:api:messages:2.0:Error"], + "scimType":"invalidSyntax" + "detail":"Request is unparseable, syntactically incorrect, or violates schema.", + "status":"400" } }, { "location": "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041", "method": "PUT", - "status": { - "code": "412", - "description": "Failed to update as user changed on the server since you last retrieved it." + "status": "412", + "response":{ + "schemas": ["urn:scim:api:messages:2.0:Error"], + "detail":"Failed to update as user changed on the server since you last retrieved it.", + "status":"412" } }, { "location": "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc", "method": "PATCH", - "status": { - "code": "412", - "description": "Failed to update as user changed on the server since you last retrieved it." + "status": "412", + "response":{ + "schemas": ["urn:scim:api:messages:2.0:Error"], + "detail":"Failed to update as user changed on the server since you last retrieved it.", + "status":"412" } }, { "location": "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b", "method": "DELETE", - "status": { - "code": "404", - "description": "Specified resource; e.g., User, does not exist." + "status": "404", + "response":{ + "schemas": ["urn:scim:api:messages:2.0:Error"], + "detail":"Resource does not exist.", + "status":"404" } } ] } The 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., @@ -1797,21 +1863,21 @@ }, { "method": "POST", "path": "/Groups", "bulkId": "ytrewq", "data": { "schemas": ["urn:scim:schemas:core:2.0:Group"], "displayName": "Tour Guides", "members": [ { - "type": "user", + "type": "User", "value": "bulkId:qwerty" } ] } } ] } The service provider returns the following response. @@ -1819,32 +1885,28 @@ Content-Type: application/scim+json { "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" - } + "status": "201" }, { "location": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "method": "POST", "bulkId": "ytrewq", "version": "W\/\"lha5bbazU3fNvfe5\"", - "status": { - "code": "201" - } + "status": "201" } ] } 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/scim+json @@ -1938,36 +2000,36 @@ "Operations": [ { "method": "POST", "path": "/Groups", "bulkId": "qwerty", "data": { "schemas": ["urn:scim:schemas:core:2.0:Group"], "displayName": "Group A", "members": [ { - "type": "group", + "type": "Group", "value": "bulkId:ytrewq" } ] } }, { "method": "POST", "path": "/Groups", "bulkId": "ytrewq", "data": { "schemas": ["urn:scim:schemas:core:2.0:Group"], "displayName": "Group B", "members": [ { - "type": "group", + "type": "Group", "value": "bulkId:qwerty" } ] } } ] } If the service provider resolved the above circular references the following is returned from a subsequent GET request. @@ -2037,30 +2099,25 @@ Host: example.com 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/scim+json -Location: https://example.com/v2/Bulk/yfCrVJhFIJagAHj8 { "schemas":["urn:scim:api:messages:2.0:Error"], - "Errors":[ - { - "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", - "code":"413" - } - ] + "status": "413", + "detail":"The size of the bulk operation exceeds the maxPayloadSize (1048576)." } 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 HTTP header "Content-Type" as specified in @@ -2086,58 +2145,59 @@ "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 For any SCIM operation where a resource representation is returned - (e.g. HTTP GET), the attributes normally returned are defined as the - minimum attribute set plus default attributes. The minimum set are - those attributes whose schema have "returned" set to "always". The - defaut attribute set are those attributes whose schema have - "returned" set to "default". + (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, each resource returned MUST contain the - minimal set of resource attributes and MUST contain no other - attributes or sub-attributes other than those explicitly - requested. The query parameter attributes value is a comma + 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, 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). . GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName Host: example.com - Accept: application/json + Accept: application/scim+json Authorization: Bearer h480djs93hd8 Giving the response 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/"a330bc54f0671c9" { "schemas":["urn:scim:schemas:core:2.0:User"], "id":"2819c223-7f76-453a-919d-413861904646", "userName":"bjensen", "meta":{ "resourceType": "User", "created":"2011-08-01T18:29:49.793Z", @@ -2149,70 +2209,72 @@ 3.8. 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: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:hr:schemas:user' is fully encoded as - 'urn:hr:schemas:user: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: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. + attribute 'age' defined in 'urn:scim:schemas:exampleCo:2.0:hr' is + fully encoded as 'urn: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: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 - A client MAY use a URL of the form "/Me" as an URL alias - for the User or other resource associated with the currently + 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 status 308 to the resource associated with the authenticated subject. The client MAY then repeat the request at the indicated location. o A service provider MAY process the SCIM request directly. In any response, the HTTP "Location" header MUST be the permanent location of the aliased resource associated with the authenticated subject. -3.10. HTTP Error Responses +3.10. HTTP Status and Error Response Handling - The SCIM Protocol uses the response status codes defined in HTTP - Section 6 [RFC7231] to indicate operation success or failure. In + 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:scim:api:messages:2.0:Error". The - following attributes are defined inclusion in a SCIM error response - using a JSON body: + following attributes are defined for a SCIM error response using a + JSON body: status - The HTTP status value (e.g. 400). REQUIRED + The HTTP status code (see Section 6 [RFC7231]). REQUIRED scimType A SCIM detailed error keyword. See Table 8. OPTIONAL detail A detailed, human readable message. OPTIONAL - Implementers SHOULD handle the identified errors as described below. + Implementers SHOULD handle the identified HTTP status codes as + described below. +--------------+---------------+------------------------------------+ | Status | 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 | @@ -2248,90 +2310,92 @@ | 413 REQUEST | POST | {"maxOperations": | | ENTITY TOO | | 1000,"maxPayload": 1048576} | | LARGE | | | | 500 INTERNAL | GET, POST, | An internal error. Implementers | | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | | | DELETE | debugging advice | | 501 NOT | GET, POST, | Service Provider does not support | | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | | | DELETE | | +--------------+---------------+------------------------------------+ - Table 7: Defined error cases + + 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), | | r | was invalid (does not comply | POST (Search - | | | with Figure 1) or the | Section 3.2.3), | | | specified attribute and | PATCH (Path Filter | | | filter comparison | - Section 3.3.2) | | | combination is not | | | | supported. | | | tooMany | The specified filter yields | GET(Section 3.2.2), | | | many more results than the | POST (Search - | | | server is willing calculate | Section 3.2.3) | | | or process. For example, a | | - | | filter such as "userName eq | | - | | "*"" would return all | | - | | entries with a "userName" | | - | | and MAY not be acceptable to | | - | | the service provider. | | + | | 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), | | | | PATCH (Section | | | | 3.3.2) | | mutability | The attempted modification | PUT (Section | | | is not compatible with the | 3.3.1), PATCH | | | target attributes mutability | (Section 3.3.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, | | | not conform to the request | Create - Section | | | schema. | 3.1, Bulk - Section | | | | 3.5), PUT (Section | | | | 3.3.1) | | invalidPath | The path attribute was | PATCH (Section | | | invalid or malformed (see | 3.3.2) | - | | Figure 4). | | + | | Figure 5). | | | noTarget | The specified "path" did not | PATCH (Section | | | yield an attribute or | 3.3.2) | | | attribute value that could | | | | be operated on. This occurs | | | | when the specified "path" | | | | value contains a filter that | | | | yields no match. | | | invalidValue | A required value was | GET (Section | | | missing, or the value | 3.2.2), POST | | | specified was not compatible | (Create - Section | - | | with the operation or | 3.1, Search - | + | | 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), | | | ma]). | PATCH (Section | | | | 3.3.2) | - | invalidVers | The specified API version is | GET (Section | - | | not supported (see Section | 3.2.2), POST (ALL), | - | | 3.11). | PUT (Section | + | 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), | | | | DELETE (Section | | | | 3.4) | +--------------+------------------------------+---------------------+ - Table 8: Table of Detail Error Keyword Values + 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. HTTP/1.1 404 NOT FOUND { @@ -2363,56 +2427,57 @@ 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 API supported by the service provider. + using the most recent SCIM protocol version supported by the service + provider. 3.12. Versioning Resources - 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. + 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: POST /Users HTTP/1.1 Host: example.com - Content-Type: application/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", "givenName":"Barbara" } } The server responds with an ETag in the response header and meta structure. 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", "meta":{ "resourceType":"User", "created":"2011-08-01T21:32:44.882Z", "lastModified":"2011-08-01T21:32:44.882Z", @@ -2428,21 +2493,21 @@ } 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 3.2 [RFC7233] header: GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName Host: example.com - Accept: application/json + Accept: application/scim+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 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., @@ -2551,58 +2616,109 @@ 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. -6.2. Request URI Information Leakage +6.2. Disclosure of Sensitive Information in URIs - 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 ). + 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 ). 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, + 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 { "schemas": ["urn:scim:api:messages:2.0:Error"], "Errors":[ { "description":"Query filter involving 'name' is restricted or confidential", "error":"confidential_restricted" } ] } -6.3. Case Insensitive Comparision & International Languages +6.3. HTTP Considerations + + As an HTTP based protocol, implementers of SCIM SHOULD consider all + security considerations of the HTTP/1.1 as enumerated in Section 1 + [RFC7230] + + As stated in Section 2.7.1 [RFC7230], a SCIM client MUST NOT generate + the userinfo (i.e. username and password) component (and its "@" + delimiter) when an "http" URI reference is generated with a message + as they are now disallowed in HTTP. + +6.4. Secure Storage and Handling of Sensitive Data + + An attacker may obtain valid username/password combinations from the + SCIM service provider's underlying database by gaining access to the + database and/or launching injection attacks. This could lead to + unintended disclosure of username/password combinations. The impact + may extend beyond the domain of the SCIM service provider if the data + was provisioned from other domains. + + Administrators should undertake industry best practices to protect + the storage of credentials and in particular SHOULD follow + recommendations outlines in Section 5.1.4.1 [RFC6819]. These + recommendations include but are not limited to: + + o Provide injection attack counter measures (e.g. by validating all + inputs and parameters), + + o No cleartext storage of credentials, + + o Store credentials using an encrypted protection mechanism, and + + o Avoid passwords and consider use of asymmetric cryptography based + credentials. + + As outlined in Section 5.1.4.2 [RFC6819], adminitrators SHOULD take + counter measures to prevent online attacks on secrets such as: + + o Utilize secure password policy in order to increase user password + entrophy to hinder online attacks and password guessing, + + o Mitigate attacks on passwords by locking respective accounts have + a number of failed attempts, + + o Use "tar pit" techniques by temporarily locking a respective + account and delaying responses for a certain duration. The + duration may increase with the number of failed attempts, and + + o Use authentication system that use CAPTCHA's and other factors for + authenticating users further reducing the possibility of automated + attacks. + +6.5. Case Insensitive Comparision & International Languages 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 @@ -2611,64 +2727,65 @@ Required parameters: none Optional parameters: none Encoding considerations: 8bit 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". + the SCIM protocol 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 + offered by web applications that 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. Additional information: Magic number(s): File extension(s): .scim .scm Macintosh file type code(s): Person & email address to contact for futher information: SCIM mailing list "" Intended usage: COMMON* (see restrictions) 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 + Applications intending to use SCIM protocol SHOULD use the application/scim+json media type. Author: Phil Hunt Change controller: IETF 7.2. SCIM API Message Schema Registry 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. + define SCIM protocol 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. +---------------------------------------+-----------+---------------+ | 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 | | @@ -2729,23 +2846,20 @@ [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax Specifications: ABNF", STD 68, RFC 5234, January 2008. [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security (TLS) Protocol Version 1.2", RFC 5246, August 2008. [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. [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. @@ -2771,20 +2885,27 @@ [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. + [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization + Framework: Bearer Token Usage", RFC 6750, October 2012. + + [RFC6819] Lodderstedt, T., McGloin, M., and P. Hunt, "OAuth 2.0 + Threat Model and Security Considerations", RFC 6819, + January 2013. + [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation (JSON) Patch", RFC 6902, April 2013. Appendix A. Contributors Samuel Erdtman (samuel@erdtman.se) Patrick Harding (pharding@pingidentity.com) Appendix B. Acknowledgments @@ -2880,20 +3001,44 @@ - Corrected version numbers in sec 3.11 API Versioning to v2 (from v1) - Clarified that no filter matches should return success totalResults=0 Draft 07 - PH - Revisions regarding support of detailed errors (Tickets 37, 46, 67) + Draft 08 - PH - Revisions as follows + + - Added clarification on schemas handling during PATCH operation + + - Revised example URN in Attribute Notation section to comply with + IANA namespace rules + + - Fixed typo in ABNF, attrExpr should be attrExp + + - Added more security considerations for HTTP and sensitive data + + - Revised authentication and authorization sections for greater + clarity. + + - Replaced the word "search" with "query" for consistency + + - Clarified sucessful resource creation response + + - Added clarification on primary value handling in PATCH + (consistent with draft 03) + + - Revised SCIM Bullk error handling to conform with draft 07 error + handling + Authors' Addresses Phil Hunt (editor) Oracle Corporation Email: phil.hunt@yahoo.com Kelly Grizzle SailPoint @@ -2891,24 +3036,25 @@ Phil Hunt (editor) Oracle Corporation Email: phil.hunt@yahoo.com Kelly Grizzle SailPoint Email: kelly.grizzle@sailpoint.com + Morteza Ansari Cisco Email: morteza.ansari@cisco.com Erik Wahlstroem Technology Nexus - Email: erik.wahlstrom@nexussafe.com + Email: erik.wahlstrom@nexusgroup.com Chuck Mortimore Salesforce.com Email: cmortimore@salesforce.com