tech-invite   World Map     

IETF     RFCs     Groups     SIP     ABNFs    |    3GPP     Specs     Glossaries     Architecture     IMS     UICC    |    search     info

RFC 7644

 
 
 

System for Cross-domain Identity Management: Protocol

Part 3 of 4, p. 49 to 75
Prev RFC Part       Next RFC Part

 


prevText      Top      Up      ToC       Page 49 
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.  Support for bulk requests can be discovered by
   querying the service provider configuration (see Section 4).  The
   body of a bulk operation contains a set of HTTP resource operations
   using one of the HTTP methods supported by the API, i.e., POST, PUT,
   PATCH, or DELETE.

   Bulk requests are identified using the following schema URI:
   "urn:ietf:params:scim:api:messages:2.0:BulkRequest".  Bulk responses
   are identified using the following URI:
   "urn:ietf:params:scim:api:messages:2.0:BulkResponse".  Bulk requests
   and bulk responses share many attributes.  Unless otherwise
   specified, each attribute below is present in both bulk requests and
   bulk responses.

   The following singular attribute is defined, in addition to the
   common attributes defined in [RFC7643].

   failOnErrors
      An integer specifying the number of errors that the service
      provider will accept before the operation is terminated and an
      error response is returned.  OPTIONAL in a request.  Not valid in
      a response.

   The following complex multi-valued attribute is defined, in addition
   to the common attributes defined in [RFC7643].

   Operations
      Defines operations within a bulk job.  Each operation corresponds
      to a single HTTP request against a resource endpoint.  REQUIRED.
      The Operations attribute has the following sub-attributes:

      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 MAY be used if the
         service provider supports entity-tags (ETags) (Section 2.3 of
         [RFC7232]) and "method" is "PUT", "PATCH", or "DELETE".

Top      Up      ToC       Page 50 
      path  The resource's relative path to the SCIM service provider's
         root.  If "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 SCIM POST,
         PUT, or PATCH operation.  REQUIRED in a request when "method"
         is "POST", "PUT", or "PATCH".

      location  The resource endpoint URL.  REQUIRED in a response,
         except in the event of a POST failure.

      response  The HTTP response body for 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 for the requested operation.
         When indicating an error, the "response" attribute MUST contain
         the detail error response as per Section 3.12.

   If a bulk job is processed successfully, 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 bulkId
   attribute MAY be specified when creating new resources.  The "bulkId"
   is defined by the client as a surrogate identifier in a POST
   operation (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 the sequence of
   operations received (e.g., to improve processing performance).  When
   doing so, the service provider MUST ensure that the client's intent
   is preserved and the same stateful result is achieved as for

Top      Up      ToC       Page 51 
   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.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 HTTP 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
   Authorization: Bearer h480djs93hd8
   Content-Length: ...

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
     "Operations": [
       {
         "method": "POST",
         "path": "/Groups",
         "bulkId": "qwerty",
         "data": {
           "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
           "displayName": "Group A",
           "members": [
             {
               "type": "Group",
               "value": "bulkId:ytrewq"
             }
           ]
         }
       },

Top      Up      ToC       Page 52 
       {
         "method": "POST",
         "path": "/Groups",
         "bulkId": "ytrewq",
         "data": {
           "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
           "displayName": "Group B",
           "members": [
             {
               "type": "Group",
               "value": "bulkId:qwerty"
             }
           ]
         }
       }
     ]
   }

   If the service provider resolved the above circular references, the
   following is returned from a subsequent GET request.

   GET /v2/Groups?filter=displayName sw 'Group'
   Host: example.com
   Accept: application/scim+json
   Authorization: Bearer h480djs93hd8

   HTTP/1.1 200 OK
   Content-Type: application/scim+json

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
     "totalResults": 2,
     "Resources": [
       {
         "id": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
         "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
         "displayName": "Group A",
         "meta": {
           "resourceType": "Group",
           "created": "2011-08-01T18:29:49.793Z",
           "lastModified": "2011-08-01T18:29:51.135Z",
           "location":
   "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
           "version": "W\/\"mvwNGaxB5SDq074p\""
         },

Top      Up      ToC       Page 53 
         "members": [
           {
             "value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
             "$ref":
   "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
             "type": "Group"
           }
         ]
       },
       {
         "id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
         "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
         "displayName": "Group B",
         "meta": {
           "resourceType": "Group",
           "created": "2011-08-01T18:29:50.873Z",
           "lastModified": "2011-08-01T18:29:50.873Z",
           "location":
   "https://example.com/v2/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
           "version": "W\/\"wGB85s2QJMjiNnuI\""
         },
         "members": [
           {
             "value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
             "$ref":
   "https://example.com/v2/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
             "type": "Group"
           }
         ]
       }
     ]
   }

