--- 1/draft-ietf-scim-core-schema-03.txt 2014-04-28 21:14:20.932035839 -0700 +++ 2/draft-ietf-scim-core-schema-04.txt 2014-04-28 21:14:21.032038246 -0700 @@ -1,23 +1,23 @@ Network Working Group K. Grizzle Internet-Draft SailPoint Intended status: Standards Track P. Hunt, Ed. -Expires: August 16, 2014 Oracle +Expires: October 30, 2014 Oracle E. Wahlstroem Technology Nexus C. Mortimore Salesforce - February 12, 2014 + April 28, 2014 System for Cross-Domain Identity Management: Core Schema - draft-ietf-scim-core-schema-03 + draft-ietf-scim-core-schema-04 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 builds upon experience with existing schemas and deployments, placing specific emphasis on simplicity of development and integration, while applying existing authentication, authorization, and privacy models. Its intent is to reduce the cost and complexity of user management @@ -39,21 +39,21 @@ 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 August 16, 2014. + This Internet-Draft will expire on October 30, 2014. Copyright Notice Copyright (c) 2014 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 @@ -63,56 +63,56 @@ the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Table of Contents 1. Requirements Notation and Conventions . . . . . . . . . . . . 3 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . 3 2.1. Definitions . . . . . . . . . . . . . . . . . . . . . . . 4 3. SCIM Schema Structure . . . . . . . . . . . . . . . . . . . . 4 3.1. Attribute Data Types . . . . . . . . . . . . . . . . . . 5 - 3.1.1. String . . . . . . . . . . . . . . . . . . . . . . . 5 + 3.1.1. String . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.2. Boolean . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.3. Decimal . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.4. Integer . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.5. DateTime . . . . . . . . . . . . . . . . . . . . . . 6 3.1.6. Binary . . . . . . . . . . . . . . . . . . . . . . . 6 3.1.7. Reference . . . . . . . . . . . . . . . . . . . . . . 6 3.1.8. Complex . . . . . . . . . . . . . . . . . . . . . . . 7 3.2. Multi-valued Attributes . . . . . . . . . . . . . . . . . 7 4. Schema Extension Model . . . . . . . . . . . . . . . . . . . 8 5. SCIM Core Schema . . . . . . . . . . . . . . . . . . . . . . 8 5.1. Common Schema Attributes . . . . . . . . . . . . . . . . 8 - 5.2. "schemas" Attribute . . . . . . . . . . . . . . . . . . . 10 + 5.2. "schemas" Attribute . . . . . . . . . . . . . . . . . . . 9 6. SCIM User Schema . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Singular Attributes . . . . . . . . . . . . . . . . . . . 10 6.2. Multi-valued Attributes . . . . . . . . . . . . . . . . . 12 - 7. SCIM Enterprise User Schema Extension . . . . . . . . . . . . 14 + 7. SCIM Enterprise User Schema Extension . . . . . . . . . . . . 15 8. SCIM Group Schema . . . . . . . . . . . . . . . . . . . . . . 15 9. Service Provider Configuration Schema . . . . . . . . . . . . 16 - 10. ResourceType Schema . . . . . . . . . . . . . . . . . . . . . 17 - 11. Schema Schema . . . . . . . . . . . . . . . . . . . . . . . . 18 + 10. ResourceType Schema . . . . . . . . . . . . . . . . . . . . . 18 + 11. Schema Schema . . . . . . . . . . . . . . . . . . . . . . . . 19 12. JSON Representation . . . . . . . . . . . . . . . . . . . . . 23 12.1. Minimal User Representation . . . . . . . . . . . . . . 23 - 12.2. Full User Representation . . . . . . . . . . . . . . . . 23 + 12.2. Full User Representation . . . . . . . . . . . . . . . . 24 12.3. Enterprise User Extension Representation . . . . . . . . 26 12.4. Group Representation . . . . . . . . . . . . . . . . . . 29 12.5. Service Provider Configuration Representation . . . . . 30 12.6. Resource Type Representation . . . . . . . . . . . . . . 31 - 12.7. Schema Representation . . . . . . . . . . . . . . . . . 31 - 13. Security Considerations . . . . . . . . . . . . . . . . . . . 53 - 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 53 - 14.1. Normative References . . . . . . . . . . . . . . . . . . 53 - 14.2. Informative References . . . . . . . . . . . . . . . . . 54 - Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 54 - Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 55 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 55 + 12.7. Schema Representation . . . . . . . . . . . . . . . . . 32 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 54 + 14. References . . . . . . . . . . . . . . . . . . . . . . . . . 54 + 14.1. Normative References . . . . . . . . . . . . . . . . . . 54 + 14.2. Informative References . . . . . . . . . . . . . . . . . 55 + Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 55 + Appendix B. Change Log . . . . . . . . . . . . . . . . . . . . . 56 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 57 1. Requirements Notation and 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] . Throughout this document, values are quoted to indicate that they are to be taken literally. When using these values in protocol messages, the quotes MUST NOT be used as part of the value. @@ -194,27 +194,34 @@ at least one simple or complex value either of which may be multi- valued. SCIM schema defines the data type, plurality and other distinguishing features of an attribute. Unless otherwise specified all attributes are modifiable by consumers. Attribute definitions contain a property "mutability" that determines whether an attribute is: "readOnly", "writeOnly", "immutable", or "readWrite"(the default). Additionally, service providers MAY define other properties such as returnability Resource's schema endpoint (Section 5.2). - A JSON (JavaScript Object Notation) format [RFC4627] is defined. - Attribute names SHOULD be camelCased. SCIM resources represented in - JSON MUST specify schema via the "schemas" attributeSection 5.2. + Attribute names SHOULD be camelCased. SCIM resources are represented + in JSON [RFC7159] and MUST specify schema via the "schemas" attribute + per Section 5.2. + + Attribute names MUST conform to the following ABNF [RFC5234] rules: + + ATTRNAME = ALPHA *(nameChar) + nameChar = "-" / "_" / DIGIT / ALPHA + + Figure 1 3.1. Attribute Data Types - Attribute data types are derived from JSON [RFC4627] and unless + Attribute data types are derived from JSON [RFC7159] and unless otherwise specified have the following characteristics (see Section 11 for attribute characteristic definitions): are optional ("required=false"). are case insensitive ("caseExact=false"), are modifiable ("mutability=readWrite"), are returned in response to queries ("returned=default"), @@ -224,58 +231,58 @@ of type String (Section 3.1.1). The JSON format defines a limited set of data types, hence, where appropriate, alternate JSON representations derived from XML Schema [XML-Schema] are defined below. SCIM extensions SHOULD NOT introduce new data types. 3.1.1. String A sequence of zero or more Unicode characters. The JSON format is - defined in Section 2.5 [RFC4627] . A "String" attribute MAY specify a + defined in Section 7 [RFC7159] . A "String" attribute MAY specify a required data format. Additionally, when canonical values are specified service providers SHOULD conform to those values if appropriate, but MAY provide alternate "String" values to represent additional values. 3.1.2. Boolean The literal "true" or "false". The JSON format is defined in - Section 2.1 [RFC4627] . + Section 3 [RFC7159] . 3.1.3. Decimal A real number with at least one digit to the left and right of the - period. The JSON format is defined in Section 2.4 [RFC4627] . + period. The JSON format is defined in Section 6 [RFC7159] . 3.1.4. Integer A decimal number with no fractional digits. The JSON format is - defined in Section 2.4 [RFC4627] with the additional constraint that + defined in Section 6 [RFC7159] with the additional constraint that the value MUST NOT contain fractionial or exponent parts. 3.1.5. DateTime A DateTime value (e.g. 2008-01-23T04:56:22Z). The attribute value MUST be encoded as a valid xsd:dateTime as specified in Section 3.2.7 [XML-Schema] . Values represented in JSON MUST conform to the XML constraints above - and are represented as a JSON String per Section 2.5 [RFC4627]. + and are represented as a JSON String per Section 7 [RFC7159]. 3.1.6. Binary Arbitrary binary data. The attribute value MUST be encoded as a valid xsd:base64Binary as specified in Section 3.2.16 [XML-Schema] . Values represented in JSON MUST conform to the XML constraints above - and are represented as a JSON String perSection 2.5 [RFC4627]. + and are represented as a JSON String perSection 2.7 [RFC7159]. 3.1.7. Reference A reference to a SCIM resource. The value MUST be the absolute or relative URI of the target resource. Relative URIs should be resolved as specified in Section 5.2 [RFC3986]. The base URI for relative URI resolution MUST include all URI components and path segments up to but not including the Endpoint URI; e.g., the base URI for a request to "https://example.com/v2/Users/2819c223-7f76-453a- 919d-413861904646" would be "https://example.com/v2/" and the @@ -288,21 +295,21 @@ references. By convention, a reference is commonly represented as a "$ref" sub- attribute in complex or multi-valued attributes, however this is OPTIONAL. 3.1.8. Complex A singular or multi-valued attribute whose value is a composition of one or more simple Attributes. The JSON format is defined in - Section 2.2 [RFC4627] . + Section 4 [RFC7159] . 3.2. Multi-valued Attributes Multi-valued attributes are unordered lists of attributes. Each attribute MAY contain Sub-Attributes and therefore multi-valued attributes may contain complex attributes. The sub-attributes below are considered normative and when specified SHOULD be used as defined. type A label indicating the attribute's function; e.g., "work" or @@ -314,35 +321,21 @@ "true" MUST appear no more than once. display A human readable name, primarily used for display purposes and has a mutability of "immutable". operation The operation to perform on the multi-valued attribute during a PATCH request. The only valid value is "delete", which signifies that this instance should be removed from the resource. value The attribute's significant value; e.g., the e-mail address, - phone number, etc. Attributes that define a "value" sub-attribute - MAY be alternately represented as a collection of primitive types. - For example: - - { - "emails": [ - {"value":"bjensen@example.com"}, - {"value":"babs@example.com"} - ] - } - May also be represented as: - - { - "emails": ["bjensen@example.com","babs@example.com"] - } + phone number, etc. $ref The reference URI of the target resource, if the attribute is a reference. When returning multi-valued attributes, service providers SHOULD canonicalize the value returned, if appropriate (e.g. for e-mail addresses and URLs). Service providers MAY return the same value more than once with different types (e.g. the same e-mail address may used for work and home), but SHOULD NOT return the same (type, value) combination more than once per Attribute, as this complicates @@ -508,35 +501,56 @@ profileUrl A fully qualified URL to a page representing the user's online profile. title The user's title, such as "Vice President". userType Used to identify the organization to user relationship. Typical values used might be "Contractor", "Employee", "Intern", "Temp", "External", and "Unknown" but any value may be used. preferredLanguage Indicates the user's preferred written or spoken - language. Generally used for selecting a localized User - interface. Valid values are concatenation of the ISO 639-1 two - letter language code per [ISO639-2], an underscore, and the ISO - 3166-1 2 letter country code[ISO3166]; e.g., 'en_US' specifies the - language English and country US. + languages and is generally used for selecting a localized User + interface. The value indicates the set of natural languages that + are preferred. The format of the value is same as the Accept- + Language header field (not including "Accept-Language:") of HTTP + and is specified in Section 5.3.5 of + [I-D.ietf-httpbis-p2-semantics]. The intent of this value is to + enable cloud applications to perform matching of language tags + [RFC4647] to the user's language preferences regardless of what + may be indicated by a user agent (which might be shared), or in a + non-user present interaction (such as in a delegated OAuth2 + [RFC6749] style interaction) where normal HTTP Accept-Language + header negotiation cannot take place. locale Used to indicate the User's default location for purposes of localizing items such as currency, date time format, numerical - representations, etc. A locale value is a concatenation of the - ISO 639-1 two letter language code[ISO639-2], an underscore, and - the ISO 3166-1 2 letter country code[ISO3166]; e.g., 'en_US' - specifies the language English and country US. + representations, etc. A valid value is a language tag as defined + in [RFC5646]. Computer languages are explicitly excluded. - timezone The User's time zone in the "Olson" timezone database - format[Olson-TZ]; e.g.,'America/Los_Angeles'. + A language tag is a sequence of one or more case-insensitive + subtags, each separated by a hyphen character ("-", %x2D). For + backwards compatibility reasons, servers MAY accept tags separated + by an underscore character ("_", %5F). In most cases, a language + tag consists of a primary language subtag that identifies a broad + family of related languages (e.g., "en" = English) which is + optionally followed by a series of subtags that refine or narrow + that language's range (e.g., "en-CA" = the variety of English as + communicated in Canada). Whitespace is not allowed within a + language tag. Example tags include: + + fr, en-US, es-419, az-Arab, x-pig-latin, man-Nkoo-GN + + See [RFC5646] for further information. + + timezone The User's time zone in IANA Time Zone database format + [RFC6557], also known as "Olson" timezone database + format[Olson-TZ]; For example: "America/Los_Angeles". active A Boolean value indicating the user's administrative status. The definitive meaning of this attribute is determined by the service provider. As a typical example, a value of true infers the user is able to login while a value of false implies the user's account has been suspended. password The user's clear text password. This attribute is intended to be used as a means to specify an initial password when creating a new User or to reset an existing User's password. Password @@ -646,21 +660,21 @@ x509Certificates A list of certificates issued to the User. Values are Binary (Section 3.1.6) and DER encoded x509. This value has NO canonical types. 7. SCIM Enterprise User Schema Extension The following SCIM extension defines attributes commonly used in representing users that belong to, or act on behalf of a business or enterprise. The enterprise user extension is identified using the following schema URI: - "urn:scim:schemas:extension:enterprise:2.0:User". + "urn:scim:schemas:extension:enterprise:2.0:EnterpriseUser". The following Singular Attributes are defined: employeeNumber Numeric or alphanumeric identifier assigned to a person, typically based on order of hire or association with an organization. costCenter Identifies the name of a cost center. organization Identifies the name of an organization. @@ -886,31 +900,31 @@ required A Boolean value that specifies if the attribute is required. caseExact A Boolean value that specifies if the String attribute is case sensitive. mutability A single keyword indicating what types of modifications an attribute MAY accept as follows: - readOnly The attribute MAY NOT be modified. + readOnly The attribute SHALL NOT be modified. readWrite The attribute MAY be updated and read at any time. DEFAULT. immutable The attribute MAY be defined at resource creation (e.g. POST) or at record replacement via request (e.g. a - PUT). The attribute MAY NOT be updated. + PUT). The attribute SHALL NOT be updated. writeOnly The attribute MAY be updated at any time. Attribute - values MAY NOT be returned (e.g. because the value is a + values SHALL NOT be returned (e.g. because the value is a stored hash). Note: an attribute with mutability of "writeOnly" usually also has a returned setting of "never". returned A single keyword that indicates when an attribute and associated values are returned in response to a GET request or in response to a PUT, POST, or PATCH request. Valid keywords are: always The attribute is always returned regardless of the contents of the "attributes" parameter. For example, "id" @@ -1148,22 +1162,22 @@ "value": "https://photos.example.com/profilephoto/72930000000Ccne/F", "type": "photo" }, { "value": "https://photos.example.com/profilephoto/72930000000Ccne/T", "type": "thumbnail" } ], "userType": "Employee", "title": "Tour Guide", - "preferredLanguage":"en_US", - "locale": "en_US", + "preferredLanguage":"en-US", + "locale": "en-US", "timezone": "America/Los_Angeles", "active":true, "password":"t1meMa$heen", "groups": [ { "value": "e9e30dba-f08f-4109-8486-d5c6a331660a", "$ref": "https://example.com/v2/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "display": "Tour Guides" }, { @@ -1283,22 +1297,22 @@ "value": "https://photos.example.com/profilephoto/72930000000Ccne/F", "type": "photo" }, { "value": "https://photos.example.com/profilephoto/72930000000Ccne/T", "type": "thumbnail" } ], "userType": "Employee", "title": "Tour Guide", - "preferredLanguage":"en_US", - "locale": "en_US", + "preferredLanguage":"en-US", + "locale": "en-US", "timezone": "America/Los_Angeles", "active":true, "password":"t1meMa$heen", "groups": [ { "value": "e9e30dba-f08f-4109-8486-d5c6a331660a", "$ref": "/Groups/e9e30dba-f08f-4109-8486-d5c6a331660a", "display": "Tour Guides" }, { @@ -2517,58 +2533,78 @@ The SCIM Core schema contains personally identifiable information as well as other sensitive data. Aside from prohibiting password values in a SCIM response this specification does not provide any means or guarantee of confidentiality. 14. References 14.1. Normative References - [ISO3166] "ISO 3166:1988 (E/F) - Codes for the representation of - names of countries - The International Organization for - Standardization, 3rd edition", 08 1988. - - [ISO639-2] - ISO 639.2 Registration Authority, "ISO639-2: Codes for the - Representation of Names of Languages", July 2013. - - [Olson-TZ] - "Sources for Time Zone and Daylight Saving Time Data", . + [I-D.ietf-httpbis-p2-semantics] + Fielding, R. and J. Reschke, "Hypertext Transfer Protocol + (HTTP/1.1): Semantics and Content", draft-ietf- + httpbis-p2-semantics-25 (work in progress), November 2013. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3966] Schulzrinne, H., "The tel URI for Telephone Numbers", RFC 3966, December 2004. [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", STD 66, RFC 3986, January 2005. - [RFC4627] Crockford, D., "The application/json Media Type for - JavaScript Object Notation (JSON)", RFC 4627, July 2006. + [RFC4647] Phillips, A. and M. Davis, "Matching of Language Tags", + BCP 47, RFC 4647, September 2006. + + [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax + Specifications: ABNF", STD 68, RFC 5234, January 2008. + + [RFC5646] Phillips, A. and M. Davis, "Tags for Identifying + Languages", BCP 47, RFC 5646, September 2009. + + [RFC6557] Lear, E. and P. Eggert, "Procedures for Maintaining the + Time Zone Database", BCP 175, RFC 6557, February 2012. + + [RFC7159] Bray, T., "The JavaScript Object Notation (JSON) Data + Interchange Format", RFC 7159, March 2014. [XML-Schema] Biron, P. and A. Malhotra, "XML Schema Part 2: Datatypes Second Edition", October 2004. 14.2. Informative References + [ISO3166] "ISO 3166:1988 (E/F) - Codes for the representation of + names of countries - The International Organization for + Standardization, 3rd edition", 08 1988. + + [ISO639-2] + ISO 639.2 Registration Authority, "ISO639-2: Codes for the + Representation of Names of Languages", July 2013. + + [Olson-TZ] + "Sources for Time Zone and Daylight Saving Time Data", . + [PortableContacts] Smarr, J., "Portable Contacts 1.0 Draft C - Schema Only", August 2008. [RFC4512] Zeilenga, K., "Lightweight Directory Access Protocol (LDAP): Directory Information Models", RFC 4512, June 2006. + [RFC6749] Hardt, D., "The OAuth 2.0 Authorization Framework", RFC + 6749, October 2012. + Appendix A. Acknowledgements The editors would like to acknowledge the contribution and work of the past draft editors: Chuck Mortimore, Salesforce Patrick Harding, Ping Paul Madsen, Ping @@ -2615,26 +2652,42 @@ 53 - Standard use of term client (some was consumer) 56 - Make manager attribute consistent with other $ref attrs 58 - Add optional id to ResourceType objects for consistency 59 - Fix capitalization per IETF editor practices 60 - Changed tags to normal and tags + Draft 04 - PH - Revisions based on the following tickets: + + 43 - Drop short-hand notation for complex multi-valued attributes + + 61 - Specify attribute name limitations + + 62 - Fix 'mutability' normative language + + 63 - Fix incorrect EnterpriseUser schema reference + + 68 - Update JSON references from RFC4627 to RFC7159 + + 71 - Made corrections to language tags in compliance with BCP47 / + RFC5646 + Authors' Addresses Kelly Grizzle SailPoint Email: kelly.grizzle@sailpoint.com + Phil Hunt (editor) Oracle Corporation Email: phil.hunt@yahoo.com Erik Wahlstroem Technology Nexus Email: erik.wahlstrom@nexussafe.com