Draft D. Hardt Sxip Identity November 29, 2006 OpenID Attribute Exchange 1.0 - Draft 03 Hardt [Page 1] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 Abstract OpenID Attribute Exchange is an OpenID service for exchanging identity information between endpoints. Messages for retrieval and storage of identity information are provided. Table of Contents 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Definitions and Conventions . . . . . . . . . . . . . . . 3 2. Overview . . . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Information Model . . . . . . . . . . . . . . . . . . . . . . 5 3.1. Subject Identifier . . . . . . . . . . . . . . . . . . . . 5 3.2. Attribute Type Identifier . . . . . . . . . . . . . . . . 5 3.3. Attribute Value . . . . . . . . . . . . . . . . . . . . . 5 4. Discovery . . . . . . . . . . . . . . . . . . . . . . . . . . 6 5. Fetch Message . . . . . . . . . . . . . . . . . . . . . . . . 7 5.1. Fetch Request Format . . . . . . . . . . . . . . . . . . . 7 5.2. Fetch Response Format . . . . . . . . . . . . . . . . . . 8 6. Store Message . . . . . . . . . . . . . . . . . . . . . . . . 10 6.1. Store Request Format . . . . . . . . . . . . . . . . . . . 10 6.2. Store Response Format . . . . . . . . . . . . . . . . . . 10 6.2.1. Storage Success . . . . . . . . . . . . . . . . . . . 10 6.2.2. Storage Failure . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 12 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 13 9. References . . . . . . . . . . . . . . . . . . . . . . . . . . 14 9.1. Normative References . . . . . . . . . . . . . . . . . . . 14 9.2. Non-normative References . . . . . . . . . . . . . . . . . 14 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 15 Hardt [Page 2] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 1. Terminology 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]. 1.1. Definitions and Conventions [NOTE: Update terminology based on final OpenID 2.0 draft.] User: (AKA "End User" or "Subject".) A person with a digital identity who participates in OpenID based identity information exchanges using their client software, typically a web browser. Identity Data: A property of a digital identity in which the Property Name and Property Value are represented as a name-value pair. Persona: A user can have multiple personas as part of their identity. For example, a user might have a work persona and a home persona. A persona is a subset of the user's identity data. Identity Provider: Also called "IdP" or "Server". This is the OpenID Authentication server that a Consumer contacts for cryptographic proof that the End User owns the Claimed Identity. Consumer: A site that requests identity data from an Identity Provider via the user's client. For the purposes of this document, the extension namespace identifier for the attribute exchange service will be "ax". Hardt [Page 3] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 2. Overview The attribute exchange service is identified by the URI "http://openid.net/srv/ax/1.0" [NOTE: subject to change in following drafts]. This URI must be specified in the extension namespace declaration. An attribute is a unit of personal identity information that is identified by a unique URI. It may refer to any kind of information; see [OpenID.attribute-types-1.0] for some examples. This service defines two additional message types for transferring attributes: fetch (see Section 5) and store (see Section 6). Fetch retrieves attribute information from an Identity Provider, while store saves or updates attribute information on the Identity Provider. Both messages originate from the Consumer site or service provider and are passed to the Identity Provider via the user agent as per the OpenID protocol specification. The request parameters detailed here SHOULD be sent with OpenID Authentication checkid_immediate or checkid_setup requests. [NOTE: This portion of the spec will change depending on the final draft of OpenID 2.0.] Error responses are communicated using the standard OpenID methods; see [OpenID.authentication-2.0]. Hardt [Page 4] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 3. Information Model The OpenID attribute exchange service provides a mechanism for moving identity information between sites, as such its information model is simple: An attribute is associated with a Subject Identifier An attribute has a type identfier and a value An attribute type identifier is a URI An attribute value is a UTF-8 string [RFC3629] 3.1. Subject Identifier An identifier for a set of attributes. MUST be a URI. The subject identifier corresponds to the end-user identifier in the authentication portion of the messages. In other words, the subject of the identity attributes in the attribute exchange part of the message is the same as the end-user in the authentication part. The subject identifier is not included in the attribute exchange. 3.2. Attribute Type Identifier An attribute type identifier MUST be a URI, which is used for referring to property values. If an attribute type identifier URI can be resolved then it MAY be dereferenced to retrieve a description of the property. This provides for flexibility and extensibility. Flexibility in that both URNs and URLs can be used to refer to property values. Extensibility allows any individual site, or consortium of sites, to define their own attribute types with agreements on the syntax and semantics of their associated attribute values. The process for defining new attribute types is defined in [OpenID.attribute-types-1.0]. 3.3. Attribute Value A attribute value MUST be a UTF-8 string and may optionally have no value. Hardt [Page 5] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 4. Discovery Discovery of the attribute exchange service is achieved via the mechanism described in [OpenID.authentication-2.0]. The attribute exchange namespace "http://openid.net/srv/ax/1.0" SHOULD be listed as an child element of the element in the XRDS discovery document. Hardt [Page 6] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 5. Fetch Message The fetch message is used to retrieve personal identity attributes from an Identity Provider. 5.1. Fetch Request Format All of the following request fields are OPTIONAL, though at least one of "openid.ax.required" or "openid.ax.if_available" MUST be specified in the request. Multiple aliases in the "required" or "if_available" directives are separated with a comma, ",". Any alias referred to in a "required" or "if_available" parameter MUST have an associated "openid.ax.fetch." parameter. openid.ax.fetch. Associates an alias with the attribute type identifier which is the value of this parameter. The name will be used as part of the lvalue in the fetch response message. openid.ax.required The value of this parameter is an alias corresponding to a URI defined in an "openid.ax.fetch.". The Identity Provider must provide the identity information specified in this parameter or return an error condition. Multiple aliases are separated with a comma, ",". openid.ax.if_available The value of this parameter is an alias corresponding to a URI defined in an "openid.ax.fetch.". The Identity Provider may provide the identity information specified in this parameter. Not including the information in the response does not constitute an error condition. Multiple aliases are separated with a comma, ",". openid.ax.update_url If this URL is specified, the Identity Provider may re-post the fetch response data to it at some time after the initial response has been sent. This "unsolicited" response message would be generated in response to an attribute information update, and would contain the updated data. The relying party may include transaction data encoded in the URL such that it contains enough information to match the attribute information to the identity subject. Additional information may be encoded in the URL by the relying party as necessary. If the Identity Provider supports this feature it MUST return the parameter as part of the fetch response message. If it does not support this feature it may legally ignore this parameter. Hardt [Page 7] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 This example requests the required full name and gender information, and the optional favourite dog information. openid.ns.ax=http://openid.net/srv/ax/1.0 openid.ax.fetch.fname=http://example.com/schema/fullname openid.ax.fetch.gender=http://example.com/schema/gender openid.ax.fetch.fav_dog=http://example.com/schema/favourite_dog openid.ax.required=fname,gender openid.ax.if_available=fav_dog openid.ax.update_url=http://idconsumer.com/update?transaction_id=a6b5c41 5.2. Fetch Response Format The fetch response message supplies the information requested in the fetch request. Each attribute is supplied with the assigned alias prefixed by "openid.ax.value" as the lvalue and the attribute value as the rvalue. Attribute types are also returned in the "type" parameter. All requested values are returned back. If the value was not supplied or available from the user, it will be returned as an empty value. This enables the RP to know that the IdP did process the request. openid.ax.type. Associates an alias with the attribute type identifier which is the value of this parameter. The name will be used as a reference in an "openid.ax.value." parameter. openid.ax.value. Assigns a value to the identifier with the name assigned by a "type" parameter. openid.ax.update_url Returns the "update_url" parameter specified in the request. If the Identity Provider receives an "update_url" parameter and it intends to support the attribute update feature, it MUST present the "update_url" parameter and value as part of the fetch response message. A fetch response message may also be sent to the "update_url" specified in Section 5.1 in response to attribute value updates on the Identity Provider. Hardt [Page 8] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 The response to the previous request example, in which the required full name information and the optional favourite dog information are both supplied. openid.ns.ax=http://openid.net/srv/ax/1.0 openid.ax.type.fname=http://example.com/schema/fullname openid.ax.type.gender=http://example.com/schema/gender openid.ax.type.fav_dog=http://example.com/schema/favourite_dog openid.ax.value.fname=John Smith openid.ax.value.gender=M openid.ax.value.fav_dog=Spot openid.ax.update_url=http://idconsumer.com/update?transaction_id=a6b5c41 Hardt [Page 9] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 6. Store Message The store message is used to store personal identity information to the Identity Provider. 6.1. Store Request Format All of the following request fields are OPTIONAL. Any alias referred to in a "value" parameter MUST have an associated "openid.ax.type." parameter. openid.ax.type. Associates an alias with the attribute type identifier which is the value of this parameter. The name will be used as a reference in an "openid.ax.value." parameter. openid.ax.value. Assigns a value to the identifier with the name assigned by a "type" parameter. openid.ns.ax=http://openid.net/srv/ax/1.0 openid.ax.type.fname=http://example.com/schema/fullname openid.ax.value.fname=Bob Smith 6.2. Store Response Format 6.2.1. Storage Success The successful store response consists of a successful response message with the 200 HTTP response code as per the OpenID specification [OpenID.authentication-2.0]. No additional parameters are sent. 6.2.2. Storage Failure If the store request fails, a parameter named "status" MUST be sent with the value "failure". Implementations MAY send an additional parameter, "status.description", containing a brief explanation of the error response. openid.ax.status On storage failure, the status parameter is sent with the value "failure". Hardt [Page 10] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 openid.ax.status.description Optional parameter describing the error condition leading to the failure response. openid.ns.ax=http://openid.net/srv/ax/1.0 openid.ax.status=failure openid.ax.status.description=General storage failure Hardt [Page 11] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 7. Security Considerations [NOTE: TBD] Hardt [Page 12] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 8. Acknowledgements John Merrels and other contributors to the document 'draft-merrels-dix'. Portions of that document were re-used for this one. Hardt [Page 13] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 9. References 9.1. Normative References [OpenID.authentication-2.0] Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, "OpenID Authentication 2.0 - Draft 10", August 2006. [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC3629] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. 9.2. Non-normative References [OpenID.attribute-types-1.0] Hardt, D., "OpenID Attribute Types - Draft 02", November 2006. Hardt [Page 14] OpenID Attribute Exchange 1.0 - Draft 03 November 2006 Author's Address Dick Hardt Sxip Identity 798 Beatty Street Vancouver, BC V6B 2M1 CA Email: dick@sxip.com URI: http://sxip.com/ Hardt [Page 15]