3.7.2.  "bulkId" Temporary Identifiers

   A SCIM client can, within one bulk operation, create a new "User",
   create 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 prepended with the
   literal "bulkId:"; e.g., if the bulkId is 'qwerty', the value is
   "bulkId:qwerty".  The service provider MUST replace the string
   "bulkId:qwerty" with the permanent resource id once created.

   To create multiple distinct requests, each with their own "bulkId",
   the SCIM client specifies different "bulkId" values for each separate
   request.

Top      Up      ToC       Page 54 
   The following example creates a User with the "userName" 'Alice' and
   a "Group" with "displayName", with a value of "Tour Guides" with
   Alice as a member.  Notice that each operation has its own "bulkId"
   value.  However, the second operation (whose "bulkId" is "ytrewq")
   refers to the "bulkId" of "qwerty" in order to add Alice to the new
   'Tour Guides' group.

   POST /v2/Bulk
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8
   Content-Length: ...

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
     "Operations": [
       {
         "method": "POST",
         "path": "/Users",
         "bulkId": "qwerty",
         "data": {
           "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
           "userName": "Alice"
         }
       },
       {
         "method": "POST",
         "path": "/Groups",
         "bulkId": "ytrewq",
         "data": {
           "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
           "displayName": "Tour Guides",
           "members": [
             {
               "type": "User",
               "value": "bulkId:qwerty"
             }
           ]
         }
       }
     ]
   }

Top      Up      ToC       Page 55 
   The service provider returns the following response:

   HTTP/1.1 200 OK
   Content-Type: application/scim+json

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
     "Operations": [
       {
         "location":
   "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
         "method": "POST",
         "bulkId": "qwerty",
         "version": "W\/\"4weymrEsh5O6cAEK\"",
         "status": {
           "code": "201"
         }
       },
       {
         "location":
   "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
         "method": "POST",
         "bulkId": "ytrewq",
         "version": "W\/\"lha5bbazU3fNvfe5\"",
         "status": {
           "code": "201"
         }
       }
     ]
   }

   In the above example, the "Alice" User resource has an "id" of
   "92b725cd-9465-4e7d-8c16-01f8e146b87a" and the 'Tour Guides' Group
   has an "id" of "e9e30dba-f08f-4109-8486-d5c6a331660a".

Top      Up      ToC       Page 56 
   A subsequent GET request for the 'Tour Guides' Group (with an "id" of
   "e9e30dba-f08f-4109-8486-d5c6a331660a") returns the following, with
   Alice's "id" as the value for the member in the Group 'Tour Guides':

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location:
    https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a
   ETag: W/"lha5bbazU3fNvfe5"

   {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:Group"],
     "id": "e9e30dba-f08f-4109-8486-d5c6a331660a",
     "displayName": "Tour Guides",
     "meta": {
       "resourceType": "Group",
       "created": "2011-08-01T18:29:49.793Z",
       "lastModified": "2011-08-01T20:31:02.315Z",
       "location":
   "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
       "version": "W\/\"lha5bbazU3fNvfe5\""
     },
     "members": [
       {
         "value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
         "$ref":
   "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
         "type": "User"
       }
     ]
   }

