draft-ietf-scim-api-04.txt   draft-ietf-scim-api-05.txt 
Network Working Group K. Grizzle Network Working Group P. Hunt, Ed.
Internet-Draft SailPoint Internet-Draft Oracle
Intended status: Standards Track P. Hunt, Ed. Intended status: Standards Track K. Grizzle
Expires: October 25, 2014 Oracle Expires: November 14, 2014 SailPoint
M. Ansari M. Ansari
Cisco Cisco
E. Wahlstroem E. Wahlstroem
Technology Nexus Technology Nexus
C. Mortimore C. Mortimore
Salesforce Salesforce
April 23, 2014 May 13, 2014
System for Cross-Domain Identity Management:Protocol System for Cross-Domain Identity Management:Protocol
draft-ietf-scim-api-04 draft-ietf-scim-api-05
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 October 25, 2014. This Internet-Draft will expire on November 14, 2014.
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 26 skipping to change at page 2, line 26
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License. described in the Simplified BSD License.
Table of Contents Table of Contents
1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3
1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3 1.2. Notational Conventions . . . . . . . . . . . . . . . . . 3
1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3
2. Authentication and Authorization . . . . . . . . . . . . . . 3 2. Authentication and Authorization . . . . . . . . . . . . . . 4
3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 6 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . 7
3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 7 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . 8
3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 7 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . 8
3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 7 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8
3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 9 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . 10
3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 19 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . 20
3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 21 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 22
3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 22 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . 23
3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 24 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . 25
3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 33 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . 34
3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 34 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . 35
3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 49 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 50
3.7. Additional retrieval query parameters . . . . . . . . . . 50 3.7. Additional Operation Response Parameters . . . . . . . . 51
3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 51 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . 52
3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 51 3.9. "/Me" Authenticated Subject Alias . . . . . . . . . . . . 53
3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . 53 3.10. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 53
3.11. Versioning Resources . . . . . . . . . . . . . . . . . . 53 3.11. API Versioning . . . . . . . . . . . . . . . . . . . . . 55
3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 55 3.12. Versioning Resources . . . . . . . . . . . . . . . . . . 55
4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 55 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 57
4.1. Associating Clients to Tenants . . . . . . . . . . . . . 56 4.1. Associating Clients to Tenants . . . . . . . . . . . . . 58
4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . 57 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 58
4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 57 5. Security Considerations . . . . . . . . . . . . . . . . . . . 59
4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 57 5.1. TLS Support . . . . . . . . . . . . . . . . . . . . . . . 59
4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . 57 5.2. Querying Using HTTP GET . . . . . . . . . . . . . . . . . 59
5. Security Considerations . . . . . . . . . . . . . . . . . . . 57 5.3. Universal Identifiers . . . . . . . . . . . . . . . . . . 60
6. References . . . . . . . . . . . . . . . . . . . . . . . . . 57
6.1. Normative References . . . . . . . . . . . . . . . . . . 58 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 60
6.2. Informative References . . . . . . . . . . . . . . . . . 59 6.1. Media Type Registration . . . . . . . . . . . . . . . . . 60
Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 59 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 61
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 59 7.1. Normative References . . . . . . . . . . . . . . . . . . 61
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 59 7.2. Informative References . . . . . . . . . . . . . . . . . 62
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 60 Appendix A. Contributors . . . . . . . . . . . . . . . . . . . . 62
Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 62
Appendix C. Change Log . . . . . . . . . . . . . . . . . . . . . 63
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 64
1. Introduction and Overview 1. Introduction and Overview
The SCIM Protocol is an application-level, REST 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
This document is intended as a guide to SCIM API usage for both This document is intended as a guide to SCIM API usage for both
identity service providers and clients. identity service providers and clients.
skipping to change at page 3, line 42 skipping to change at page 3, line 45
that affect the interoperability and security of implementations. that affect the interoperability and security of implementations.
When these words are not capitalized, they are meant in their When these words are not capitalized, they are meant in their
natural-language sense. natural-language sense.
For purposes of readability examples are not URL encoded. For purposes of readability examples are not URL encoded.
Implementers MUST percent encode URLs as described in Section 2.1 Implementers MUST percent encode URLs as described in Section 2.1
[RFC3986]. [RFC3986].
1.3. Definitions 1.3. Definitions
Base URL: The SCIM REST API is always relative to a Base URL. The Base URL: The SCIM HTTP API is always relative to a Base URL. The
Base URL MUST NOT contain a query string as clients may append Base URL MUST NOT contain a query string as clients may append
additional path information and query parameters as part of additional path information and query parameters as part of
forming the request. Example: https://example.com/scim/v2/ forming the request. Example: "https://example.com/scim/"
For readability, all examples in this document are expressed
assuming the SCIM service root and the server root are the same.
It is expected that SCIM servers may be deployed using any URI
prefix. For example, a SCIM server might be have a prefix of
"https://example.com/", or "https://example.com/scim/tenancypath/
". Additionally client may also apply a version number to the
server root prefix (see Section 3.11).
2. Authentication and Authorization 2. Authentication and Authorization
The SCIM protocol does not define a scheme for authentication and The SCIM protocol does not define a scheme for authentication and
authorization therefore implementers are free to choose mechanisms authorization therefore implementers are free to choose mechanisms
appropriate to their use cases. The choice of authentication appropriate to their use cases. The choice of authentication
mechanism will impact interoperability. It is RECOMMENDED that mechanism will impact interoperability. It is RECOMMENDED that
clients be implemented in such a way that new authentication schemes clients be implemented in such a way that new authentication schemes
can be deployed. Implementers SHOULD support existing authentication can be deployed. Implementers SHOULD support existing authentication
/authorization schemes. In particular, OAuth2[RFC6750] is /authorization schemes. In particular, OAuth2[RFC6750] is
skipping to change at page 15, line 18 skipping to change at page 16, line 18
Providers MAY support additional filter operations if they choose. Providers MAY support additional filter operations if they choose.
Providers MUST decline to filter results if the specified filter Providers MUST decline to filter results if the specified filter
operation is not recognized and return a HTTP 400 error with an operation is not recognized and return a HTTP 400 error with an
appropriate human readable response. For example, if a client appropriate human readable response. For example, if a client
specified an unsupported operator named 'regex' the service provider specified an unsupported operator named 'regex' the service provider
should specify an error response description identifying the client should specify an error response description identifying the client
error; e.g., 'The operator 'regex' is not supported.' error; e.g., 'The operator 'regex' is not supported.'
String type attributes are case insensitive by default unless the String type attributes are case insensitive by default unless the
attribute type is defined as a caseExact string. Attribute operators attribute type is defined as case exact. Attribute comparison
'eq', 'co', and 'sw' MUST perform caseIgnore matching for all string operators 'eq', 'co', and 'sw' MUST perform caseIgnore matching for
attributes unless the attribute is defined as caseExact. By default all string attributes unless the attribute is defined as case exact.
all string attributes are caseIgnore. By default all string attributes are case insensitive.
Clients MAY search by schema or schema extensions by using a filter Clients MAY search by schema or schema extensions by using a filter
expression including the "schemas" attribute. expression including the "schemas" attribute.
The following are examples of valid filters. Some attributes (e.g. The following are examples of valid filters. Some attributes (e.g.
rooms and rooms.number) are hypothetical extensions and are not part rooms and rooms.number) are hypothetical extensions and are not part
of SCIM core schema: of SCIM core schema:
filter=userName eq "bjensen" filter=userName eq "bjensen"
skipping to change at page 17, line 30 skipping to change at page 18, line 30
data for the specified "sortBy" value they are sorted via the data for the specified "sortBy" value they are sorted via the
"sortOrder" parameter; i.e., they are ordered last if ascending "sortOrder" parameter; i.e., they are ordered last if ascending
and first if descending. and first if descending.
sortOrder: The order in which the sortBy parameter is applied. sortOrder: The order in which the sortBy parameter is applied.
Allowed values are "ascending" and "descending". If a value for Allowed values are "ascending" and "descending". If a value for
sortBy is provided and no sortOrder is specified, the sortOrder sortBy is provided and no sortOrder is specified, the sortOrder
SHALL default to ascending. String type attributes are case SHALL default to ascending. String type attributes are case
insensitive by default unless the attribute type is defined as a insensitive by default unless the attribute type is defined as a
case exact string. "sortOrder" MUST sort according to the case exact string. "sortOrder" MUST sort according to the
attribute type; i.e., for "caseIgnore" attributes, sort the result attribute type; i.e., for caee insensitive attributes, sort the
using case insensitive, unicode alphabetic sort order, with no result using case insensitive, unicode alphabetic sort order, with
specific locale implied and for caseExact attribute types, sort no specific locale implied and for case exact attribute types,
the result using case sensitive, Unicode alphabetic sort order. sort the result using case sensitive, Unicode alphabetic sort
order.
3.2.2.4. Pagination 3.2.2.4. Pagination
Pagination parameters can be used together to "page through" large Pagination parameters can be used together to "page through" large
numbers of resources so as not to overwhelm the client or service numbers of resources so as not to overwhelm the client or service
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
skipping to change at page 19, line 39 skipping to change at page 20, line 39
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').
The body of the POST request MAY include any of the parameters as The body of the POST request MAY include any of the parameters as
defined in Section 3.2.2. defined in Section 3.2.2.
Search requests MUST be identified using the following URI: Search requests MUST be identified using the following URI:
'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes 'urn:scim:schemas:core:2.0:SearchRequest'. The following attributes
are defined for search requests: are defined for search requests:
attributes A multi-valued list of strings indicating the names of attributes A multi-valued list of strings indicating the names of
resource attributes to return in the response. Attribute names 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 MUST be in standard attribute notation (Section 3.8) form. See
additional retrieval query parameters (Section 3.7). OPTIONAL. 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.
filter The filter string used to request a subset of resources. The filter The filter string used to request a subset of resources. The
filter string MUST be a valid filter (Section 3.2.2.2) expression. filter string MUST be a valid filter (Section 3.2.2.2) expression.
OPTIONAL. OPTIONAL.
sortBy A string indicating the attribute whose value SHALL be used sortBy A string indicating the attribute whose value SHALL be used
to order the returned responses. The sortBy attribute MUST be in to order the returned responses. The sortBy attribute MUST be in
standard attribute notation (Section 3.8) form. See sorting standard attribute notation (Section 3.8) form. See sorting
(Section 3.2.2.3). OPTIONAL. (Section 3.2.2.3). OPTIONAL.
sortOrder A string indicating the order in which the sortBy sortOrder A string indicating the order in which the sortBy
skipping to change at page 26, line 41 skipping to change at page 27, line 41
The following is a non-normative example of an error response to a The following is a non-normative example of an error response to a
patch request. patch request.
HTTP/1.1 400 Bad Request HTTP/1.1 400 Bad Request
Content-Type: application/json;charset=UTF-8 Content-Type: application/json;charset=UTF-8
Cache-Control: no-store Cache-Control: no-store
Pragma: no-cache Pragma: no-cache
{ {
"error":"mutability", "schemas": ["urn:scim:schemas:core:2.0:Error"],
"error_description":"Attribute 'id' is readOnly." "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 response (Section 3.7)) within the response body, or a 204 No Content response
code and the appropriate response headers for a successful patch code and the appropriate response headers for a successful patch
request. The server MUST return a 200 OK if the "attributes" request. The server MUST return a 200 OK if the "attributes"
parameter is specified on the request. parameter is specified on the request.
skipping to change at page 34, line 44 skipping to change at page 35, line 44
"Errors":[ "Errors":[
{ {
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404" "code":"404"
} }
] ]
} }
3.5. Bulk 3.5. Bulk
Bulk is OPTIONAL. The bulk operation enables clients to send a The SCIM bulk operation is an optional server feature that enables
potentially large collection of resource operations in a single clients to send a potentially large collection of resource operations
request. The body of a a bulk operation contains a set of HTTP in a single request. The body of a a bulk operation contains a set
resource operations using one of the API supported HTTP methods; of HTTP resource operations using one of the API supported HTTP
i.e., POST, PUT, PATCH or DELETE. methods; i.e., POST, PUT, PATCH or DELETE.
Bulk requests are identified using the following URI: Bulk requests are identified using the following URI:
'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are 'urn:scim:schemas:core:2.0:BulkRequest'. Bulk responses are
identified using the following URI: identified using the following URI:
'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk 'urn:scim:schemas:core:2.0:BulkResponse'. Bulk requests and bulk
responses share many attributes. Unless otherwise specified, each responses share many attributes. Unless otherwise specified, each
attribute below is present in both bulk requests and bulk responses. attribute below is present in both bulk requests and bulk responses.
The following Singular Attribute is defined in addition to the common The following Singular Attribute is defined in addition to the common
attributes defined in SCIM core schema. attributes defined in SCIM core schema.
skipping to change at page 49, line 38 skipping to change at page 50, line 38
"Errors":[ "Errors":[
{ {
"description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).", "description":"The size of the bulk operation exceeds the maxPayloadSize (1048576).",
"code":"413" "code":"413"
} }
] ]
} }
3.6. Data Input/Output Formats 3.6. Data Input/Output Formats
Clients MUST specify the format in which the data is submitted via Servers MUST accept requests and respond with JSON structured
the Section 14.17 HTTP header content-type [RFC2616] and MAY specify responses using UTF-8 encoding [RFC3629], UTF-8 SHALL be the default
the desired response data format via an HTTP Accept Header; encoding format.
e.g.,"Accept: application/json" or via URI suffix; e.g.,
Clients using other encodings MUST specify the format in which the
data is submitted via Section 14.17 HTTP header content-type[RFC2616]
and MAY specify the desired response data format via an HTTP Accept
Header; e.g.,"Accept: application/json" or via URI suffix; e.g.,
GET /Users/2819c223-7f76-453a-919d-413861904646.json GET /Users/2819c223-7f76-453a-919d-413861904646.json
Host: example.com Host: example.com
Service providers MUST support the Accept Headers "Accept: Service providers MUST support the Accept Headers "Accept:
application/json" for [RFC7159]. The format defaults to JSON if no application/json" for [RFC7159]. The format defaults to JSON if no
format is specified. format is specified.
Singular attributes are encoded as string name-value-pairs in JSON; Singular attributes are encoded as string name-value-pairs in JSON;
e.g., e.g.,
"attribute": "value" "attribute": "value"
Multi-valued attributes in JSON are encoded as arrays; e.g., Multi-valued attributes in JSON are encoded as arrays; e.g.,
skipping to change at page 50, line 19 skipping to change at page 51, line 22
Multi-valued attributes in JSON are encoded as arrays; e.g., Multi-valued attributes in JSON are encoded as arrays; e.g.,
"attributes": [ "value1", "value2" ] "attributes": [ "value1", "value2" ]
Elements with nested elements are represented as objects in JSON; Elements with nested elements are represented as objects in JSON;
e.g, e.g,
"attribute": { "subattribute1": "value1", "subattribute2": "value2" } "attribute": { "subattribute1": "value1", "subattribute2": "value2" }
3.7. Additional retrieval query parameters 3.7. Additional Operation Response Parameters
For any SCIM operation where a resource representation is returned
(e.g. HTTP GET), the attributes normally returned are defined as the
minimum attribute set plus default attributes. The minimum set are
those attributes whose schema have "returned" set to "always". The
defaut attribute set are those attributes whose schema have
"returned" set to "default".
Clients MAY request a partial resource representation on any Clients MAY request a partial resource representation on any
operation that returns a resource within the response by specifying operation that returns a resource within the response by specifying
the URL query parameter 'attributes'. When specified, each resource either of the mutually exclusive URL query parameters "attributes" OR
returned MUST contain the minimal set of resource attributes and MUST "excludedAtributes" as follows:
contain no other attributes or Sub-Attributes than those explicitly
requested. The query parameter attributes value is a comma separated attributes When specified, each resource returned MUST contain the
list of resource attribute names in standard attribute notation minimal set of resource attributes and MUST contain no other
(Section 3.8) form (e.g. userName, name, emails). attributes or sub-attributes other than those explicitly
requested. The query parameter attributes value is a comma
separated list of resource attribute names in standard
attribute notation (Section 3.8) form (e.g. userName, name,
emails).
excludedAttributes When specified, each resource returned MUST
contain the minimal set of resource attributes.
Additionally, the default set of attributes minus those
attributes listed in "excludedAttributes"are also returned.
The query parameter attributes value is a comma separated
list of resource attribute names in standard attribute
notation (Section 3.8) form (e.g. userName, name, emails).
.
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=userName
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
Giving the response Giving the response
HTTP/1.1 200 OK HTTP/1.1 200 OK
Content-Type: application/json Content-Type: application/json
skipping to change at page 51, line 40 skipping to change at page 53, line 5
omit core schema attribute URN prefixes though MUST fully qualify omit core schema attribute URN prefixes though MUST fully qualify
extended attributes with the associated resource URN; e.g., the extended attributes with the associated resource URN; e.g., the
attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as
'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are 'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are
referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute
name}.{Sub-Attribute name}. For example, the fully qualified path for name}.{Sub-Attribute name}. For example, the fully qualified path for
a User's givenName is urn:scim:schemas:core:2.0:User:name.givenName a User's givenName is urn:scim:schemas:core:2.0:User:name.givenName
All facets (URN, attribute and Sub-Attribute name) of the fully All facets (URN, attribute and Sub-Attribute name) of the fully
encoded Attribute name are case insensitive. encoded Attribute name are case insensitive.
3.9. HTTP Response Codes 3.9. "/Me" Authenticated Subject Alias
A client MAY use a URL of the form "<server-root>/Me" as an URL alias
for the User or other resource associated with the currently
authenticated subject for any SCIM operation. A service provider MAY
respond in ONE of 3 ways:
o A service provider that does NOT support this feature SHOULD
respond with status 403 (FORBIDDEN).
o A service provider MAY choose to redirect the client using HTTP
status 308 to the resource associated with the authenticated
subject. The client MAY then repeat the request at the indicated
location.
o A service provider MAY process the SCIM request directly. In any
response, the HTTP "Location" header MUST be the permanent
location of the aliased resource associated with the authenticated
subject.
3.10. HTTP Response Codes
The SCIM Protocol uses the response status codes defined in HTTP The SCIM Protocol uses the response status codes defined in HTTP
Section 10 [RFC2616] to indicate operation success or failure. In Section 10 [RFC2616] 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:schemas:core:2.0:Error'. The following following URI: 'urn:scim:schemas:core:2.0:Error'. The following
multi-valued attribute is defined in addition to those attributes multi-valued attribute is defined in addition to those attributes
defined in SCIM Core Schema: defined in SCIM Core Schema:
skipping to change at page 53, line 31 skipping to change at page 55, line 17
{ {
"schemas": ["urn:scim:schemas:core:2.0:Error"], "schemas": ["urn:scim:schemas:core:2.0:Error"],
"Errors":[ "Errors":[
{ {
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found", "description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404" "code":"404"
} }
] ]
} }
3.10. 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 the only valid identifier is segment in the URL path. At this time the only valid identifier is
'v1'. If specified, the version identifier MUST appear in the URL 'v1'. If specified, the version identifier MUST appear in the URL
path immediately preceding the resource endpoint and conform to the path immediately preceding the resource endpoint and conform to the
following scheme: the character 'v' followed by the desired SCIM following scheme: the character 'v' followed by the desired SCIM
version number; e.g., a version 'v1' User request is specified as /v2 version number; e.g., a version 'v1' User request is specified as /v2
/Users. When specified service providers MUST perform the operation /Users. When specified service providers MUST perform the operation
using the desired version or reject the request. When omitted using the desired version or reject the request. When omitted
service providers SHOULD perform the operation using the most recent service providers SHOULD perform the operation using the most recent
API supported by the service provider. API supported by the service provider.
3.11. Versioning Resources 3.12. Versioning Resources
The API supports resource versioning via standard HTTP The API supports resource versioning via standard HTTP
ETagsSection 14.19 [RFC2616]. Service providers MAY support weak ETagsSection 14.19 [RFC2616]. Service providers MAY support weak
ETags as the preferred mechanism for performing conditional ETags as the preferred mechanism for performing conditional
retrievals and ensuring clients do not inadvertently overwrite each retrievals and ensuring clients do not inadvertently overwrite each
others changes, respectively. When supported SCIM ETags MUST be others changes, respectively. When supported SCIM ETags MUST be
specified as an HTTP header and SHOULD be specified within the specified as an HTTP header and SHOULD be specified within the
'version' attribute contained in the resource's 'meta' attribute. 'version' attribute contained in the resource's 'meta' attribute.
Example: Example:
skipping to change at page 55, line 20 skipping to change at page 57, line 15
GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName GET /Users/2819c223-7f76-453a-919d-413861904646?attributes=displayName
Host: example.com Host: example.com
Accept: application/json Accept: application/json
Authorization: Bearer h480djs93hd8 Authorization: Bearer h480djs93hd8
If-None-Match: W/"e180ee84f0671b1" If-None-Match: W/"e180ee84f0671b1"
If the resource has not changed the service provider simply returns If the resource has not changed the service provider simply returns
an empty body with a 304 "Not Modified" response code. an empty body with a 304 "Not Modified" response code.
If the service providers supports versioning of resources the client If the service providers supports versioning of resources the client
MUST supply an If-Match Section 14.24 [RFC2616] header for PUT and MAY supply an If-Match Section 14.24 [RFC2616] header for PUT and
PATCH operations to ensure that the requested operation succeeds only PATCH operations to ensure that the requested operation succeeds only
if the supplied ETag matches the latest service provider resource; if the supplied ETag matches the latest service provider resource;
e.g., If-Match: W/"e180ee84f0671b1" e.g., If-Match: W/"e180ee84f0671b1"
3.12. HTTP Method Overloading
In recognition that some clients, servers and firewalls prevent PUT,
PATCH and DELETE operations a client MAY override the POST operation
by specifying the custom header "X-HTTP-Method-Override" with the
desired PUT, PATCH, DELETE operation. For example:
POST /Users/2819c223-7f76-453a-919d-413861904646
X-HTTP-Method-Override: DELETE
4. Multi-Tenancy 4. Multi-Tenancy
A single service provider may expose the SCIM protocol to multiple A single service provider may expose the SCIM protocol to multiple
clients. Depending on the nature of the service, the clients may clients. Depending on the nature of the service, the clients may
have authority to access and alter resources initially created by have authority to access and alter resources initially created by
other clients. Alternatively, clients may expect to access disjoint other clients. Alternatively, clients may expect to access disjoint
sets of resources, and may expect that their resources are sets of resources, and may expect that their resources are
inaccessible by other clients. These scenarios are called "multi- inaccessible by other clients. These scenarios are called "multi-
tenancy", where each client is understood to be or represent a tenancy", where each client is understood to be or represent a
"tenant" of the service provider. Clients may also be multi- "tenant" of the service provider. Clients may also be multi-
skipping to change at page 56, line 20 skipping to change at page 58, line 4
Service providers may implement any subset of the above cases. Service providers may implement any subset of the above cases.
Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a
scheme for multi-tenancy. scheme for multi-tenancy.
The SCIM protocol does not prescribe the mechanisms whereby clients The SCIM protocol does not prescribe the mechanisms whereby clients
and service providers interact for: and service providers interact for:
o Registering or provisioning Tenants o Registering or provisioning Tenants
o Associating a subset of clients with a subset of the Tenants o Associating a subset of clients with a subset of the Tenants
o Indicating which tenant is associated with the data in a request o Indicating which tenant is associated with the data in a request
or response, or indicating which Tenant is the subject of a query or response, or indicating which Tenant is the subject of a query
o Implementers are encouraged to use mechanisms which comply with
RESTful conventions.
4.1. Associating Clients to Tenants 4.1. Associating Clients to Tenants
The service provider MAY use the authentication mechanism (Section 2) The service provider MAY use the authentication mechanism (Section 2)
to determine the identity of the client, and thus infer the to determine the identity of the client, and thus infer the
associated Tenant. associated Tenant.
For implementations where a client is associated with more than one For implementations where a client is associated with more than one
Tenant, the service provider MAY use one of the following methods for Tenant, the service provider MAY use one of the following methods for
explicit specification of the Tenant. explicit specification of the Tenant.
If any of these methods of allowing the client to explicitly specify If any of these methods of allowing the client to explicitly specify
the Tenant are employed, the service provider should ensure that the Tenant are employed, the service provider should ensure that
access controls are in place to prevent or allow cross-tenant use access controls are in place to prevent or allow cross-tenant use
cases. cases.
The service provider should consider precedence in cases where a The service provider should consider precedence in cases where a
client may explicitly specify a Tenant while being implicitly client may explicitly specify a Tenant while being implicitly
associated with a different Tenant. associated with a different Tenant.
4.1.1. URL Prefix Example In all of these methods, the {tenant_id} is a unique identifier for
the Tenant as defined by the service provider.
https://www.example.com/Tenants/{tenant_id}/v2/Users
4.1.2. Subdomain Example
https://{tenant_id}.example.com/v2/Groups
4.1.3. HTTP Header o A URL prefix: "https://www.example.com/Tenants/{tenant_id}/v2/
Users"
The service provider may recognize a {tenant_id} provided by the o A sub-domain: "https://{tenant_id}.example.com/v2/Groups"
client in the HTTP Header "SCIM_TENANT_ID" as the indicator of the
desired target Tenant.
In all of these methods, the {tenant_id} is a unique identifier for o The service provider may recognize a {tenant_id} provided by the
the Tenant as defined by the service provider. client in an HTTP Header as the indicator of the desired target
Tenant.
4.2. SCIM Identifiers with Multiple Tenants 4.2. SCIM Identifiers with Multiple Tenants
Considerations for a Multi-Tenant Implementation: Considerations for a Multi-Tenant Implementation:
The service provider may choose to implement SCIM ids which are The service provider may choose to implement SCIM ids which are
unique across all resources for all Tenants, but this is not unique across all resources for all Tenants, but this is not
required. required.
The externalId, defined by the client, is required to be unique ONLY The externalId, defined by the client, is required to be unique ONLY
within the resources associated with the associated Tenant. within the resources associated with the associated Tenant.
5. Security Considerations 5. Security Considerations
5.1. TLS Support
The SCIM Protocol is based on HTTP and thus subject to the security The SCIM Protocol is based on HTTP and thus subject to the security
considerations found in Section 15 of [RFC2616]. SCIM resources considerations found in Section 15 of [RFC2616]. SCIM resources
(e.g., Users and Groups) can contain sensitive information. (e.g., Users and Groups) can contain sensitive information.
Therefore, SCIM clients and service providers MUST implement TLS. Therefore, SCIM clients and service providers MUST implement TLS.
Which version(s) ought to be implemented will vary over time, and Which version(s) ought to be implemented will vary over time, and
depend on the widespread deployment and known security depend on the widespread deployment and known security
vulnerabilities at the time of implementation. At the time of this vulnerabilities at the time of implementation. At the time of this
writing, TLS version 1.2 [RFC5246]] is the most recent version, but writing, TLS version 1.2 [RFC5246] is the most recent version, but
has very limited actual deployment, and might not be readily has very limited actual deployment, and might not be readily
available in implementation toolkits. TLS version 1.0 [[RFC2246]] is available in implementation toolkits. TLS version 1.0 [RFC2246] is
the most widely deployed version, and will give the broadest the most widely deployed version, and will give the broadest
interoperability. interoperability.
6. References 5.2. Querying Using HTTP GET
6.1. Normative References
Clients requesting information using query filters SHOULD give
consideration to the information content of the filters and whether
their exposure in a URL would represent a breach of security or
confidentiality through leakage in a web browser or logs. This is
particularly true for information that is legally considered
"personally identifiable information" or is otherwise restricted by
privacy laws. To ensure maximum security and confidentiality,
clients SHOULD query using HTTP POST (see Section 3.2.3).
Servers that receive HTTP GET requests using filters that contain
restricted or confidential information SHOULD respond with HTTP
status 403 indicating the operation is FORBIDDEN. A detialed error,
"confidential_restricted" may be returned indicating the request must
be submitted using POST. A non-normative example:
HTTP/1.1 403 FORBIDDEN
{
"schemas": ["urn:scim:schemas:core:2.0:Error"],
"Errors":[
{
"description":"Query filter involving 'name' is restricted or confidential",
"error":"confidential_restricted"
}
]
}
5.3. Universal Identifiers
6. IANA Considerations
6.1. Media Type Registration
To: ietf-types@iana.org
Subject: Registration of media type application/scim+json
Type name: application
Subtype name: scim+json
Required parameters: none
Optional parameters: none
Encoding considerations: 8bit
Security considerations: See Section 5
Interoperability considerations: The "application/scim+json" media
type is intended to identify JSON structure data that conforms to
the SCIM 2 api and schema specifications. Older versions of SCIM
are known to informally use "application/json".
Published specification: [[this document]]
Applications that use this media type: It is expected that
applications that use this type may be special purpose
applications intended for inter-domain provisioning. Clients may
also be applications (e.g. mobile applications) that need to use
SCIM for self-registration of user accounts. SCIM services may be
offered by web applications wishin to offer support for standards
based provisioning or may be a dedicated SCIM service provider
such as a "cloud directory". Content may be treated as equivalent
to "application/json" type for the purpose of displaying in web
browsers.
Additional information:
Magic number(s):
File extension(s): .scim .scm
Macintosh file type code(s):
Person & email address to contact for futher information: SCIM
mailing list "<scim@ietf.org>"
Intended usage: COMMON* (see restrictions)
Restrictions on usage: For most client types, it is sufficient to
recognize the content as equivalent to "application/json".
Applications intending to use the SCIM API SHOULD use the
application/scim+json media type.
Author: Phil Hunt
Change controller: IETF
7. References
7.1. Normative References
[I-D.ietf-httpbis-p2-semantics] [I-D.ietf-httpbis-p2-semantics]
Fielding, R. and J. Reschke, "Hypertext Transfer Protocol Fielding, R. and J. Reschke, "Hypertext Transfer Protocol
(HTTP/1.1): Semantics and Content", draft-ietf- (HTTP/1.1): Semantics and Content", draft-ietf-
httpbis-p2-semantics-25 (work in progress), November 2013. httpbis-p2-semantics-25 (work in progress), November 2013.
[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-03 (work in Schema", draft-ietf-scim-core-schema-03 (work in
skipping to change at page 58, line 36 skipping to change at page 62, line 5
[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.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., [RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H.,
Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext Masinter, L., Leach, P., and T. Berners-Lee, "Hypertext
Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999. Transfer Protocol -- HTTP/1.1", RFC 2616, June 1999.
[RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO
10646", STD 63, RFC 3629, November 2003.
[RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform
Resource Identifier (URI): Generic Syntax", STD 66, RFC Resource Identifier (URI): Generic Syntax", STD 66, RFC
3986, January 2005. 3986, January 2005.
[RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax
Specifications: ABNF", STD 68, RFC 5234, January 2008. Specifications: ABNF", STD 68, RFC 5234, January 2008.
[RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security [RFC5246] Dierks, T. and E. Rescorla, "The Transport Layer Security
(TLS) Protocol Version 1.2", RFC 5246, August 2008. (TLS) Protocol Version 1.2", RFC 5246, August 2008.
[RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC [RFC5789] Dusseault, L. and J. Snell, "PATCH Method for HTTP", RFC
5789, March 2010. 5789, March 2010.
[RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization [RFC6750] Jones, M. and D. Hardt, "The OAuth 2.0 Authorization
Framework: Bearer Token Usage", RFC 6750, October 2012. Framework: Bearer Token Usage", RFC 6750, October 2012.
[RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data
Interchange Format", RFC 7159, March 2014. Interchange Format", RFC 7159, March 2014.
6.2. Informative References 7.2. Informative References
[OpenSearch] [OpenSearch]
Clinton, D., "OpenSearch Protocol 1.1, Draft 5", . Clinton, D., "OpenSearch Protocol 1.1, Draft 5", .
[Order-Operations] [Order-Operations]
Wikipedia, "Order of Operations: Programming Languages", . Wikipedia, "Order of Operations: Programming Languages", .
[RFC2277] Alvestrand, H., "IETF Policy on Character Sets and
Languages", BCP 18, RFC 2277, January 1998.
[RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation [RFC6902] Bryan, P. and M. Nottingham, "JavaScript Object Notation
(JSON) Patch", RFC 6902, April 2013. (JSON) Patch", RFC 6902, April 2013.
Appendix A. Contributors Appendix A. Contributors
Samuel Erdtman (samuel@erdtman.se) Samuel Erdtman (samuel@erdtman.se)
Patrick Harding (pharding@pingidentity.com) Patrick Harding (pharding@pingidentity.com)
Appendix B. Acknowledgments Appendix B. Acknowledgments
skipping to change at page 60, line 28 skipping to change at page 63, line 49
60 - Changed <eref> tags to normal <xref> and <reference> tags 60 - Changed <eref> tags to normal <xref> and <reference> tags
Draft 04 - PH - Revisions based on the following tickets: Draft 04 - PH - Revisions based on the following tickets:
18 - New PATCH command based on JSON Patch (RFC6902) 18 - New PATCH command based on JSON Patch (RFC6902)
- Provided ABNF specification for filters (used in PATCH) - Provided ABNF specification for filters (used in PATCH)
- Updated references to RFC4627 to RFC7159 - Updated references to RFC4627 to RFC7159
Authors' Addresses Draft 05 - PH - Revisions based on the following tickets:
Kelly Grizzle 03 - Support for excludedAttributes parameter
SailPoint 13 - Change client use of Etags from MUST to MAY (correction)
Email: kelly.grizzle@sailpoint.com 23 - Clarifications regarding case exact processing.
41 - Add IANA considerations
65 - Removed X-HTTP-Method-Override support
69 - Added clarifications to intro to align with draft-nottingham-
uri-get-off-my-lawn
70 - Remove SCIM_TENANT_ID header
72 - Added text to indicate UTF-8 is default and mandatory
encoding format per BCP18
74 - Added security considerations for using GET with confidential
attribute filters
- corrected error response in JSON PATCH operation
Authors' Addresses
Phil Hunt (editor) Phil Hunt (editor)
Oracle Corporation Oracle Corporation
Email: phil.hunt@yahoo.com Email: phil.hunt@yahoo.com
Kelly Grizzle
SailPoint
Email: kelly.grizzle@sailpoint.com
Morteza Ansari Morteza Ansari
Cisco Cisco
Email: morteza.ansari@cisco.com Email: morteza.ansari@cisco.com
Erik Wahlstroem Erik Wahlstroem
Technology Nexus Technology Nexus
Email: erik.wahlstrom@nexussafe.com Email: erik.wahlstrom@nexussafe.com
Chuck Mortimore Chuck Mortimore
 End of changes. 41 change blocks. 
111 lines changed or deleted 285 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/