Tech-invite3GPPspaceIETF RFCsSIP
929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 7644

System for Cross-domain Identity Management: Protocol

Pages: 89
Proposed Standard
Errata
Part 1 of 4 – Pages 1 to 13
None   None   Next

Top   ToC   RFC7644 - Page 1
Internet Engineering Task Force (IETF)                      P. Hunt, Ed.
Request for Comments: 7644                                        Oracle
Category: Standards Track                                     K. Grizzle
ISSN: 2070-1721                                                SailPoint
                                                               M. Ansari
                                                                   Cisco
                                                           E. Wahlstroem
                                                        Nexus Technology
                                                            C. Mortimore
                                                              Salesforce
                                                          September 2015


         System for Cross-domain Identity Management: Protocol

Abstract

The System for Cross-domain Identity Management (SCIM) specification is an HTTP-based protocol that makes managing identities in multi- domain scenarios easier to support via a standardized service. Examples include, but are not limited to, enterprise-to-cloud service providers and inter-cloud scenarios. 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. SCIM's intent is to reduce the cost and complexity of user management operations by providing a common user schema, an extension model, and a service protocol defined by this document. Status of This Memo This is an Internet Standards Track document. This document is a product of the Internet Engineering Task Force (IETF). It represents the consensus of the IETF community. It has received public review and has been approved for publication by the Internet Engineering Steering Group (IESG). Further information on Internet Standards is available in Section 2 of RFC 5741. Information about the current status of this document, any errata, and how to provide feedback on it may be obtained at http://www.rfc-editor.org/info/rfc7644.
Top   ToC   RFC7644 - Page 2
Copyright Notice

   Copyright (c) 2015 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 .....................................4 1.3. Definitions ................................................4 2. Authentication and Authorization ................................5 2.1. Use of Tokens as Authorizations ............................7 2.2. Anonymous Requests .........................................7 3. SCIM Protocol ...................................................8 3.1. Background .................................................8 3.2. SCIM Endpoints and HTTP Methods ............................9 3.3. Creating Resources ........................................11 3.3.1. Resource Types .....................................13 3.4. Retrieving Resources ......................................13 3.4.1. Retrieving a Known Resource ........................14 3.4.2. Query Resources ....................................15 3.4.3. Querying Resources Using HTTP POST .................27 3.5. Modifying Resources .......................................29 3.5.1. Replacing with PUT .................................30 3.5.2. Modifying with PATCH ...............................32 3.6. Deleting Resources ........................................48 3.7. Bulk Operations ...........................................49 3.7.1. Circular Reference Processing ......................51 3.7.2. "bulkId" Temporary Identifiers .....................53 3.7.3. Response and Error Handling ........................58 3.7.4. Maximum Operations .................................63 3.8. Data Input/Output Formats .................................64 3.9. Additional Operation Response Parameters ..................64 3.10. Attribute Notation .......................................66 3.11. "/Me" Authenticated Subject Alias ........................66
Top   ToC   RFC7644 - Page 3
      3.12. HTTP Status and Error Response Handling ..................67
      3.13. SCIM Protocol Versioning .................................71
      3.14. Versioning Resources .....................................71
   4. Service Provider Configuration Endpoints .......................73
   5. Preparation and Comparison of Internationalized Strings ........76
   6. Multi-Tenancy ..................................................76
      6.1. Associating Clients to Tenants ............................77
      6.2. SCIM Identifiers with Multiple Tenants ....................78
   7. Security Considerations ........................................78
      7.1. HTTP Considerations .......................................78
      7.2. TLS Support Considerations ................................78
      7.3. Authorization Token Considerations ........................78
      7.4. Bearer Token and Cookie Considerations ....................79
      7.5. Privacy Considerations ....................................79
           7.5.1. Personal Information ...............................79
           7.5.2. Disclosure of Sensitive Information in URIs ........80
      7.6. Anonymous Requests ........................................80
      7.7. Secure Storage and Handling of Sensitive Data .............81
      7.8. Case-Insensitive Comparison and International Languages ...82
   8. IANA Considerations ............................................82
      8.1. Media Type Registration ...................................82
      8.2. Registering URIs for SCIM Messages ........................84
   9. References .....................................................85
      9.1. Normative References ......................................85
      9.2. Informative References ....................................87
   Acknowledgements ..................................................88
   Contributors ......................................................88
   Authors' Addresses ................................................89

