draft-ietf-scim-api-06.txt   draft-ietf-scim-api-07.txt 
Network Working Group P. Hunt, Ed. Network Working Group P. Hunt, Ed.
Internet-Draft Oracle Internet-Draft Oracle
Intended status: Standards Track K. Grizzle Intended status: Standards Track K. Grizzle
Expires: December 25, 2014 SailPoint Expires: January 4, 2015 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Technology Nexus Technology Nexus
C. Mortimore C. Mortimore
Salesforce Salesforce
June 23, 2014 July 3, 2014
System for Cross-Domain Identity Management:Protocol System for Cross-Domain Identity Management:Protocol
draft-ietf-scim-api-06 draft-ietf-scim-api-07
Abstract Abstract
The System for Cross-Domain Identity Management (SCIM) specification The System for Cross-Domain Identity Management (SCIM) specification
is designed to make managing user identity in cloud based is designed to make managing user identity in cloud based
applications and services easier. The specification suite seeks to applications and services easier. The specification suite seeks to
build upon experience with existing schemas and deployments, placing build upon experience with existing schemas and deployments, placing
specific emphasis on simplicity of development and integration, while specific emphasis on simplicity of development and integration, while
applying existing authentication, authorization, and privacy models. applying existing authentication, authorization, and privacy models.
It's intent is to reduce the cost and complexity of user management It's intent is to reduce the cost and complexity of user management
skipping to change at page 1, line 47 skipping to change at page 1, line 47
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/. Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on December 25, 2014. This Internet-Draft will expire on January 4, 2015.
Copyright Notice Copyright Notice
Copyright (c) 2014 IETF Trust and the persons identified as the Copyright (c) 2014 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
skipping to change at page 2, line 34 skipping to change at page 2, line 34
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3
2. Authentication and Authorization . . . . . . . . . . . . . . 4 2. Authentication and Authorization . . . . . . . . . . . . . . 4
3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 7 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 7
3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 9 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 9
3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 9 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 9
3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 9
3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 10 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 10
3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20
3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 22 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 23
3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 23 3.3.1. Replacing with PUT . . . . . . . . . . . . . . . . . 24
3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 25 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 26
3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 35 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 35
3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 35 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 50 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 50
3.7. Additional Operation Response Parameters . . . . . . . . 51 3.7. Additional Operation Response Parameters . . . . . . . . 51
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 52 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 52
3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 53 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 53
3.10. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 53 3.10. HTTP Error Responses . . . . . . . . . . . . . . . . . . 53
3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 55 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 57
3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 55 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 57
4. Preparation and Comparison of Internationalized Strings . . . 57 4. Preparation and Comparison of Internationalized Strings . . . 59
5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 57 5. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 59
5.1. Associating Clients to Tenants . . . . . . . . . . . . . 58 5.1. Associating Clients to Tenants . . . . . . . . . . . . . 60
5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 59 5.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 61
6. Security Considerations . . . . . . . . . . . . . . . . . . . 59 6. Security Considerations . . . . . . . . . . . . . . . . . . . 61
6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 59 6.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 61
6.2. Request URI Information Leakage . . . . . . . . . . . . . 59 6.2. Request URI Information Leakage . . . . . . . . . . . . . 61
6.3. Case Insensitive Comparision & International Languages . 60 6.3. Case Insensitive Comparision & International Languages . 62
6.4. Universal Identifiers . . . . . . . . . . . . . . . . . . 60 6.4. Universal Identifiers . . . . . . . . . . . . . . . . . . 62
7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 62
7.1. Media Type Registration . . . . . . . . . . . . . . . . . 60 7.1. Media Type Registration . . . . . . . . . . . . . . . . . 62
7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 61 7.2. SCIM API Message Schema Registry . . . . . . . . . . . . 63
8. References . . . . . . . . . . . . . . . . . . . . . . . . . 62 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 64
8.1. Normative References . . . . . . . . . . . . . . . . . . 62 8.1. Normative References . . . . . . . . . . . . . . . . . . 64
8.2. Informative References . . . . . . . . . . . . . . . . . 64 8.2. Informative References . . . . . . . . . . . . . . . . . 66
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 64 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 66
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 64 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 66
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 64 Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 66
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 66 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 68
1. Introduction and Overview 1. Introduction and Overview
The SCIM Protocol is an application-level, HTTP protocol for The SCIM Protocol is an application-level, HTTP protocol for
provisioning and managing identity data on the web. The protocol provisioning and managing identity data on the web. The protocol
supports creation, modification, retrieval, and discovery of core supports creation, modification, retrieval, and discovery of core
identity resources; i.e., Users and Groups, as well as custom identity resources; i.e., Users and Groups, as well as custom
resource extensions. resource extensions.
1.1. Intended Audience 1.1. Intended Audience
skipping to change at page 5, line 5 skipping to change at page 5, line 5
Service providers that support extended resources SHOULD define Service providers that support extended resources SHOULD define
resource endpoints using the established convention; pluralize the resource endpoints using the established convention; pluralize the
resource name defined in the extended schema by appending an 's'. resource name defined in the extended schema by appending an 's'.
Given there are cases where resource pluralization is ambiguous; Given there are cases where resource pluralization is ambiguous;
e.g., a resource named "Person" is legitimately "Persons" and e.g., a resource named "Person" is legitimately "Persons" and
"People" clients SHOULD discover resource endpoints via the "People" clients SHOULD discover resource endpoints via the
"/ResourceTypes" endpoint. "/ResourceTypes" endpoint.
GET Retrieves a complete or partial resource. GET Retrieves a complete or partial resource.
POST Create new resources, create a Search request, or bulk modify POST Create new resources, create a search request, or bulk modify
resources. resources.
PUT Modifies a resource by replacing existing attributes with a PUT Modifies a resource by replacing existing attributes with a
specified set of replacement attributes (replace). PUT SHOULD NOT specified set of replacement attributes (replace). PUT SHOULD NOT
be used to create new resources. be used to create new resources.
PATCH Modifies a resource with a set of client specified changes PATCH Modifies a resource with a set of client specified changes
(partial update). (partial update).
DELETE Deletes a resource. DELETE Deletes a resource.
skipping to change at page 10, line 45 skipping to change at page 10, line 45
"value":"bjensen@example.com", "value":"bjensen@example.com",
"type":"work" "type":"work"
} }
] ]
} }
3.2.2. List/Query Resources 3.2.2. List/Query Resources
SCIM defines a standard set of operations that can be used to filter, SCIM defines a standard set of operations that can be used to filter,
sort, and paginate response results. The operations are specified by sort, and paginate response results. The operations are specified by
adding query parameters to the resource's endpoint. Service adding query parameters to the resource's endpoint (see following
providers MAY support additional query parameters not specified here, sub-sections). Service providers MAY support additional query
and Providers SHOULD ignore any query parameters they don't parameters not specified here, and Providers SHOULD ignore any query
recognize. parameters they don't recognize.
List and query responses MUST be identified using the following URI: List and query responses MUST be identified using the following URI:
"urn:scim:api:messages:2.0:ListResponse". The following attributes "urn:scim:api:messages:2.0:ListResponse". The following attributes
are defined for list and query responses: are defined for list and query responses:
totalResults The total number of results returned by the list or totalResults The total number of results returned by the list or
query operation. This may not be equal to the number of elements query operation. This may not be equal to the number of elements
in the resources attribute of the list response if pagination in the resources attribute of the list response if pagination
(Section 3.2.2.4) is requested. REQUIRED. (Section 3.2.2.4) is requested. REQUIRED.
skipping to change at page 19, line 5 skipping to change at page 19, line 5
provider. Pagination is not session based hence clients SHOULD never provider. Pagination is not session based hence clients SHOULD never
assume repeatable results. For example, a request for a list of 10 assume repeatable results. For example, a request for a list of 10
resources beginning with a startIndex of 1 may return different resources beginning with a startIndex of 1 may return different
results when repeated as a resource in the original result could be results when repeated as a resource in the original result could be
deleted or new ones could be added in-between requests. Pagination deleted or new ones could be added in-between requests. Pagination
parameters and general behavior are derived from the OpenSearch parameters and general behavior are derived from the OpenSearch
Protocol [OpenSearch]. Protocol [OpenSearch].
The following table describes the URL pagination parameters. The following table describes the URL pagination parameters.
+------------+-------------------+----------------------------------+ +------------+----------------------------+-------------------------+
| Parameter | Description | Default | | Parameter | Description | Default |
+------------+-------------------+----------------------------------+ +------------+----------------------------+-------------------------+
| startIndex | The 1-based index | 1 | | startIndex | The 1-based index of the | 1 |
| | of the first | | | | first search result. A | |
| | search result. | | | | value less than 1 SHALL be | |
| count | Non-negative | None. When specified the service | | | interpreted as 1. | |
| | Integer. | provider MUST not return more | | count | Non-negative Integer. | None. When specified |
| | Specifies the | results than specified though | | | Specifies the desired | the service provider |
| | desired maximum | MAY return fewer results. If | | | maximum number of search | MUST not return more |
| | number of search | unspecified, the maximum number | | | results per page; e.g., | results than specified |
| | results per page; | of results is set by the service | | | 10. A negative value SHALL | though MAY return fewer |
| | e.g., 10. | provider. | | | be interpreted as "0". A | results. If |
+------------+-------------------+----------------------------------+ | | value of "0" indicates no | unspecified, the |
| | resource results are to be | maximum number of |
| | returned except for | results is set by the |
| | "totalResults". | service provider. |
+------------+----------------------------+-------------------------+
Table 5: Pagination Request parameters Table 5: Pagination Request parameters
The following table describes the query response pagination The following table describes the query response pagination
attributes specified by the service provider. attributes specified by the service provider.
+--------------+----------------------------------------------------+ +--------------+----------------------------------------------------+
| Element | Description | | Element | Description |
+--------------+----------------------------------------------------+ +--------------+----------------------------------------------------+
| itemsPerPage | Non-negative Integer. Specifies the number of | | itemsPerPage | Non-negative Integer. Specifies the number of |
skipping to change at page 20, line 21 skipping to change at page 20, line 21
"startIndex":1, "startIndex":1,
"schemas":["urn:scim:api:messages:2.0"], "schemas":["urn:scim:api:messages:2.0"],
"Resources":[{ "Resources":[{
... ...
}] }]
} }
Given the example above, to continue paging set the startIndex to 11 Given the example above, to continue paging set the startIndex to 11
and re-fetch; i.e., /Users?startIndex=11&count=10 and re-fetch; i.e., /Users?startIndex=11&count=10
3.2.2.5. Attributes
The following attributes control which attributes SHALL be returned
with a returned resource.
attributes A multi-valued list of strings indicating the names of
resource attributes to return in the response overriding the set
of attributes that would be returned by default. Attribute names
MUST be in standard attribute notation (Section 3.8) form. See
additional retrieval query parameters (Section 3.7). OPTIONAL.
excludedAttributes A multi-valued list of strings indicating the
names of resource attributes to be removed from the default set of
attributes to return. This parameter SHALL have no effect on
attributes whose schema "returned" setting is "always" see Server
Schema [I-D.ietf-scim-core-schema]. Attribute names MUST be in
standard attribute notation (Section 3.8) form. See additional
retrieval query parameters (Section 3.7). OPTIONAL.
3.2.3. Querying Resources Using HTTP POST 3.2.3. Querying Resources Using HTTP POST
Clients MAY execute queries without passing parameters on the URL by Clients MAY execute queries without passing parameters on the URL by
using the HTTP POST verb combined with the '/.search' path extension. using the HTTP POST verb combined with the '/.search' path extension.
The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL
be used to indicate the HTTP POST verb is intended to be a query be used to indicate the HTTP POST verb is intended to be a query
operation. operation.
To create a new search result set, a SCIM client sends an HTTP POST To create a new search result set, a SCIM client sends an HTTP POST
request to the desired SCIM resource endpoint (ending in '/.search'). request to the desired SCIM resource endpoint (ending in '/.search').
skipping to change at page 27, line 11 skipping to change at page 28, line 11
resulting resource becomes the target of the next operation. resulting resource becomes the target of the next operation.
Evaluation continues until all operations are successfully applied or Evaluation continues until all operations are successfully applied or
until an error condition is encountered. until an error condition is encountered.
A patch request, regardless of the number of operations, SHALL be A patch request, regardless of the number of operations, SHALL be
treated as atomic. If a single operation encounters an error treated as atomic. If a single operation encounters an error
condition, the original SCIM resource MUST be restored, and a failure condition, the original SCIM resource MUST be restored, and a failure
status SHALL be returned. status SHALL be returned.
If a request fails. the server SHALL return an HTTP response status If a request fails. the server SHALL return an HTTP response status
code of 400 and a JSON detail error response containing an "error" code and a JSON detail error response as defined in Section 3.10.
object that SHOULD be one of the following string values:
malformed_operation
The JSON operation elements could not successfully be parsed.
This may be due to an invalid or missing operation attribute, or
it could be due to a missing attribute required by a specific
operation.
mutability
The operation requested is not compatible with the mutability of
the selected attribute.
invalid_path
The path attribute was invalid or malformed.
no_target
The "path" specified did not return a target against which the
operation could be performed.
invalid_value
The operation "value" was missing or was not compatable with the
targeted attribute's type
The following is a non-normative example of an error response to a
patch request.
HTTP/1.1 400 Bad Request
Content-Type: application/scim+json;charset=UTF-8
Cache-Control: no-store
Pragma: no-cache
{
"schemas": ["urn:scim:api:messages:2.0:Error"],
"Errors":[
{
"error":"mutability",
"error_description":"Attribute 'id' is readOnly."
}
]
}
On successful completion, the server MUST return either a 200 OK On successful completion, the server MUST return either a 200 OK
response code and the entire resource (subject to the "attributes" response code and the entire resource (subject to the "attributes"
query parameter - see Additional Retrieval Query Parameters query parameter - see Additional Retrieval Query Parameters
(Section 3.7) ) within the response body, or a 204 No Content (Section 3.7) ) within the response body, or a 204 No Content
response code and the appropriate response headers for a successful response code and the appropriate response headers for a successful
patch request. The server MUST return a 200 OK if the "attributes" patch request. The server MUST return a 200 OK if the "attributes"
parameter is specified on the request. parameter is specified on the request.
3.3.2.1. Add Operation 3.3.2.1. Add Operation
skipping to change at page 53, line 28 skipping to change at page 53, line 28
o A service provider MAY choose to redirect the client using HTTP o A service provider MAY choose to redirect the client using HTTP
status 308 to the resource associated with the authenticated status 308 to the resource associated with the authenticated
subject. The client MAY then repeat the request at the indicated subject. The client MAY then repeat the request at the indicated
location. location.
o A service provider MAY process the SCIM request directly. In any o A service provider MAY process the SCIM request directly. In any
response, the HTTP "Location" header MUST be the permanent response, the HTTP "Location" header MUST be the permanent
location of the aliased resource associated with the authenticated location of the aliased resource associated with the authenticated
subject. subject.
3.10. HTTP Response Codes 3.10. HTTP Error Responses
The SCIM Protocol uses the response status codes defined in HTTP The SCIM Protocol uses the response status codes defined in HTTP
Section 6 [RFC7231] to indicate operation success or failure. In Section 6 [RFC7231] to indicate operation success or failure. In
addition to returning a HTTP response code implementers MUST return addition to returning a HTTP response code implementers MUST return
the errors in the body of the response in the client requested format the errors in the body of the response in the client requested format
containing the error response and, per the HTTP specification, human- containing the error response and, per the HTTP specification, human-
readable explanations. Error responses are identified using the readable explanations. Error responses are identified using the
following URI: 'urn:scim:api:messages:2.0:Error'. The following following "schema" URI: "urn:scim:api:messages:2.0:Error". The
multi-valued attribute is defined in addition to those attributes following attributes are defined inclusion in a SCIM error response
defined in SCIM Core Schema: using a JSON body:
Errors The list of errors encountered by the service provider. The status
value attribute is a complex type with the following sub- The HTTP status value (e.g. 400). REQUIRED
attributes.
description A human-readable explanation of the error. REQUIRED. scimType
A SCIM detailed error keyword. See Table 8. OPTIONAL
code A string indicating the HTTP response code. REQUIRED. detail
A detailed, human readable message. OPTIONAL
Implementers SHOULD handle the identified errors as described below. Implementers SHOULD handle the identified errors as described below.
+--------------+---------------+------------------------------------+ +--------------+---------------+------------------------------------+
| Code | Applicability | Suggested Explanation | | Status | Applicability | Suggested Explanation |
+--------------+---------------+------------------------------------+ +--------------+---------------+------------------------------------+
| 307 | GET, POST, | The client is directed to repeat | | 307 | GET, POST, | The client is directed to repeat |
| TEMPORARY | PUT, PATCH, | the same HTTP request at the | | TEMPORARY | PUT, PATCH, | the same HTTP request at the |
| REDIRECT | DELETE | location identified. The client | | REDIRECT | DELETE | location identified. The client |
| | | SHOULD NOT use the location | | | | SHOULD NOT use the location |
| | | provided in the response as a | | | | provided in the response as a |
| | | permanent reference to the | | | | permanent reference to the |
| | | resource and SHOULD continue to | | | | resource and SHOULD continue to |
| | | use the original request URI | | | | use the original request URI |
| | | [RFC7231]. | | | | [RFC7231]. |
skipping to change at page 54, line 30 skipping to change at page 54, line 31
| | | [I-D.reschke-http-status-308]. | | | | [I-D.reschke-http-status-308]. |
| 400 BAD | GET, POST, | Request is unparseable, | | 400 BAD | GET, POST, | Request is unparseable, |
| REQUEST | PUT, PATCH, | syntactically incorrect, or | | REQUEST | PUT, PATCH, | syntactically incorrect, or |
| | DELETE | violates schema | | | DELETE | violates schema |
| 401 | GET, POST, | Authorization failure | | 401 | GET, POST, | Authorization failure |
| UNAUTHORIZED | PUT, PATCH, | | | UNAUTHORIZED | PUT, PATCH, | |
| | DELETE | | | | DELETE | |
| 403 | GET, POST, | Server does not support requested | | 403 | GET, POST, | Server does not support requested |
| FORBIDDEN | PUT, PATCH, | operation | | FORBIDDEN | PUT, PATCH, | operation |
| | DELETE | | | | DELETE | |
| 404 NOT | GET, PUT, | Specified resource; e.g., User, | | 404 NOT | GET, PUT, | Specified resource (e.g., User) or |
| FOUND | PATCH, DELETE | does not exist | | FOUND | PATCH, DELETE | end-point, does not exist |
| 409 CONFLICT | POST, PUT, | The specified version number does | | 409 CONFLICT | POST, PUT, | The specified version number does |
| | PATCH, DELETE | not match the resource's latest | | | PATCH, DELETE | not match the resource's latest |
| | | version number or a service | | | | version number or a service |
| | | provider refused to create a new, | | | | provider refused to create a new, |
| | | duplicate resource | | | | duplicate resource |
| 412 | PUT, PATCH,D | Failed to update as resource {id} | | 412 | PUT, PATCH,D | Failed to update as resource {id} |
| PRECONDITION | ELETE | changed on the server last | | PRECONDITION | ELETE | changed on the server last |
| FAILED | | retrieved | | FAILED | | retrieved |
| 413 REQUEST | POST | {"maxOperations": | | 413 REQUEST | POST | {"maxOperations": |
| ENTITY TOO | | 1000,"maxPayload": 1048576} | | ENTITY TOO | | 1000,"maxPayload": 1048576} |
skipping to change at page 54, line 50 skipping to change at page 55, line 4
| 413 REQUEST | POST | {"maxOperations": | | 413 REQUEST | POST | {"maxOperations": |
| ENTITY TOO | | 1000,"maxPayload": 1048576} | | ENTITY TOO | | 1000,"maxPayload": 1048576} |
| LARGE | | | | LARGE | | |
| 500 INTERNAL | GET, POST, | An internal error. Implementers | | 500 INTERNAL | GET, POST, | An internal error. Implementers |
| SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive | | SERVER ERROR | PUT, PATCH, | SHOULD provide descriptive |
| | DELETE | debugging advice | | | DELETE | debugging advice |
| 501 NOT | GET, POST, | Service Provider does not support | | 501 NOT | GET, POST, | Service Provider does not support |
| IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH | | IMPLEMENTED | PUT, PATCH, | the request operation; e.g., PATCH |
| | DELETE | | | | DELETE | |
+--------------+---------------+------------------------------------+ +--------------+---------------+------------------------------------+
Table 7: Defined error cases Table 7: Defined error cases
For HTTP Status 400 (Bad Request) responses, the following detail
error types are defined:
+--------------+------------------------------+---------------------+
| scimType | Description | Applicability |
+--------------+------------------------------+---------------------+
| invalidFilte | The specified filter syntax | GET(Section 3.2.2), |
| r | was invalid (does not comply | POST (Search - |
| | with Figure 1) or the | Section 3.2.3), |
| | specified attribute and | PATCH (Path Filter |
| | filter comparison | - Section 3.3.2) |
| | combination is not | |
| | supported. | |
| tooMany | The specified filter yields | GET(Section 3.2.2), |
| | many more results than the | POST (Search - |
| | server is willing calculate | Section 3.2.3) |
| | or process. For example, a | |
| | filter such as "userName eq | |
| | "*"" would return all | |
| | entries with a "userName" | |
| | and MAY not be acceptable to | |
| | the service provider. | |
| uniqueness | One or more of attribute | POST (Create - |
| | values is already in use or | Section 3.1), PUT |
| | is reserved. | (Section 3.3.1), |
| | | PATCH (Section |
| | | 3.3.2) |
| mutability | The attempted modification | PUT (Section |
| | is not compatible with the | 3.3.1), PATCH |
| | target attributes mutability | (Section 3.3.2) |
| | or current state (e.g. | |
| | modification of an immutable | |
| | attribute with an existing | |
| | value). | |
| invalidSynta | The request body message | POST (Search - |
| x | structure was invalid or did | Section 3.2.2, |
| | not conform to the request | Create - Section |
| | schema. | 3.1, Bulk - Section |
| | | 3.5), PUT (Section |
| | | 3.3.1) |
| invalidPath | The path attribute was | PATCH (Section |
| | invalid or malformed (see | 3.3.2) |
| | Figure 4). | |
| noTarget | The specified "path" did not | PATCH (Section |
| | yield an attribute or | 3.3.2) |
| | attribute value that could | |
| | be operated on. This occurs | |
| | when the specified "path" | |
| | value contains a filter that | |
| | yields no match. | |
| invalidValue | A required value was | GET (Section |
| | missing, or the value | 3.2.2), POST |
| | specified was not compatible | (Create - Section |
| | with the operation or | 3.1, Search - |
| | attribute type (see Section | Section 3.2.2), PUT |
| | 2.1 [I-D.ietf-scim-core-sche | (Section 3.3.1), |
| | ma]). | PATCH (Section |
| | | 3.3.2) |
| invalidVers | The specified API version is | GET (Section |
| | not supported (see Section | 3.2.2), POST (ALL), |
| | 3.11). | PUT (Section |
| | | 3.3.1), PATCH |
| | | (Section 3.3.2), |
| | | DELETE (Section |
| | | 3.4) |
+--------------+------------------------------+---------------------+
Table 8: Table of Detail Error Keyword Values
Note that in the table above (Table 8), the applicability table
applies to the normal HTTP method but MAY apply within a SCIM Bulk
operation (via HTTP POST).
Error example in response to a non-existent GET request. Error example in response to a non-existent GET request.
HTTP/1.1 404 NOT FOUND HTTP/1.1 404 NOT FOUND
{ {
"schemas": ["urn:scim:api:messages:2.0:Error"], "schemas": ["urn:scim:api:messages:2.0:Error"],
"Errors":[ "detail":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
{ "status":"404
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", }
"code":"404"
} Error example in response to a PUT request.
]
} HTTP/1.1 400 BAD REQUEST
{
"schemas": ["urn:scim:api:messages:2.0:Error"],
"scimType":"mutability"
"detail":"Attribute 'id' is readOnly",
"status":"400"
}
[[Editor's note: while the detail error codes seem to have consensus,
there is a question about whether the error codes should be
extensible so that individual service providers may define site
specific codes. Should all scimTypes be URIs, so that scimTypes can
be registered via IANA? Should there be a separate field defined for
this purpose? Or, should custom signalling (for non-protocol/schema
errors, be out of scope?]]
3.11. API Versioning 3.11. API Versioning
The Base URL MAY be appended with a version identifier as a separate The Base URL MAY be appended with a version identifier as a separate
segment in the URL path. At this time of this specification, the segment in the URL path. At this time of this specification, the
identifier is 'v2'. If specified, the version identifier MUST appear identifier is 'v2'. If specified, the version identifier MUST appear
in the URL path immediately preceding the resource endpoint and in the URL path immediately preceding the resource endpoint and
conform to the following scheme: the character 'v' followed by the conform to the following scheme: the character 'v' followed by the
desired SCIM version number; e.g., a version 'v2' User request is desired SCIM version number; e.g., a version 'v2' User request is
specified as /v2/Users. When specified service providers MUST specified as /v2/Users. When specified service providers MUST
skipping to change at page 62, line 41 skipping to change at page 64, line 41
[I-D.ietf-precis-saslprepbis] [I-D.ietf-precis-saslprepbis]
Saint-Andre, P. and A. Melnikov, "Preparation and Saint-Andre, P. and A. Melnikov, "Preparation and
Comparison of Internationalized Strings Representing Comparison of Internationalized Strings Representing
Usernames and Passwords", draft-ietf-precis-saslprepbis-07 Usernames and Passwords", draft-ietf-precis-saslprepbis-07
(work in progress), March 2014. (work in progress), March 2014.
[I-D.ietf-scim-core-schema] [I-D.ietf-scim-core-schema]
Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore, Grizzle, K., Hunt, P., Wahlstroem, E., and C. Mortimore,
"System for Cross-Domain Identity Management: Core "System for Cross-Domain Identity Management: Core
Schema", draft-ietf-scim-core-schema-05 (work in Schema", draft-ietf-scim-core-schema-06 (work in
progress), May 2014. progress), June 2014.
[IANA.Language] [IANA.Language]
Internet Assigned Numbers Authority (IANA), "Language Internet Assigned Numbers Authority (IANA), "Language
Subtag Registry", 2005. Subtag Registry", 2005.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, March 1997. Requirement Levels", BCP 14, RFC 2119, March 1997.
[RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0", [RFC2246] Dierks, T. and C. Allen, "The TLS Protocol Version 1.0",
RFC 2246, January 1999. RFC 2246, January 1999.
skipping to change at page 66, line 36 skipping to change at page 68, line 36
76 - Clarified handling of PUT (& POST) with regards to mutability 76 - Clarified handling of PUT (& POST) with regards to mutability
and default values and default values
- Corrected version numbers in sec 3.11 API Versioning to v2 (from - Corrected version numbers in sec 3.11 API Versioning to v2 (from
v1) v1)
- Clarified that no filter matches should return success - Clarified that no filter matches should return success
totalResults=0 totalResults=0
Draft 07 - PH - Revisions regarding support of detailed errors
(Tickets 37, 46, 67)
Authors' Addresses Authors' Addresses
Phil Hunt (editor) Phil Hunt (editor)
Oracle Corporation Oracle Corporation
Email: phil.hunt@yahoo.com Email: phil.hunt@yahoo.com
Kelly Grizzle Kelly Grizzle
SailPoint SailPoint
 End of changes. 25 change blocks. 
113 lines changed or deleted 188 lines changed or added

This html diff was produced by rfcdiff 1.41. The latest version is available from http://tools.ietf.org/tools/rfcdiff/