Top      Up      ToC       Page 57 
   Extensions that include references to other resources MUST be handled
   in the same way by the service provider.  The following example uses
   the bulkId attribute within the enterprise extension managerId
   attribute.

 POST /v2/Bulk
 Host: example.com
 Accept: application/scim+json
 Content-Type: application/scim+json
 Authorization: Bearer h480djs93hd8
 Content-Length: ...

 {
   "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
   "Operations": [
     {
       "method": "POST",
       "path": "/Users",
       "bulkId": "qwerty",
       "data": {
         "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
         "userName": "Alice"
       }
     },
     {
       "method": "POST",
       "path": "/Users",
       "bulkId": "ytrewq",
       "data": {
         "schemas": [
           "urn:ietf:params:scim:schemas:core:2.0:User",
           "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User"
         ],
         "userName": "Bob",
         "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User": {
           "employeeNumber": "11250",
           "manager": {
             "value": "bulkId:qwerty"
           }
         }
       }
     }
   ]
 }

Top      Up      ToC       Page 58 
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 except for
   failed POST operations (which have no location).  The status
   attribute includes information about the success or failure of one
   operation within the bulk job.  The status attribute 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": "201"

   The following is an example of a status in a failed operation.

  "status": "400",
  "response":{
       "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
       "scimType":"invalidSyntax"
       "detail":
  "Request is unparsable, syntactically incorrect, or violates schema.",
       "status":"400"
   }

