Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7644

System for Cross-domain Identity Management: Protocol

Pages: 89
Proposed Standard
Errata
Part 3 of 4 – Pages 49 to 75
First   Prev   Next

Top   ToC   RFC7644 - Page 49   prevText

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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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   ToC   RFC7644 - 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 page on part 4)

Next Section