--- 1/draft-ietf-scim-api-00.txt 2013-04-16 04:04:56.431792132 +0200
+++ 2/draft-ietf-scim-api-01.txt 2013-04-16 04:04:56.503792196 +0200
@@ -1,25 +1,25 @@
Network Working Group T. Drake, Ed.
Internet-Draft UnboundID
Intended status: Standards Track C. Mortimore
-Expires: February 28, 2013 SalesForce
+Expires: October 17, 2013 SalesForce
M. Ansari
Cisco
K. Grizzle
SailPoint
E. Wahlstroem
Technology Nexus
- August 27, 2012
+ April 15, 2013
System for Cross-Domain Identity Management:Protocol
- draft-ietf-scim-api-00
+ draft-ietf-scim-api-01
Abstract
The System for Cross-Domain Identity Management (SCIM) specification
is designed to make managing user identity in cloud based
applications and services easier. The specification suite seeks to
build upon experience with existing schemas and deployments, placing
specific emphasis on simplicity of development and integration, while
applying existing authentication, authorization, and privacy models.
It's intent is to reduce the cost and complexity of user management
@@ -36,64 +36,72 @@
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet-
Drafts is at http://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
- This Internet-Draft will expire on February 28, 2013.
+ This Internet-Draft will expire on October 17, 2013.
Copyright Notice
- Copyright (c) 2012 IETF Trust and the persons identified as the
+ Copyright (c) 2013 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as
described in the Simplified BSD License.
Table of Contents
- 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 3
- 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 3
- 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 3
- 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 3
- 2. Authentication and Authorization . . . . . . . . . . . . . . . 3
- 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 4
- 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . . 6
- 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . . 7
- 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 7
- 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . . 8
- 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 15
- 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . . 15
- 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . . 17
- 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . . 25
- 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . . 26
- 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 41
- 3.7. Additional retrieval query parameters . . . . . . . . . . 42
- 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . . 42
- 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 43
- 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . . 44
- 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . . 44
- 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 46
- 4. Security Considerations . . . . . . . . . . . . . . . . . . . 46
- 5. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 47
- 6. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 47
- Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 47
+ 1. Introduction and Overview . . . . . . . . . . . . . . . . . . 4
+ 1.1. Intended Audience . . . . . . . . . . . . . . . . . . . . 4
+ 1.2. Notational Conventions . . . . . . . . . . . . . . . . . . 4
+ 1.3. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4
+ 2. Authentication and Authorization . . . . . . . . . . . . . . . 4
+ 3. API . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5
+ 3.1. Creating Resources . . . . . . . . . . . . . . . . . . . . 7
+ 3.1.1. Resource Types . . . . . . . . . . . . . . . . . . . . 8
+ 3.2. Retrieving Resources . . . . . . . . . . . . . . . . . . . 8
+ 3.2.1. Retrieving a known Resource . . . . . . . . . . . . . 8
+ 3.2.2. List/Query Resources . . . . . . . . . . . . . . . . . 10
+ 3.2.3. Querying Resources Using HTTP POST . . . . . . . . . . 17
+ 3.3. Modifying Resources . . . . . . . . . . . . . . . . . . . 19
+ 3.3.1. Modifying with PUT . . . . . . . . . . . . . . . . . . 19
+ 3.3.2. Modifying with PATCH . . . . . . . . . . . . . . . . . 21
+ 3.4. Deleting Resources . . . . . . . . . . . . . . . . . . . . 29
+ 3.5. Bulk . . . . . . . . . . . . . . . . . . . . . . . . . . . 30
+ 3.6. Data Input/Output Formats . . . . . . . . . . . . . . . . 45
+ 3.7. Additional retrieval query parameters . . . . . . . . . . 45
+ 3.8. Attribute Notation . . . . . . . . . . . . . . . . . . . . 46
+ 3.9. HTTP Response Codes . . . . . . . . . . . . . . . . . . . 46
+ 3.10. API Versioning . . . . . . . . . . . . . . . . . . . . . . 48
+ 3.11. Versioning Resources . . . . . . . . . . . . . . . . . . . 48
+ 3.12. HTTP Method Overloading . . . . . . . . . . . . . . . . . 50
+ 4. Multi-Tenancy . . . . . . . . . . . . . . . . . . . . . . . . 50
+ 4.1. Associating Consumers to Tenants . . . . . . . . . . . . . 51
+ 4.1.1. URL Prefix Example . . . . . . . . . . . . . . . . . . 51
+ 4.1.2. Subdomain Example . . . . . . . . . . . . . . . . . . 52
+ 4.1.3. HTTP Header . . . . . . . . . . . . . . . . . . . . . 52
+ 4.2. SCIM Identifiers with Multiple Tenants . . . . . . . . . . 52
+ 5. Security Considerations . . . . . . . . . . . . . . . . . . . 52
+ 6. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 52
+ 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 53
+ Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 53
1. Introduction and Overview
The SCIM Protocol is an application-level, REST protocol for
provisioning and managing identity data on the web. The protocol
supports creation, modification, retrieval, and discovery of core
identity Resources; i.e., Users and Groups, as well as custom
Resource extensions.
1.1. Intended Audience
@@ -155,21 +163,22 @@
Providers that support extended Resources SHOULD define Resource
endpoints using the established convention; pluralize the Resource
name defined in the extended schema by appending an 's'. Given there
are cases where Resource pluralization is ambiguous; e.g., a Resource
named 'person' is legitimately 'persons' and 'people' Consumers
SHOULD discover Resource endpoints via the Schema Sub-Attribute
'endpoint'.
GET Retrieves a complete or partial Resource.
- POST Create new Resource or bulk modify Resources.
+ POST Create new Resource, perform an extended Search, or bulk modify
+ Resources.
PUT Modifies a Resource with a complete, Consumer specified Resource
(replace).
PATCH Modifies a Resource with a set of Consumer specified changes
(partial update).
DELETE Deletes a Resource.
+------------+--------------------+---------------+-----------------+
@@ -199,30 +208,38 @@
| | | 3.4) | |
| Service | /ServiceProviderCo | GET | Retrieve the |
| Provider | nfigs | (Section 3.2. | Service |
| Configurat | | 1) | Provider's |
| ion | | | Configuration |
| Schema | /Schemas | GET | Retrieve a |
| | | (Section 3.2. | Resource's |
| | | 1) | Schema |
| Bulk | /Bulk | POST | Bulk modify |
| | | (Section 3.5) | Resources |
+ | Search | [prefix]/.search | POST | Perform a |
+ | | | (Section 3.2. | search at |
+ | | | 3) | system root or |
+ | | | | within a |
+ | | | | resource |
+ | | | | endpoint for |
+ | | | | one or more |
+ | | | | resource types |
+ | | | | using POST. |
+------------+--------------------+---------------+-----------------+
Table 1: Defined endpoints
All requests to the Service Provider are made via HTTP operations on
a URL derived from the Base URL. Responses are returned in the body
- of the HTTP response, formatted as JSON or XML, depending on what is
- requested. Response and error codes SHOULD be transmitted via the
- HTTP status code of the response (if possible), and SHOULD also be
- specified in the body of the response.
+ of the HTTP response, formatted as JSON. Response and error codes
+ SHOULD be transmitted via the HTTP status code of the response (if
+ possible), and SHOULD also be specified in the body of the response.
3.1. Creating Resources
To create new Resources, clients send POST requests to the Resource
endpoint; i.e., /Users or /Groups.
Successful Resource creation is indicated with a 201 ("Created")
response code. Upon successful creation, the response body MUST
contain the newly created Resource. Since the server is free to
alter and/or ignore POSTed content, returning the full representation
@@ -263,33 +280,46 @@
HTTP/1.1 201 Created
Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"e180ee84f0671b1"
{
"schemas":["urn:scim:schemas:core:1.0"],
"id":"2819c223-7f76-453a-919d-413861904646",
"externalId":"bjensen",
"meta":{
+ "resourceType":"User",
"created":"2011-08-01T21:32:44.882Z",
"lastModified":"2011-08-01T21:32:44.882Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"e180ee84f0671b1\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
"userName":"bjensen"
}
+3.1.1. Resource Types
+
+ When adding a resource to a specific endpoint, the meta attribute
+ "resourceType" SHALL be set by the Service Provider to the
+ corresponding resource type for the endpoint and any extension types.
+ For example, "/Users" will set "resourceType" to "User", and
+ "/Groups" will set "resourceType" to "Group".
+
+ [TBD: For extended resource types, the "resourceType" attribute SHALL
+ be set by the Service Provider to have multiple values including the
+ base type plus any extneded types (e.g. 'User' and 'Employee').]
+
3.2. Retrieving Resources
Users and Group Resources are retrieved via opaque, unique URLs or
via Query. Service Providers MAY choose to respond with a sub-set of
Resource attributes, though MUST minimally return the Resource id and
meta attributes.
3.2.1. Retrieving a known Resource
To retrieve a known Resource, clients send GET requests to the
@@ -309,20 +340,21 @@
HTTP/1.1 200 OK
Content-Type: application/json
Location: https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646
ETag: W/"f250dd84f0671c3"
{
"schemas":["urn:scim:schemas:core:1.0"],
"id":"2819c223-7f76-453a-919d-413861904646,
"externalId":"bjensen",
"meta":{
+ "resourceType":"User",
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:49.793Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"f250dd84f0671c3\""
},
"name":{
"formatted":"Ms. Barbara J Jensen III",
"familyName":"Jensen",
"givenName":"Barbara"
},
@@ -366,21 +398,44 @@
"Resources":[
{
"userName":"bjensen"
},
{
"userName":"jsmith"
}
]
}
-3.2.2.1. Filtering
+3.2.2.1. Query Endpoints
+
+ Queries MAY be performed against a SCIM:
+
+ Resource (e.g. /Users/{userid}),
+
+ Resource Type endpoint (e.g. /Users or /Groups), or
+
+ Server Root (e.g. /).
+
+ A search against a server root indicates that ALL resources within
+ the server SHALL be included subject to filtering. For example, a
+ filter against 'resourceType' could be used to restrict results to
+ one or more specific resource types.
+
+ When processing search operations across endpoints that include more
+ than one SCIM resource type (e.g. a search from the server root
+ endpoint), filters MUST be processed in the same fashion as outlined
+ in Section 3.2.2.2. For filtered attributes that are not part of a
+ particular resource type, the service provider SHALL treat the
+ attribute as if there is no attribute value. For example, a presence
+ or equality filter for an undefined attribute evaluates as FALSE.
+
+3.2.2.2. Filtering
Filtering is OPTIONAL. Consumers may request a subset of Resources
by specifying the 'filter' URL query parameter containing a filter
expression. When specified only those Resources matching the filter
expression SHALL be returned. The expression language that is used
in the filter parameter supports references to attributes and
literals. The literal values can be strings enclosed in double
quotes, numbers, date times enclosed in double quotes, and Boolean
values; i.e., true or false. String literals MUST be valid JSON
strings [2].
@@ -521,21 +576,21 @@
filter=meta.lastModified le "2011-05-13T04:42:34Z"
filter=title pr and userType eq "Employee"
filter=title pr or userType eq "Intern"
filter=userType eq "Employee" and (emails co "example.com" or emails
co "example.org")
-3.2.2.2. Sorting
+3.2.2.3. Sorting
Sort is OPTIONAL. Sorting allows Consumers to specify the order in
which Resources are returned by specifying a combination of sortBy
and sortOrder URL parameters.
sortBy: The sortBy parameter specifies the attribute whose value
SHALL be used to order the returned responses. If the sortBy
attribute corresponds to a Singular Attribute, Resources are
sorted according to that attribute's value; if it's a Multi-valued
Attribute, Resources are sorted by the value of the primary
@@ -551,21 +606,21 @@
Allowed values are "ascending" and "descending". If a value for
sortBy is provided and no sortOrder is specified, the sortOrder
SHALL default to ascending. String type attributes are case
insensitive by default unless the attribute type is defined as a
caseExact string. sortOrder MUST sort according to the attribute
type; i.e., for caseIgnore attributes, sort the result using case
insensitive, Unicode alphabetic sort order, with no specific
locale implied and for caseExact attribute types, sort the result
using case sensitive, Unicode alphabetic sort order.
-3.2.2.3. Pagination
+3.2.2.4. Pagination
Pagination parameters can be used together to "page through" large
numbers of Resources so as not to overwhelm the Consumer or Service
Provider. Pagination is not session based hence Consumers SHOULD
never assume repeatable results. For example, a request for a list
of 10 Resources beginning with a startIndex of 1 may return different
results when repeated as a Resource in the original result could be
deleted or new ones could be added in-between requests. Pagination
parameters and general behavior are derived from the OpenSearch
Protocol [3].
@@ -617,23 +672,96 @@
{
"totalResults":100,
"itemsPerPage":10,
"startIndex":1,
"schemas":["urn:scim:schemas:core:1.0"],
"Resources":[{
...
}]
}
+
Given the example above, to continue paging set the startIndex to 11
and re-fetch; i.e., /Users?startIndex=11&count=10
+3.2.3. Querying Resources Using HTTP POST
+
+ Clients MAY execute queries without passing parameters on the URL by
+ using the HTTP POST verb combined with the '/.search' path extension.
+ The inclusion of '/.search' on the end of a valid SCIM endpoint SHALL
+ be used to indicate the HTTP POST verb is intended to be a query
+ operation.
+
+ To create a new search result set, a SCIM client sends an HTTP POST
+ request to the desired SCIM resource endpoint (ending in '/.search').
+ The body of the POST request MAY include any of the parameters as
+ defined in Section 3.2.2.
+
+ After receiving a HTTP POST request, a response is returned as
+ specified in Section 3.2.2.
+
+ [NOTE: See resourceType meta attribute in example below --> need to
+ update rest of document!]
+ The following example shows an HTTP POST Search request with search
+ parameters attributes, filter, and count included:
+ POST /.search
+ Host: example.com
+ Accept: application/json
+ Content-Type: application/json
+ Authorization: Bearer h480djs93hd8
+ Content-Length: ...
+
+ {
+ "schemas": ["urn:scim:schemas:core:1.0"],
+ "attributes":["displayName","username"],
+ "filter":"displayName sw \"smith\"",
+ "count":10
+ }
+
+ Figure 1: Example POST Search Request
+
+ A search response is shown with the first page of results. For
+ brevity reasons, only two matches are shown: one User and one Group.
+ HTTP/1.1 200 OK
+ Content-Type: application/json
+ Location: https://example.com/.search
+ {
+ "totalResults":100,
+ "itemsPerPage":10,
+ "startIndex":1,
+ "schemas":["urn:scim:schemas:core:1.0"],
+ "Resources":[
+ {
+ "meta":{
+ "location":
+ "https://example.com/Users/2819c223-7f76-413861904646",
+ "resourceType":"User",
+ "lastModified": ...
+ }
+ "username":"jsmith",
+ "displayName":"Smith, James"
+ },
+ {
+ "meta":{
+ "location":
+ "https://example.com/Groups/c8596b90-7539-4f20968d1908",
+ "resourceType":"Group",
+ "lastModified": ...
+ }
+ "displayName":"Smith Family"
+ },
+ ...
+ ]
+ }
+
+ Figure 2: Example POST Search Response
+
3.3. Modifying Resources
Resources can be modified in whole or in part via PUT or PATCH,
respectively. Implementers MUST support PUT as specified in RFC2616
. Resources such as Groups may be very large hence implementers
SHOULD support PATCH [4] to enable partial resource modifications.
3.3.1. Modifying with PUT
PUT performs a full update. Consumers must retrieve the entire
@@ -696,20 +824,21 @@
},
"emails":[
{
"value":"bjensen@example.com"
},
{
"value":"babs@jensen.org"
}
],
"meta": {
+ "resourceType","User",
"created":"2011-08-08T04:56:22Z",
"lastModified":"2011-08-08T08:00:12Z",
"location":"https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"version":"W\/\"b431af54f0671a2\""
}
}
3.3.2. Modifying with PATCH
PATCH is OPTIONAL. PATCH enables consumers to send only those
@@ -778,20 +907,21 @@
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas": ["urn:scim:schemas:core:1.0"],
"members": [
{
"display": "Babs Jensen",
+ "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
}
]
}
The "display" Sub-Attribute in this request is optional since the
value attribute uniquely identifies the user to be added. If the
user was already a member of this group, no changes should be made to
the Resource and a success response should be returned. The server
responds with either the entire updated Group or no response body:
@@ -814,20 +944,21 @@
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas": ["urn:scim:schemas:core:1.0"],
"members": [
{
"display": "Babs Jensen",
+ "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
"operation": "delete"
}
]
}
The following example shows how to remove all members from a group:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
@@ -858,49 +989,53 @@
{
"schemas": ["urn:scim:schemas:core:1.0"],
"meta": {
"attributes": [
"members"
]
},
"members": [
{
"display": "Babs Jensen",
+ "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
},
{
"display": "James Smith",
+ "$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210"
}
]
}
The following example shows how to add a member to and remove a
member from a Group in a single request:
PATCH /Groups/acbf3ae7-8463-4692-b4fd-9b4da3f908ce
Host: example.com
Accept: application/json
Content-Type: application/json
Authorization: Bearer h480djs93hd8
If-Match: W/"a330bc54f0671c9"
{
"schemas": ["urn:scim:schemas:core:1.0"],
"members": [
{
"display": "Babs Jensen",
+ "$ref": "https://example.com/v1/Users/2819c223-7f76-453a-919d-413861904646",
"value": "2819c223-7f76-453a-919d-413861904646"
"operation": "delete"
},
{
"display": "James Smith",
+ "$ref": "https://example.com/v1/Users/08e1d05d-121c-4561-8b96-473d93df9210",
"value": "08e1d05d-121c-4561-8b96-473d93df9210"
}
]
}
The following example shows how to change a User's primary email. If
the User already has the email address, it is made the primary
address and the current primary address (if present) is made non-
primary. If the User does not already have the email address, it is
added and made the primary address.
@@ -1041,28 +1178,31 @@
deleted resource in conflict calculation. For example if a User
resource is deleted, a CREATE request for a User resource with the
same userName as the previously deleted resource should not fail with
a 409 error due to userName conflict.
DELETE /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Authorization: Bearer h480djs93hd8
If-Match: W/"c310cd84f0281b7"
+ Server Response:
+
HTTP/1.1 200 OK
Example: Consumer attempt to retrieve the previously deleted User
-
GET /Users/2819c223-7f76-453a-919d-413861904646
Host: example.com
Authorization: Bearer h480djs93hd8
+ Server Response:
+
HTTP/1.1 404 NOT FOUND
{
"Errors":[
{
"description":"Resource 2819c223-7f76-453a-919d-413861904646 not found",
"code":"404"
}
]
}
@@ -1464,21 +1605,22 @@
"displayName": "Tour Guides",
"meta": {
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T20:31:02.315Z",
"location": "https://example.com/v1/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a",
"version": "W\/\"lha5bbazU3fNvfe5\""
},
"members": [
{
"value": "92b725cd-9465-4e7d-8c16-01f8e146b87a",
- "type": "user"
+ "$ref": "https://example.com/v1/Users/92b725cd-9465-4e7d-8c16-01f8e146b87a",
+ "type": "User"
}
]
}
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 /v1/Bulk
@@ -1604,40 +1746,42 @@
"displayName": "Group A",
"meta": {
"created":"2011-08-01T18:29:49.793Z",
"lastModified":"2011-08-01T18:29:51.135Z",
"location":"https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
"version":"W\/\"mvwNGaxB5SDq074p\""
},
"members": [
{
"value": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
- "type": "group"
+ "$ref": "https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
+ "type": "Group"
}
]
},
{
"id": "6c5bb468-14b2-4183-baf2-06d523e03bd3",
"schemas": [
"urn:scim:schemas:core:1.0"
],
"displayName": "Group B",
"meta": {
"created":"2011-08-01T18:29:50.873Z",
"lastModified":"2011-08-01T18:29:50.873Z",
"location":"https://example.com/v1/Groups/6c5bb468-14b2-4183-baf2-06d523e03bd3",
"version":"W\/\"wGB85s2QJMjiNnuI\""
},
"members": [
{
"value": "c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
- "type": "group"
+ "$ref": "https://example.com/v1/Groups/c3a26dd3-27a0-4dec-a2ac-ce211e105f97",
+ "type": "Group"
}
]
}
]
}
The Service Provider MUST define the maximum number of operations and
maximum payload size a Consumer may send in a single request. If
either limits are exceeded the Service Provider MUST return the HTTP
response code 413 Request Entity Too Large. The returned response
@@ -1670,60 +1814,38 @@
3.6. Data Input/Output Formats
Consumers MUST specify the format in which the data is submitted via
the HTTP header content-type 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
Host: example.com
- GET /Users/2819c223-7f76-453a-919d-413861904646.xml
- Host: example.com
-
Service Providers MUST support the Accept Headers "Accept:
- application/json" for JSON [5] and, if supported, "Accept:
- application/xml" for XML [6]. The format defaults to JSON if no
- format is specified. The data structure returned is equivalent in
- both formats; the only difference is in the encoding of the data.
+ application/json" for JSON [5]. The format defaults to JSON if no
+ format is specified.
Singular attributes are encoded as string name-value-pairs in JSON;
e.g.,
"attribute": "value"
- and elements in XML; e.g.,
-
- value
-
Multi-valued attributes in JSON are encoded as arrays; e.g.,
"attributes": [ "value1", "value2" ]
- and repeated tags in XML; e.g.,
-
- value1
- value2
-
Elements with nested elements are represented as objects in JSON;
e.g,
"attribute": { "subattribute1": "value1", "subattribute2": "value2" }
- and repeated tags in XML; e.g.,
-
-
- value1
- value2
-
-
-
3.7. Additional retrieval query parameters
Consumers MAY request a partial Resource representation on any
operation that returns a Resource within the response by specifying
the URL query parameter 'attributes'. When specified, each Resource
returned MUST contain the minimal set of Resource attributes and,
MUST contain no other attributes or Sub-Attributes 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).
@@ -1764,21 +1886,21 @@
attribute 'age' defined in 'urn:hr:schemas:user' is fully encoded as
'urn:hr:schemas:user:age'. A Complex attributes' Sub-Attributes are
referenced via nested, dot ('.') notation; i.e., {urn}:{Attribute
name}.{Sub-Attribute name}. For example, the fully qualified path
for a User's givenName is urn:scim:schemas:core:1.0:name.givenName
All facets (URN, attribute and Sub-Attribute name) of the fully
encoded Attribute name are case insensitive.
3.9. HTTP Response Codes
- The SCIM Protocol uses the response status codes defined in HTTP [7]
+ The SCIM Protocol uses the response status codes defined in HTTP [6]
to indicate operation success or failure. In addition to returning a
HTTP response code implementers MUST return the errors in the body of
the response in the client requested format containing the error
response and, per the HTTP specification, human-readable
explanations. Implementers SHOULD handle the identified errors as
described below.
+--------------+---------------------------+------------------------+
| Code | Applicability | Suggested Explanation |
+--------------+---------------------------+------------------------+
@@ -1924,42 +2047,130 @@
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. Security Considerations
+4. Multi-Tenancy
+
+ A single Service Provider may expose the SCIM protocol to multiple
+ Consumers. Depending on the nature of the service, the Consumers may
+ have authority to access and alter Resources initially created by
+ other Consumers. Alternatively, Consumers may expect to access
+ disjoint sets of Resources, and may expect that their resources are
+ inaccessible by other Consumers. These scenarios are called "multi-
+ tenancy", where each Consumer is understood to be or represent a
+ "tenant" of the Service Provider. Consumers may also be multi-
+ tenanted.
+
+ The following common cases may occur:
+
+ 1. All Consumers share all Resources (no tenancy)
+
+ 2. Each single Consumer creates and accesses a private subset of
+ Resources (1 Consumer:1 Tenant)
+
+ 3. Sets of Consumers share sets of Resources (M Consumers:1 Tenant)
+
+ 4. One Consumer to Multiple Tenants (1 Consumer:M Tenants)
+
+ Service Providers may implement any subset of the above cases.
+
+ Multi-Tenancy is OPTIONAL. The SCIM protocol does not define a
+ scheme for multi-tenancy.
+
+ The SCIM protocol does not prescribe the mechanisms whereby Consumers
+ and Service Providers interact for:
+
+ o Registering or provisioning Tenants
+
+ o Associating a subset of Consumers with a subset of the Tenants
+
+ o Indicating which tenant is associated with the data in a request
+ 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 Consumers to Tenants
+
+ The Service Provider MAY use the authentication mechanism (Section 2)
+ to determine the identity of the Consumer, and thus infer the
+ associated Tenant.
+
+ For implementations where a Consumer is associated with more than one
+ Tenant, the Service Provider MAY use one of the following methods for
+ explicit specification of the Tenant.
+
+ If any of these methods of allowing the Consumer to explicitly
+ specify the Tenant are employed, the Service Provider should ensure
+ that access controls are in place to prevent or allow cross-tenant
+ use cases.
+
+ The Service Provider should consider precedence in cases where a
+ Consumer may explicitly specify a Tenant while being implicitly
+ associated with a different Tenant.
+
+4.1.1. URL Prefix Example
+
+ https://www.example.com/Tenants/{tenant_id}/v1/Users
+
+4.1.2. Subdomain Example
+
+ https://{tenant_id}.example.com/v1/Groups
+
+4.1.3. HTTP Header
+
+ The Service Provider may recognize a {tenant_id} provided by the
+ Consumer 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
+ the Tenant as defined by the Service Provider.
+
+4.2. SCIM Identifiers with Multiple Tenants
+
+ Considerations for a Multi-Tenant Implementation:
+
+ The Service Provider may choose to implement SCIM ids which are
+ unique across all Resources for all Tenants, but this is not
+ required.
+
+ The externalId, defined by the Consumer, is required to be unique
+ ONLY within the Resources associated with the associated Tenant.
+
+5. Security Considerations
The SCIM Protocol is based on HTTP and thus subject to the security
considerations found in Section 15 of [RFC2616]. SCIM Resources
(e.g., Users and Groups) can contain sensitive information.
Therefore, SCIM Consumers and Service Providers MUST implement TLS.
Which version(s) ought to be implemented will vary over time, and
depend on the widespread deployment and known security
vulnerabilities at the time of implementation. At the time of this
- writing, TLS version 1.2 [RFC5246 [8]] is the most recent version,
+ writing, TLS version 1.2 [RFC5246 [7]] is the most recent version,
but has very limited actual deployment, and might not be readily
- available in implementation toolkits. TLS version 1.0 [RFC2246 [8]]
+ available in implementation toolkits. TLS version 1.0 [RFC2246 [7]]
is the most widely deployed version, and will give the broadest
interoperability.
-5. Contributors
+6. Contributors
Samuel Erdtman (samuel@erdtman.se)
Patrick Harding (pharding@pingidentity.com)
-6. Acknowledgments
+7. Acknowledgments
The editor would like to thank the participants in the the SCIM
working group for their support of this specification.
Authors' Addresses
Trey Drake (editor)
UnboundID
Email: trey.drake@unboundid.com