Top      Up      ToC       Page 59 
   The following example shows how to add, update, and remove a user.
   The "failOnErrors" attribute is set to '1', indicating that the
   service provider will stop processing and return results after one
   error.  The POST operation's bulkId value is set to 'qwerty',
   enabling the client to match the new User with the returned
   resource "id" of
   "92b725cd-9465-4e7d-8c16-01f8e146b87a".

   POST /v2/Bulk
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8
   Content-Length: ...

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkRequest"],
     "failOnErrors":1,
     "Operations":[
       {
         "method":"POST",
         "path":"/Users",
         "bulkId":"qwerty",
         "data":{
           "schemas": ["urn:ietf:params:scim:api:messages:2.0:User"],
           "userName":"Alice"
         }
       },
       {
         "method":"PUT",
         "path":"/Users/b7c14771-226c-4d05-8860-134711653041",
         "version":"W\/\"3694e05e9dff591\"",
         "data":{
           "schemas": ["urn:ietf:params:scim:schemas:core:2.0:User"],
           "id":"b7c14771-226c-4d05-8860-134711653041",
           "userName":"Bob"
         }
       },

Top      Up      ToC       Page 60 
       {
         "method": "PATCH",
         "path": "/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
         "version": "W/\"edac3253e2c0ef2\"",
         "data": {[
           {
               "op": "remove",
               "path": "nickName"
           },
           {
               "op": "add",
               "path": "userName",
               "value": "Dave"
           }
         ]}
       },
       {
         "method":"DELETE",
         "path":"/Users/e9025315-6bea-44e1-899c-1e07454e468b",
         "version":"W\/\"0ee8add0a938e1a\""
       }
     ]
   }

   The service provider returns the following response:

  HTTP/1.1 200 OK
  Content-Type: application/scim+json

  {
      "schemas": ["urn:ietf:params:scim:api:messages:2.0:BulkResponse"],
      "Operations": [
          {
              "location":
  "https://example.com/v2/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
              "method": "POST",
              "bulkId": "qwerty",
              "version": "W\/\"oY4m4wn58tkVjJxK\"",
              "status": "201"
          },
          {
              "location":
  "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
              "method": "PUT",
              "version": "W\/\"huJj29dMNgu3WXPD\"",
              "status": "200"
          },

Top      Up      ToC       Page 61 
          {
              "location":
  "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
              "method": "PATCH",
              "version": "W\/\"huJj29dMNgu3WXPD\"",
              "status": "200"
          },
          {
              "location":
  "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
              "method": "DELETE",
              "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:ietf:params:scim:api:messages:2.0:BulkResponse"],
    "Operations": [
      {
        "method": "POST",
        "bulkId": "qwerty",
        "status": "400",
        "response":{
           "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
           "scimType":"invalidSyntax"
           "detail":
  "Request is unparsable, syntactically incorrect, or violates schema.",
           "status":"400"
        }
      }
    ]
  }

Top      Up      ToC       Page 62 
   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:ietf:params:scim:api:messages:2.0:BulkResponse"],
    "Operations": [
      {
        "method": "POST",
        "bulkId": "qwerty",
        "status": "400",
        "response":{
           "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
           "scimType":"invalidSyntax"
           "detail":
  "Request is unparsable, syntactically incorrect, or violates schema.",
           "status":"400"
        }
      },
      {
        "location":
  "https://example.com/v2/Users/b7c14771-226c-4d05-8860-134711653041",
        "method": "PUT",
        "status": "412",
        "response":{
            "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
            "detail":
                  "Failed to update.  Resource changed on the server.",
            "status":"412"
        }
      },
      {
        "location":
  "https://example.com/v2/Users/5d8d29d3-342c-4b5f-8683-a3cb6763ffcc",
        "method": "PATCH",
        "status": "412",
        "response":{
            "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
            "detail":
                  "Failed to update.  Resource changed on the server.",
            "status":"412"
        }
      },

Top      Up      ToC       Page 63 
      {
        "location":
  "https://example.com/v2/Users/e9025315-6bea-44e1-899c-1e07454e468b",
        "method": "DELETE",
        "status": "404",
        "response":{
            "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
            "detail":"Resource does not exist.",
            "status":"404"
        }
      }
    ]
  }

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 Sections 5 and 8.5 of [RFC7643]).  If either limit is
   exceeded, the service provider MUST return HTTP response code 413
   (Payload Too Large).  The returned response MUST specify the limit
   exceeded in the body of the error response.

   In the following example, the client sent a request exceeding the
   service provider's maximum payload size of 1 megabyte:

   POST /v2/Bulk
   Host: example.com
   Accept: application/scim+json
   Content-Type: application/scim+json
   Authorization: Bearer h480djs93hd8
   Content-Length: 4294967296

   ...

   The server sends the following error in response to the oversized
   request:

  HTTP/1.1 413 Payload 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)."
  }

Top      Up      ToC       Page 64 
3.8.  Data Input/Output Formats

   Servers MUST accept requests and be able to return JSON-structured
   responses using UTF-8 encoding [RFC3629].  UTF-8 SHALL be the default
   encoding format.  Other media types MAY be supported by service
   providers but are beyond the scope of this specification.

   Clients using other encodings MUST specify the format in which the
   data is submitted via an HTTP "Content-Type" header as specified in
   Section 3.1.1.5 of [RFC7231] and MAY specify the desired response
   data format via an HTTP "Accept" header (Section 5.3.2 of [RFC7231]),
   e.g., "Accept: application/scim+json", or via URI suffix:

   GET /Users/2819c223-7f76-453a-919d-413861904646.scim
   Host: example.com

   Service providers MUST support the "Accept" header
   "Accept: application/scim+json" and SHOULD support the header
   "Accept: application/json", both of which specify JSON documents
   conforming to [RFC7159].  The format defaults to
   "application/scim+json" if no format is specified.

   Singular attributes are encoded as string name-value pairs in
   JSON, e.g.,

   "attribute": "value"

   Multi-valued attributes in JSON are encoded as arrays, e.g.,

   "attributes": [ "value1", "value2" ]

   Elements with nested elements are represented as objects in
   JSON, e.g.,

   "attribute": { "subattribute1": "value1", "subattribute2": "value2" }

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 attribute set.  The minimum set is
   composed of those attributes that have their "returned"
   characteristic set to "always" (see Section 2.2 of [RFC7643]).  The
   default attribute set is composed of those attributes that have the
   "returned" characteristic set to "default".

