Abstract

OpenID Attribute Exchange is an OpenID service extension for exchanging identity information between endpoints. Messages for retrieval and storage of identity information are provided.

Table of Contents

1.  Terminology
    1.1.  Definitions and Conventions
2.  Overview
3.  Information Model
    3.1.  Subject Identifier
    3.2.  Attribute Type Identifier
    3.3.  Attribute Value
4.  Discovery
5.  Fetch Message
    5.1.  Fetch Request Format
    5.2.  Fetch Response Format
6.  Store Message
    6.1.  Store Request Format
    6.2.  Store Response Format
        6.2.1.  Storage Success
        6.2.2.  Storage Failure
7.  Security Considerations
8.  Acknowledgements
9.  References
    9.1.  Normative References
    9.2.  Non-normative References
§  Authors' Addresses

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] (Bradner, S., “Key words for use in RFCs to Indicate Requirement Levels,” March 1997.).

1.1. Definitions and Conventions

User:

Also referred to as "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.

Attribute

The base of the information model used to describe the Identity Data, for the purpose of exchanging it.

Persona:

A subset of the user's identity data. A user can have multiple personas as part of their identity. For example, a user might have a work persona and a home persona.

OpenID Provider:

Also called "OP" or "Server". An OpenID Authentication server on which a Relying Party relies for an assertion that the end user controls an Identifier.

Relying Party:

Also called "RP" or "Consumer". A Web application that wants proof that the end user controls an Identifier, and requests identity data associated with the end user.

For the purposes of this document, the extension namespace identifier for the attribute exchange service will be "ax".

2. Overview

The attribute exchange service extension 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] (Hardt, D., “OpenID Attribute Types - Draft 02,” November 2006.) for some examples.

This service extension defines two message types for transferring attributes: fetch (see Section 5 (Fetch Message)) and store (see Section 6 (Store Message)). Fetch retrieves attribute information from an OpenID Provider, while store saves or updates attribute information on the OpenID Provider. Both messages originate from the Relying Party and are passed to the OpenID Provider via the user agent as per the OpenID Authentication protocol specification.

The request parameters detailed here MUST be sent using the [OpenID.authentication-2.0] (Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, “OpenID Authentication 2.0 - Draft 10,” August 2006.) extension mechanism. Error responses are communicated using the standard OpenID methods.

3. Information Model

The OpenID Attribute Exchange service extension 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 identifier and a value

An attribute type identifier is a URI

An attribute value is a UTF-8 string [RFC3629] (Yergeau, F., “UTF-8, a transformation format of ISO 10646,” November 2003.)

3.1. Subject Identifier

An identifier for a set of attributes. It 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 proposed process for defining new attribute types is specified in [OpenID.attribute-types-1.0] (Hardt, D., “OpenID Attribute Types - Draft 02,” November 2006.), and the attribute metadata schema and data formats are described in [OpenID.attribute-metadata-1.0] (Hardt, D., “OpenID Attribute Metadata - Draft 01,” November 2006.). Details about the location of these documents, as well as the OpenID attribute type URI namespace have not been finalized yet, and are currently being discussed with the community.

3.3. Attribute Value

A attribute value MUST be a UTF-8 string and may optionally be empty.

4. Discovery

Discovery of the attribute exchange service extension is achieved via the mechanism described in [OpenID.authentication-2.0] (Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, “OpenID Authentication 2.0 - Draft 10,” August 2006.). The attribute exchange namespace "http://openid.net/srv/ax/1.0" SHOULD be listed as an <xrd:Type> child element of the <xrd:Service> element in the XRDS discovery document.

5. Fetch Message

The fetch message is used to retrieve personal identity attributes from an OpenID 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, and any attribute alias present in a "openid.ax.required" or "openid.ax.if_available" parameter MUST have an associated "openid.ax.type.<alias>" parameter.

Multiple attribute aliases in the "openid.ax.required" and "openid.ax.if_available" directives are separated with a comma, ",".

Attribute aliases MUST NOT contain newline and colon characters, as specified in the Data Formats / Protocol Messages section of [OpenID.authentication-2.0] (Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, “OpenID Authentication 2.0 - Draft 10,” August 2006.); they also MUST NOT contain commas.

openid.ax.type.<alias>

The value of this parameter specifies the type identifier URI of a requested attribute. The <alias> will further be used to identify the attribute being exchanged.

openid.ax.required

The value of this parameter is an attribute alias, or a list of aliases corresponding to the URIs defined by "openid.ax.type.<alias>" parameters. The OpenID Provider MUST provide the identity information specified in this parameter or return an error condition. Multiple attribute aliases are separated with a comma, ",".

openid.ax.if_available