1. Introduction and Overview

The SCIM protocol is an application-level HTTP-based protocol for provisioning and managing identity data on the web and in cross-domain environments such as enterprise-to-cloud service providers or inter-cloud scenarios. The protocol supports creation, modification, retrieval, and discovery of core identity resources such as Users and Groups, as well as custom resources and resource extensions. The definition of resources, attributes, and overall schema are defined in the SCIM Core Schema document [RFC7643].

1.1. Intended Audience

This document is intended to serve as a guide to SCIM protocol usage for both SCIM HTTP service providers and HTTP clients who may provision information to service providers or retrieve information from them.
Top   ToC   RFC7644 - Page 4

1.2. Notational Conventions

The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. These key words are capitalized when used to unambiguously specify requirements of the protocol or application features and behavior that affect the interoperability and security of implementations. When these words are not capitalized, they are meant in their natural-language sense. For purposes of readability, examples are not URL encoded. Implementers MUST percent-encode URLs as described in Section 2.1 of [RFC3986]. Throughout this document, figures may contain spaces and extra line wrapping to improve readability and accommodate space limitations. Similarly, some URIs contained within examples have been shortened for space and readability reasons (as indicated by "...").

1.3. Definitions

This specification uses the definitions from [RFC7643] and defines the following additional term: Base URI The SCIM HTTP protocol is described in terms of a path relative to a Base URI. The Base URI MUST NOT contain a query string, as clients MAY append additional path information and query parameters as part of forming the request. The base URI is a URL that most often consists of the "https" protocol scheme, a domain name, and some initial path [RFC3986]. For example: "https://example.com/scim/" For readability, all examples in this document assume that the SCIM service root and the server root are the same (no path prefix). It is expected that SCIM servers may be deployed using any URI path prefix. For example, a SCIM server might have a prefix of "https://example.com/" or "https://example.com/scim/tenancypath/". Additionally, a client MAY apply a version number to the server root prefix (see Section 3.13).
Top   ToC   RFC7644 - Page 5

2. Authentication and Authorization