Top      Up      ToC       Page 65 
   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
   "excludedAttributes", 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.10) form (e.g., userName, name,
           emails).

   excludedAttributes  When specified, each resource returned MUST
           contain the minimum set of resource attributes.
           Additionally, the default set of attributes minus those
           attributes listed in "excludedAttributes" is returned.  The
           query parameter attributes value is a comma-separated list of
           resource attribute names in standard attribute 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

   The following response is returned:

   HTTP/1.1 200 OK
   Content-Type: application/scim+json
   Location:
    https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
   ETag: W/"a330bc54f0671c9"

   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id":"2819c223-7f76-453a-919d-413861904646",
     "userName":"bjensen"
   }

Top      Up      ToC       Page 66 
3.10.  Attribute Notation

   All operations share a common scheme for referencing simple and
   complex attributes.  In general, attributes are uniquely identified
   by prefixing the attribute name with its schema URN separated by a
   colon (":") 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 but SHOULD fully qualify
   extended attributes with the associated schema extension URN to avoid
   naming conflicts.  For example, the attribute 'age' defined in
   "urn:ietf:params:scim:schemas:exampleCo:2.0:hr" is uniquely
   identified as "urn:ietf:params:scim:schemas:exampleCo:2.0:hr:age".
   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.11.  "/Me" Authenticated Subject Alias

   A client MAY use a URL of the form "<base-URI>/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 three ways:

   o  A service provider that does NOT support this feature SHOULD
      respond with HTTP status code 501 (Not Implemented).

   o  A service provider MAY choose to redirect the client using HTTP
      status code 308 (Permanent Redirect) to the resource associated
      with the authenticated subject.  The client MAY then repeat the
      request at the indicated location.

   o  A service provider MAY process the SCIM request directly.  In any
      response, the HTTP "Location" header MUST be the permanent
      location of the aliased resource associated with the authenticated
      subject.

   When using the SCIM Create Resource command (HTTP POST) with the
   "/Me" alias, the desired resourceType being created is at the
   discretion of the service provider, based on the authenticated
   subject (if not anonymous) making the request and any request body
   attributes (e.g., "schemas").  See Section 7.6 for information on
   security considerations related to this operation.

Top      Up      ToC       Page 67 
3.12.  HTTP Status and Error Response Handling

   The SCIM protocol uses the HTTP response status codes defined in
   Section 6 of [RFC7231] to indicate operation success or failure.  In
   addition to returning an HTTP response code, implementers MUST return
   the errors in the body of the response in a JSON format, using the
   attributes described below.  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:

   status
      The HTTP status code (see Section 6 of [RFC7231]) expressed as a
      JSON string.  REQUIRED.

   scimType
      A SCIM detail error keyword.  See Table 9.  OPTIONAL.

   detail
      A detailed human-readable message.  OPTIONAL.

   Implementers SHOULD handle the identified HTTP status codes as
   described below.

   +----------------+---------------+----------------------------------+
   | Status         | Applicability | Suggested Explanation            |
   +----------------+---------------+----------------------------------+
   | 307 (Temporary | GET, POST,    | The client is directed to repeat |
   | Redirect)      | PUT, PATCH,   | the same HTTP request at the     |
   |                | DELETE        | location identified.  The client |
   |                |               | SHOULD NOT use the location      |
   |                |               | provided in the response as a    |
   |                |               | permanent reference to the       |
   |                |               | resource and SHOULD continue to  |
   |                |               | use the original request URI     |
   |                |               | [RFC7231].                       |
   |                |               |                                  |
   | 308 (Permanent | GET, POST,    | The client is directed to repeat |
   | Redirect)      | PUT, PATCH,   | the same HTTP request at the     |
   |                | DELETE        | location identified.  The client |
   |                |               | SHOULD use the location provided |
   |                |               | in the response as the permanent |
   |                |               | reference to the resource        |
   |                |               | [RFC7538].                       |
   |                |               |                                  |
   | 400 (Bad       | GET, POST,    | Request is unparsable,           |
   | Request)       | PUT, PATCH,   | syntactically incorrect, or      |
   |                | DELETE        | violates schema.                 |