The value of this parameter is an attribute alias, or a list of aliases corresponding to the URIs defined by "openid.ax.type.<alias>" parameters. The OpenID Provider MAY provide the identity information specified in this parameter. Not including the information in the response does not constitute an error condition. Multiple attribute aliases are separated with a comma, ",".

openid.ax.count.<alias>

OPTIONAL. The number of values for the specified attribute alias the Relying Party wishes to receive from the OpenID Provider. If present, the value MUST be greater than zero. If absent, exactly one value is requested. OpenID Providers MUST NOT return more than the number of requested values.

openid.ax.update_url

If this URL is specified, the OpenID 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 OpenID 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.

This example requests the required full name and gender information, and the optional favourite dog and movie information. The Relying Party is interested in up to three favorite movies associated with the subject identifier.

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.type.fav_movie=http://example.com/schema/favourite_movie
openid.ax.count.fav_movie=3
openid.ax.required=fname,gender
openid.ax.if_available=fav_dog,fav_movie
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 "openid.ax.type.<alias>" parameters.

A response parameter will be sent for each requested attribute alias. If a value was not supplied or available from the user, the attribute alias will be returned with an empty value. This enables the RP to know that the OP did process the request.

openid.ax.type.<alias>

The value of this parameter specifies the type identifier URI for the attribute referred to as <alias>. MUST be present if, and only if, this exact parameter was included in the fetch request.

openid.ax.count.<alias>

The number of values returned for the attribute referred to as <alias>. MUST be present if, and only if, it was present in the fetch request.

openid.ax.value.<alias>

Assigns a value to the attribute referred to as <alias>. This parameter format MUST be used if "openid.ax.count.<alias>" is not sent.

openid.ax.value.<alias>.<number>

Assigns a value to the attribute referred to as <alias>. The <number> uniquely identifies the index of the value, ranging from one to the value specified by "openid.ax.count.<alias>". This parameter format MUST be used if "openid.ax.count.<alias>" is sent, and the number of parameters MUST be equal to the value specified by "openid.ax.count.<alias>".

openid.ax.update_url

Returns the "update_url" parameter specified in the request. If the OpenID 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 (Fetch Request Format) in response to attribute value updates on the OpenID Provider.

The response to the previous request example, in which the required full name information, and the optional favourite dog information are supplied. Even though three movie names were requested, the OP supplied only two values.

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.type.fav_movie=http://example.com/schema/favourite_movie
openid.ax.value.fname=John Smith
openid.ax.value.gender=M
openid.ax.value.fav_dog=Spot
openid.ax.count.fav_movie=2
openid.ax.value.fav_movie.1=Movie1
openid.ax.value.fav_movie.2=Movie2
openid.ax.update_url=http://idconsumer.com/update?transaction_id=a6b5c41

6. Store Message

The store message is used to store personal identity information to the OpenID Provider.

6.1. Store Request Format

All of the following request fields are OPTIONAL. Any alias referred to in a "openid.ax.value.<alias>" or "openid.ax.value.<alias>.<number>" parameter MUST have an associated "openid.ax.type.<alias>" parameter.

openid.ax.type.<alias>

The value of this parameter specifies the type identifier URI for the attribute referred to as <alias>.

openid.ax.count.<alias>

The number of values sent for the attribute referred to as <alias>. If present, the value MUST be greater than zero.

openid.ax.value.<alias>

Assigns a value to the attribute referred to as <alias>. This parameter format MUST be used if "openid.ax.count.<alias>" is not sent.

openid.ax.value.<alias>.<number>

Assigns a value to the attribute referred to as <alias>. The <number> uniquely identifies the index of the value, ranging from one to the value specified by "openid.ax.count.<alias>". This parameter format MUST be used if "openid.ax.count.<alias>" is sent, and the number of these parameters MUST be equal to the value specified by "openid.ax.count.<alias>".

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
openid.ax.type.fav_movie=http://example.com/schema/favourite_movie
openid.ax.count.fav_movie=2
openid.ax.value.fav_movie.1=Movie1
openid.ax.value.fav_movie.2=Movie2

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] (Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, “OpenID Authentication 2.0 - Draft 10,” August 2006.). 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".

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

7. Security Considerations

OpenID Attribute Exchange is an OpenID extension, and thus uses OpenID Authentication request and response messages for exchanging attributes.

See the "Security Considerations" section of [OpenID.authentication-2.0] (Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, “OpenID Authentication 2.0 - Draft 10,” August 2006.).

8. Acknowledgements

John Merrels and other contributors to the document 'draft-merrels-dix'. Portions of that document were re-used for this one.

9. References

9.1. Normative References

9.2. Non-normative References

Authors' Addresses