The SCIM protocol is based upon HTTP and does not itself define a SCIM-specific scheme for authentication and authorization. SCIM depends on the use of Transport Layer Security (TLS) and/or standard HTTP authentication and authorization schemes as per [RFC7235]. For example, the following methodologies could be used, among others: TLS Client Authentication The SCIM service provider MAY request TLS client authentication (also known as mutual authentication). See Section 7.3 of [RFC5246]. HOBA Authentication HTTP Origin-Bound Authentication (HOBA) is a variation on TLS client authentication and uses a digital-signature-based design for an HTTP authentication method (see [RFC7486]). The design can also be used in JavaScript-based authentication embedded in HTML. HOBA is an alternative to HTTP authentication schemes that require passwords and therefore avoids all problems related to passwords, such as leakage of server-side password databases. Bearer Tokens Bearer tokens [RFC6750] MAY be used when combined with TLS and a token framework such as OAuth 2.0 [RFC6749]. Tokens that are issued based on weak or no authentication of authorizing users and/or OAuth clients SHOULD NOT be used, unless, for example, they are being used as single-use tokens to permit one-time requests such as anonymous registration (see Section 3.3). For security considerations regarding the use of bearer tokens in SCIM, see Section 7.4. While bearer tokens most often represent an authorization, it is assumed that the authorization was based upon a successful authentication of the SCIM client. Accordingly, the SCIM service provider must have a method for validating, parsing, and/or "introspecting" the bearer token for the relevant authentication and authorization information. The method for this is assumed to be defined by the token-issuing system and is beyond the scope of this specification. PoP Tokens A proof-of-possession (PoP) token demonstrates that the presenter of the token possesses a particular key and that the recipient can cryptographically confirm proof of possession of the key by the presenter. This property is sometimes also described as the presenter being a holder of the key. See [OAuth-PoP-Arch] for an example of such a token and its use.
Top   ToC   RFC7644 - Page 6
   Cookies
      JavaScript clients MAY assert HTTP cookies over TLS that contain
      an authentication state that is understood by the SCIM service
      provider (see [RFC6265]).  An example of this is scenarios where
      web-form authentication has taken place with the user and HTTP
      cookies were set representing the authentication state.  For the
      purposes of SCIM, the security considerations in Section 7.4
      apply.

   Basic Authentication
      Usage of basic authentication should be avoided, due to its use of
      a single factor that is based upon a relatively static, symmetric
      secret.  Implementers SHOULD combine the use of basic
      authentication with other factors.  The security considerations of
      HTTP Basic are well documented in [HTTP-BASIC-AUTH]; therefore,
      implementers are encouraged to use stronger authentication
      methods.  Designating the specific methods of authentication and
      authorization is out of scope for SCIM; however, this information
      is provided as a resource to implementers.

   As per Section 4.1 of [RFC7235], a SCIM service provider SHALL
   indicate supported HTTP authentication schemes via the
   "WWW-Authenticate" header.

   Regardless of methodology, the SCIM service provider MUST be able to
   map the authenticated client to an access control policy in order to
   determine the client's authorization to retrieve and update SCIM
   resources.  For example, while a browser session may have been
   established via HTTP cookie or TLS client authentication, the unique
   client MUST be mapped to a security subject (e.g., User).  The
   authorization model and the process by which this is done are beyond
   the scope of this specification.

   When processing requests, the service provider SHOULD consider the
   subject performing the request and whether or not the action is
   appropriate given the subject and the resource affected by the
   request.  The subject performing the request is usually determined
   directly or indirectly from the "Authorization" header present in the
   request.  For example, a subject MAY be permitted to retrieve and
   update their own "User" resource but will normally have restricted
   ability to access resources associated with other Users.  In other
   cases, the SCIM service provider might only grant access to a
   subject's own associated "User" resource (e.g., for the purpose of
   updating personal contact attributes).
Top   ToC   RFC7644 - Page 7
   For illustrative purposes only, SCIM protocol examples show an
   OAuth 2.0 bearer token value [RFC6750] in the authorization
   header, e.g.,

   GET /Users/2819c223-7f76-453a-919d-413861904646 HTTP/1.1
   Host: example.com
   Authorization: Bearer h480djs93hd8

   This is not intended to imply that bearer tokens are preferred.
   However, the use of bearer tokens in the specification does reflect
   common implementation practice.

2.1. Use of Tokens as Authorizations

When using bearer tokens or PoP tokens that represent an authorization grant, such as a grant issued by OAuth (see [RFC6749]), implementers SHOULD consider the type of authorization granted, any authorized scopes (see Section 3.3 of [RFC6749]), and the security subject(s) that SHOULD be mapped from the authorization when considering local access control rules. Section 6 of [RFC7521] documents common scenarios for authorization, including: o A client using an assertion to authenticate and/or act on behalf of itself, o A client acting on behalf of a user, and o A client acting on behalf of an anonymous user (for example, see Section 2.2). When using OAuth authorization tokens, implementers MUST take into account the threats and countermeasures related to the use of client authorizations, as documented in Section 8 of [RFC7521]. When using other token formats or frameworks, implementers MUST take into account similar threats and countermeasures, especially those documented by the relevant specifications.

2.2. Anonymous Requests

In some SCIM deployments, it MAY be acceptable to permit unauthenticated (anonymous) requests -- for example, a user self-registration request where the service provider chooses to accept a SCIM Create request (see Section 3.3) from an anonymous client. See Section 7.6 for security considerations regarding anonymous requests.
Top   ToC   RFC7644 - Page 8

3. SCIM Protocol

3.1. Background