Top      Up      ToC       Page 68 
   |                |               |                                  |
   | 401            | GET, POST,    | Authorization failure.  The      |
   | (Unauthorized) | PUT, PATCH,   | authorization header is invalid  |
   |                | DELETE        | or missing.                      |
   |                |               |                                  |
   | 403            | GET, POST,    | Operation is not permitted based |
   | (Forbidden)    | PUT, PATCH,   | on the supplied authorization.   |
   |                | DELETE        |                                  |
   |                |               |                                  |
   | 404 (Not       | GET, POST,    | Specified resource (e.g., User)  |
   | Found)         | PUT, PATCH,   | or endpoint does not exist.      |
   |                | DELETE        |                                  |
   |                |               |                                  |
   | 409 (Conflict) | POST, PUT,    | The specified version number     |
   |                | PATCH, DELETE | does not match the resource's    |
   |                |               | latest version number, or a      |
   |                |               | service provider refused to      |
   |                |               | create a new, duplicate          |
   |                |               | resource.                        |
   |                |               |                                  |
   | 412            | PUT, PATCH,   | Failed to update.  Resource has  |
   | (Precondition  | DELETE        | changed on the server.           |
   | Failed)        |               |                                  |
   |                |               |                                  |
   | 413 (Payload   | POST          | {"maxOperations":                |
   | Too Large)     |               | 1000,"maxPayloadSize": 1048576}  |
   |                |               |                                  |
   | 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        |
   | Implemented)   | PUT, PATCH,   | support the request operation,   |
   |                | DELETE        | e.g., PATCH.                     |
   +----------------+---------------+----------------------------------+

                   Table 8: SCIM HTTP Status Code Usage

Top      Up      ToC       Page 69 
   For HTTP status code 400 (Bad Request) responses, the following
   detail error types are defined:

   +---------------+--------------------------------+------------------+
   | scimType      | Description                    | Applicability    |
   +---------------+--------------------------------+------------------+
   | invalidFilter | The specified filter syntax    | GET (Section     |
   |               | was invalid (does not comply   | 3.4.2), POST     |
   |               | with Figure 1), or the         | (Search -        |
   |               | specified attribute and filter | Section 3.4.3),  |
   |               | comparison combination is not  | PATCH (Path      |
   |               | supported.                     | Filter - Section |
   |               |                                | 3.5.2)           |
   |               |                                |                  |
   | tooMany       | The specified filter yields    | GET (Section     |
   |               | many more results than the     | 3.4.2), POST     |
   |               | server is willing to calculate | (Search -        |
   |               | or process.  For example, a    | Section 3.4.3)   |
   |               | 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 the attribute   | POST (Create -   |
   |               | values are already in use or   | Section 3.3),    |
   |               | are reserved.                  | PUT (Section     |
   |               |                                | 3.5.1), PATCH    |
   |               |                                | (Section 3.5.2)  |
   |               |                                |                  |
   | mutability    | The attempted modification is  | PUT (Section     |
   |               | not compatible with the target | 3.5.1), PATCH    |
   |               | attribute's mutability or      | (Section 3.5.2)  |
   |               | current state (e.g.,           |                  |
   |               | modification of an "immutable" |                  |
   |               | attribute with an existing     |                  |
   |               | value).                        |                  |
   |               |                                |                  |
   | invalidSyntax | The request body message       | POST (Search -   |
   |               | structure was invalid or did   | Section 3.4.3,   |
   |               | not conform to the request     | Create - Section |
   |               | schema.                        | 3.3, Bulk -      |
   |               |                                | Section 3.7),    |
   |               |                                | PUT (Section     |
   |               |                                | 3.5.1)           |
   |               |                                |                  |

Top      Up      ToC       Page 70 
   | invalidPath   | The "path" attribute was       | PATCH (Section   |
   |               | invalid or malformed (see      | 3.5.2)           |
   |               | Figure 7).                     |                  |
   |               |                                |                  |
   | noTarget      | The specified "path" did not   | PATCH (Section   |
   |               | 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 missing,  | GET (Section     |
   |               | or the value specified was not | 3.4.2), POST     |
   |               | compatible with the operation  | (Create -        |
   |               | or attribute type (see Section | Section 3.3,     |
   |               | 2.2 of [RFC7643]), or resource | Query - Section  |
   |               | schema (see Section 4 of       | 3.4.3), PUT      |
   |               | [RFC7643]).                    | (Section 3.5.1), |
   |               |                                | PATCH (Section   |
   |               |                                | 3.5.2)           |
   |               |                                |                  |
   | invalidVers   | The specified SCIM protocol    | GET (Section     |
   |               | version is not supported (see  | 3.4.2), POST     |
   |               | Section 3.13).                 | (ALL), PUT       |
   |               |                                | (Section 3.5.1), |
   |               |                                | PATCH (Section   |
   |               |                                | 3.5.2), DELETE   |
   |               |                                | (Section 3.6)    |
   |               |                                |                  |
   | sensitive     | The specified request cannot   | GET (Section     |
   |               | be completed, due to the       | 3.4.2)           |
   |               | passing of sensitive (e.g.,    |                  |
   |               | personal) information in a     |                  |
   |               | request URI.  For example,     |                  |
   |               | personal information SHALL NOT |                  |
   |               | be transmitted over request    |                  |
   |               | URIs.  See Section 7.5.2.      |                  |
   +---------------+--------------------------------+------------------+

                 Table 9: SCIM Detail Error Keyword Values

   Note that in Table 9 above, the information in the Applicability
   column applies to the normal HTTP method but MAY apply within a SCIM
   bulk operation (via HTTP POST).

Top      Up      ToC       Page 71 
   Example of an error in response to a non-existent GET request:

   HTTP/1.1 404 Not Found

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
     "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
     "status": "404"
   }

   Example of an error in response to a PUT request:

   HTTP/1.1 400 Bad Request

   {
     "schemas": ["urn:ietf:params:scim:api:messages:2.0:Error"],
     "scimType":"mutability"
     "detail":"Attribute 'id' is readOnly",
     "status": "400"
   }

3.13.  SCIM Protocol Versioning

   The Base URL MAY be appended with a version identifier as a separate
   segment in the URL path.  At the time of this writing, 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.14.  Versioning Resources

   The SCIM protocol supports resource versioning via standard HTTP
   ETags (Section 2.3 of [RFC7232]).  Service providers MAY support weak
   ETags as the preferred mechanism for performing conditional
   retrievals and ensuring that clients do not inadvertently overwrite
   each other's 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.