SCIM is a protocol that is based on HTTP [RFC7230]. Along with HTTP headers and URIs, SCIM uses JSON [RFC7159] payloads to convey SCIM resources, as well as protocol-specific payload messages that convey request parameters and response information such as errors. Both resources and messages are passed in the form of JSON-based structures in the message body of an HTTP request or response. To identify this content, SCIM uses a media type of "application/scim+json" (see Section 8.1). A SCIM "resource" is a JSON object [RFC7159] that may be created, maintained, and retrieved via HTTP request methods as described in this document. Each JSON resource representation contains a "schemas" attribute that contains a list of one or more URIs that indicate included SCIM schemas that are used to indicate the attributes contained within a resource. Specific information about what attributes are defined within a schema MAY be obtained by querying a SCIM service provider's "/Schemas" endpoint for a schema definition (see Section 8.7 of [RFC7643]). Responses from this endpoint describe the schema supported by a service provider, including attribute characteristics such as cardinality, case-exactness, mutability, uniqueness, returnability, and whether or not attributes are required. While SCIM schemas and an associated extension model are defined in [RFC7643], SCIM clients should expect that some attribute schema may change from service provider to service provider, particularly across administrative domains. In cases where SCIM may be used as an open protocol in front of an application service, it is quite reasonable to expect that some service providers may only support a subset of the schema defined in [RFC7643]. A SCIM message conveys protocol parameters related to a SCIM request or response; this specification defines these parameters. As with a SCIM resource, a SCIM message is a JSON object [RFC7159] that contains a "schemas" attribute with a URI whose namespace prefix MUST begin with "urn:ietf:params:scim:api:". As SCIM protocol messages are fixed and defined by SCIM specifications and registered extensions, SCIM message schemas using the above prefix URN SHALL NOT be discoverable using the "/Schemas" endpoint. As SCIM is intended for use in cross-domain scenarios where schema and implementations may vary, techniques such as document validation (e.g., [XML-Schema]) are not recommended. A SCIM service provider interprets a request in the context of its own schema (which may be different from the client's schema) and following the defined
Top   ToC   RFC7644 - Page 9
   processing rules for each request.  The sections that follow define
   the processing rules for SCIM and provide allowances for schema
   differences where appropriate.  For example, in a SCIM PUT request,
   "readOnly" attributes are ignored, while "readWrite" attributes are
   updated.  There is no need for a SCIM client to discover which
   attributes are "readOnly", and the client does not need to remove
   them from a PUT request in order to be accepted.  Similarly, a SCIM
   client SHOULD NOT expect a service provider to return SCIM resources
   with exactly the same schema and values as submitted.  SCIM responses
   SHALL reflect resource state as interpreted by the SCIM service
   provider.

3.2. SCIM Endpoints and HTTP Methods

The SCIM protocol specifies well-known endpoints and HTTP methods for managing resources defined in the SCIM Core Schema document ([RFC7643]); i.e., "User" and "Group" resources correspond to "/Users" and "/Groups", respectively. Service providers that support extended resources SHOULD define resource endpoints using the convention of pluralizing the resource name defined in the extended schema, by appending an 's'. Given that there are cases where resource pluralization is ambiguous, e.g., a resource named "Person" is legitimately "Persons" and "People", clients SHOULD discover resource endpoints via the "/ResourceTypes" endpoint. HTTP SCIM Usage Method ------ -------------------------------------------------------------- GET Retrieves one or more complete or partial resources. POST Depending on the endpoint, creates new resources, creates a search request, or MAY be used to bulk-modify resources. PUT Modifies a resource by replacing existing attributes with a specified set of replacement attributes (replace). PUT MUST NOT be used to create new resources. PATCH Modifies a resource with a set of client-specified changes (partial update). DELETE Deletes a resource. Table 1: SCIM HTTP Methods
Top   ToC   RFC7644 - Page 10
   Resource Endpoint         Operations             Description
   -------- ---------------- ---------------------- --------------------
   User     /Users           GET (Section 3.4.1),   Retrieve, add,
                             POST (Section 3.3),    modify Users.
                             PUT (Section 3.5.1),
                             PATCH (Section 3.5.2),
                             DELETE (Section 3.6)

   Group    /Groups          GET (Section 3.4.1),   Retrieve, add,
                             POST (Section 3.3),    modify Groups.
                             PUT (Section 3.5.1),
                             PATCH (Section 3.5.2),
                             DELETE (Section 3.6)

   Self     /Me              GET, POST, PUT, PATCH, Alias for operations
                             DELETE (Section 3.11)  against a resource
                                                    mapped to an
                                                    authenticated
                                                    subject (e.g.,
                                                    User).

   Service  /ServiceProvider GET (Section 4)        Retrieve service
   provider Config                                  provider's
   config.                                          configuration.

   Resource /ResourceTypes   GET (Section 4)        Retrieve supported
   type                                             resource types.

   Schema   /Schemas         GET (Section 4)        Retrieve one or more
                                                    supported schemas.

   Bulk     /Bulk            POST (Section 3.7)     Bulk updates to one
                                                    or more resources.

   Search   [prefix]/.search POST (Section 3.4.3)   Search from system
                                                    root or within a
                                                    resource endpoint
                                                    for one or more
                                                    resource types using
                                                    POST.

                        Table 2: Defined Endpoints