Top      Up      ToC       Page 72 
   Example create request:

   POST /Users  HTTP/1.1
   Host: example.com
   Content-Type:  application/scim+json
   Authorization: Bearer h480djs93hd8
   Content-Length: ...

   {
     "schemas":["urn:ietf:params: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/scim+json
   Location:
    https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646
   ETag: W/"e180ee84f0671b1"

   {
     "schemas":["urn:ietf:params: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",
       "location":
   "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
       "version":"W\/\"e180ee84f0671b1\""
     },
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "userName":"bjensen"
   }

Top      Up      ToC       Page 73 
   With the returned ETag, clients MAY choose to retrieve the resource
   only if the resource has been modified.

   An example of conditional retrieval, using the If-None-Match header
   (Section 3.2 of [RFC7232]):

  GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName
  Host: example.com
  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 provider supports versioning of resources, the client
   MAY supply an If-Match header (Section 3.1 of [RFC7232]) for PUT and
   PATCH operations to ensure that the requested operation succeeds only
   if the supplied ETag matches the latest service provider resource,
   e.g., If-Match: W/"e180ee84f0671b1".

4.  Service Provider Configuration Endpoints

   SCIM defines three endpoints to facilitate discovery of SCIM service
   provider features and schema that MAY be retrieved using HTTP GET:

   /ServiceProviderConfig
      An HTTP GET to this endpoint will return a JSON structure that
      describes the SCIM specification features available on a service
      provider.  This endpoint SHALL return responses with a JSON object
      using a "schemas" attribute of
      "urn:ietf:params:scim:schemas:core:2.0:ServiceProviderConfig".
      The attributes returned in the JSON object are defined in
      Section 5 of [RFC7643].  An example representation of SCIM service
      provider configuration may be found in Section 8.5 of [RFC7643].

Top      Up      ToC       Page 74 
   /Schemas
      An HTTP GET to this endpoint is used to retrieve information about
      resource schemas supported by a SCIM service provider.  An HTTP
      GET to the endpoint "/Schemas" SHALL return all supported schemas
      in ListResponse format (see Figure 3).  Individual schema
      definitions can be returned by appending the schema URI to the
      /Schemas endpoint.  For example:

            /Schemas/urn:ietf:params:scim:schemas:core:2.0:User

      The contents of each schema returned are described in Section 7 of
      [RFC7643].  An example representation of SCIM schemas may be found
      in Section 8.7 of [RFC7643].

   /ResourceTypes
      An HTTP GET to this endpoint is used to discover the types of
      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 of [RFC7643], and an example representation can be
      found in Section 8.6 of [RFC7643].

   In cases where a request is for a specific "ResourceType" or
   "Schema", the single JSON object is returned in the same way that a
   single User or Group is retrieved, as per Section 3.4.1.  When
   returning multiple ResourceTypes or Schemas, the message form
   described by the "urn:ietf:params:scim:api:messages:2.0:ListResponse"
   (ListResponse) form SHALL be used as shown in Figure 3 and in
   Figure 9 below.  Query parameters described in Section 3.4.2, such as
   filtering, sorting, and pagination, SHALL be ignored.  If a "filter"
   is provided, the service provider SHOULD respond with HTTP status
   code 403 (Forbidden) to ensure that clients cannot incorrectly assume
   that any matching conditions specified in a filter are true.

Top      Up      ToC       Page 75 
   The following is a non-normative example of an HTTP GET to the
   /ResourceTypes endpoint:

  {
    "totalResults":2,
    "itemsPerPage":10,
    "startIndex":1,
    "schemas":["urn:ietf:params:scim:api:messages:2.0:ListResponse"],
    "Resources":[{
      "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
      "id":"User",
      "name":"User",
      "endpoint": "/Users",
      "description": "User Account",
      "schema": "urn:ietf:params:scim:schemas:core:2.0:User",
      "schemaExtensions": [{
        "schema":
          "urn:ietf:params:scim:schemas:extension:enterprise:2.0:User",
        "required": true
      }],
      "meta": {
        "location":"https://example.com/v2/ResourceTypes/User",
        "resourceType": "ResourceType"
      }
    },
   {
     "schemas": ["urn:ietf:params:scim:schemas:core:2.0:ResourceType"],
     "id":"Group",
     "name":"Group",
     "endpoint": "/Groups",
     "description": "Group",
     "schema": "urn:ietf:params:scim:schemas:core:2.0:Group",
     "meta": {
       "location":"https://example.com/v2/ResourceTypes/Group",
       "resourceType": "ResourceType"
     }
   }]
  }

            Figure 9: Example Resource Type JSON Representation


Next RFC Part