Top   ToC   RFC7644 - Page 11
   All requests to the service provider are made via HTTP methods as per
   Section 4.3 of [RFC7231] on a URL derived from the Base URL.
   Responses are returned in the body of the HTTP response, formatted as
   JSON.  Error status 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 (see Section 3.12).

3.3. Creating Resources

To create new resources, clients send HTTP POST requests to the resource endpoint, such as "/Users" or "/Groups", as defined by the associated resource type endpoint discovery (see Section 4). The server SHALL process attributes according to the following mutability rules: o In the request body, attributes whose mutability is "readOnly" (see Sections 2.2 and 7 of [RFC7643]) SHALL be ignored. o Attributes whose mutability is "readWrite" (see Section 2.2 of [RFC7643]) and that are omitted from the request body MAY be assumed to be not asserted by the client. The service provider MAY assign a default value to non-asserted attributes in the final resource representation. o Service providers MAY take into account whether or not a client has access to all of the resource's attributes when deciding whether or not non-asserted attributes should be defaulted. o Clients that intend to override existing or server-defaulted values for attributes MAY specify "null" for a single-valued attribute or an empty array "[]" for a multi-valued attribute to clear all values. When the service provider successfully creates the new resource, an HTTP response SHALL be returned with HTTP status code 201 (Created). The response body SHOULD contain the service provider's representation of the newly created resource. The URI of the created resource SHALL include, in the HTTP "Location" header and the HTTP body, a JSON representation [RFC7159] with the attribute "meta.location". Since the server is free to alter and/or ignore POSTed content, returning the full representation can be useful to the client, enabling it to correlate the client's and server's views of the new resource.
Top   ToC   RFC7644 - Page 12
   If the service provider determines that the creation of the requested
   resource conflicts with existing resources (e.g., a "User" resource
   with a duplicate "userName"), the service provider MUST return HTTP
   status code 409 (Conflict) with a "scimType" error code of
   "uniqueness", as per Section 3.12.

   In the following example, a client sends a POST request containing a
   "User" to the "/Users" endpoint.

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

   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     "userName":"bjensen",
     "externalId":"bjensen",
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara"
     }
   }
Top   ToC   RFC7644 - Page 13
   In response to the example request above, the server signals a
   successful creation with an HTTP status code 201 (Created) and
   returns a representation of the resource created:

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

   {
     "schemas":["urn:ietf:params:scim:schemas:core:2.0:User"],
     "id":"2819c223-7f76-453a-919d-413861904646",
     "externalId":"bjensen",
     "meta":{
       "resourceType":"User",
       "created":"2011-08-01T21:32:44.882Z",
       "lastModified":"2011-08-01T21:32:44.882Z",
       "location":
   "https://example.com/v2/Users/2819c223-7f76-453a-919d-413861904646",
       "version":"W\/\"e180ee84f0671b1\""
     },
     "name":{
       "formatted":"Ms. Barbara J Jensen III",
       "familyName":"Jensen",
       "givenName":"Barbara"
     },
     "userName":"bjensen"
   }

3.3.1. Resource Types

When adding a resource to a specific endpoint, the meta attribute "resourceType" SHALL be set by the HTTP service provider to the corresponding resource type for the endpoint. For example, a POST to the endpoint "/Users" will set "resourceType" to "User", and "/Groups" will set "resourceType" to "Group".


(page 13 continued on part 2)

Next Section