OpenID Email Address Transform Extension 1.0 - Draft 1

Abstract

OpenID Email Address Transformation is an extension to the OpenID Authentication 2.0 protocol, and provides a straightforward mechanism to transform an RFC2822 email address into an OpenId-compatible Url. The transform procedure outlined in this document is designed to be flexible enough such that every DNS domain-owner can specify a unique transformation format that Relying Parties can easily discover and utilize in thier OpenId transactions.

Table of Contents

1.  Requirements Notation
2.  Terminology
    2.1.  Existing Terminology
    2.2.  New Terminology
3.  Protocol Overview
4.  Reccommend Usage in OpenId Authentication 2.0
5.  Normalization
6.  Discovery
    6.1.  Discovered Information
    6.2.  XRDS-Based Discovery
        6.2.1.  Service Elements
        6.2.2.  Extracting the OpenId URL or ETT
    6.3.  Default Discovery
7.  Tranforming an Email Address using an ETT
    7.1.  ETT Structure
    7.2.  ETT Validity
        7.2.1.  Valid ETT
        7.2.2.  Invalid ETT
8.  ETT Tranform Procedure
9.  Security Considerations
    9.1.  Man-in-the-Middle Attacks
10.  Acknowledgements
Appendix A.  Examples
Appendix A.1.  Email Address Normalization
Appendix A.2.  ETT Examples
Appendix A.3.  XRDS Service Element Examples
Appendix A.3.1.  ETT Service Element Example 1
Appendix A.3.2.  ETT Service Element Example 2
11.  Normative References
§  Author's Address

1.  Requirements Notation

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, B., “Key words for use in RFCs to Indicate Requirement Levels,” .) .

2.  Terminology

The terminology definitions are broken up into three sub-categories: Existing, New, and Extended terminology.

2.1.  Existing Terminology

The following terminology is specified in OpenId Authentication 2.0 (Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, “OpenID Authentication 2.0 - Draft 11,” August 2006.) [OpenID.authentication‑2.0] , and is reproduced here for reference throughout this document.

Relying Party:

RP. A Web application that wants proof that the end user controls an Identifier.

OpenID Provider:

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

OP Endpoint URL:

The URL which accepts OpenID Authentication requests, obtained by performing discovery on the the User-Supplied Identifier. This value MUST be an absolute URL.

Claimed Identifier:

An Identifier that the end user claims to own; the overall aim of the protocol is verifying this claim. The Claimed Identifier is either:

• The Identifier obtained by normalizing the User-Supplied Identifier, if it was an URL.
• The CanonicalID , if it was an XRI.

2.2.  New Terminology

The following is new terminology for this OpenId Authentication 2.0 (Recordon, D., Hoyt, J., Fitzpatrick, B., and D. Hardt, “OpenID Authentication 2.0 - Draft 11,” August 2006.) [OpenID.authentication‑2.0] extension.

Processing-Agent

A Relying Party or other agent (e.g, a computer program) attempting to perform an OpenId Email Address Transform operation.

OpenId URL

An "http" or "https" schemed URI (Berners-Lee, T., Fielding, R., and L. Masinter, “Uniform Resource Identifier (URI): Generic Syntax,” .) [RFC3986] (commonly referred to as a "URL" within this document) which can be used in the OpenId protocol.

Email Address:

An RFC2822 (Resnick, P., “Internet Message Format,” .) [RFC2822] compatible Email address.

Email Identifier:

An Email Address that was presented to the Processing Agent. The Email Identifier can be normalized and tranformed into an OpenId Url.

Normalized Email Identifier:

An RFC2822 'Addr-spec' compatible email address that can be used in the OpenID Email Address Tranformation Extension. This Identifier is typically the result of normalizing (Normalization) an Email Identifier.

Email Address Transform Template (ETT)

A URI, possibly containing a Wildcard Replacement Token.

Wildcard Replacement Token

A string surrounded by an opening-brace and a closing-brace, in that order (such as [username]). The Wildcard Replacement Token is used inside of an ETT to designate how an OP structures its Claimed Identifiers.

3.  Protocol Overview

1. An Email Address is presented to the Processing-Agent.
2. The Email Address is normalized (Normalization) to produce a Normalized Email Identifier.
3. The Processing-Agent then performs discovery (Discovery) on the Normalized Email Identifier and retrieves either an OpenId URL or an Email Address Transform Template URL (ETT).
4. (Optional) If an ETT is found, it is tranformed into an OpenId URL using information extracted from the Normalized Email Identifier.
5. The resulting OpenId URL can then be used in an OpenId Authentication transaction.

4.  Reccommend Usage in OpenId Authentication 2.0

This protocol extension results in an OpenId Url that can be utilized by a Relying Party to initiate OpenId Authentication.

Traditionally, OpenId Authentication 2.0 allows a User-Supplied Identifier to be an Identifier that is presented by the end user to the Relying Party, or selected by the user at the OpenID Provider. During the initiation phase of the protocol, an end user may enter either their own Identifier or an OP Identifier. If an OP Identifier is used, the OP may then assist the end user in selecting an Identifier to share with the Relying Party.

Using this extension, OpenId Relying parties can extend the definition of a User-Supplied Identifier to be the following:

A User-Supplied Identifier is an Identifier or Email Identifier that was presented by the end user to the Relying Party, or an Identifier selected by the user at the OpenID Provider. During the initiation phase of the protocol, an end user may enter either their own Identifier, an OP Identifier, or an Email Identifier. If an OP Identifier is used, the OP may then assist the end user in selecting an Identifier to share with the Relying Party. If an Email Identifier is used, this identifier will be tranformed into its corresponding OpenId URL, and used as a traditional User-Supplied Identifier in OpenId 2.0 Authentication.

5.  Normalization

The Email Identifier provided to the Processing Agent MUST be normalized into a Normalized Email Identifier, as follows:

1. If the Email Identifier contains one or more comma's (ASCII #2C or ','), then all comma's in the Email Identifier SHALL be converted into semi-colon's (ASCII #3B or ';') using the ASCII character set.
   
   
2. The resulting Email Identifier must be broken up into tokens using a semi-colon delmiter. The first token ONLY becomes the new Email Identifier for purposes of Normalization.
   
   
3. If the resulting Email Identifier contains more than 1 'less-than' (ASCII #3C or '<') character and/or more than one 'greater-than' (ASCII #3E or '>') character, then the Email Identifier is considered to be invalid, and the tranformation process SHOULD fail.
   
   
4. If the resulting Email Identifier contains a single 'less-than' character, it SHOULD also contain a 'greater-than' character at some point after the 'less-than' character. If only one, but not both, of these character are present in the Email Identifier, then the Email Identifier is considered to be invalid, and the tranformation process SHOULD fail.
   
   
5. If a single 'less-than' character and a single 'greater-than' character are both present in the Email Identifier, all text up to and including the 'less-than' character MUST be removed and discarded. In addition, all text from the 'greater-than' character inclusive, to the end of the Email Identifier MUST be removed and discarded. For example, the Email Identifier 'Beth "I'm cool" Jones" <beth@example.com>' MUST become 'beth@example.com' (single quotes are for clarity, and not part of the actual protocol).
   
   
6. Email Identifiers MUST then be further normalized to conform to section 3.4.1 (Addr-spec specification) of RFC2822. After completing this Normalization process, the Email Identifier MUST be a valid Addr-spec as defined by RFC2822, and SHOULD be of the following form: addr-spec = local-part "@" domain
   
   
7. After all normalization steps have been complete, the resulting ASCII string is known as the Normalized Email Identifier.

See these normalization examples (Email Address Normalization) for further valid and invalid examples of an Email Identifier that has been fully normalized.

6.  Discovery

Discovery is the process where the Processing Agent uses the Normalized Email Identifier to look up ("discover") the necessary information for transforming the Normalized Email Identifier into an OpenId URL. This extension protocol has two paths through which to do discovery:

1. The Yadis protocol (Miller, J., “Yadis Specification 1.0,” .) [Yadis] SHALL be first attempted. If it succeeds, the result is an XRDS document that contains the necessary information for the protocol to continue. If more than one applicable Service Element is returned in the XRDS document, the precedence rules defined in [XRI_Resolution_2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Working Draft 10,” .) are to be applied.
2. If the Yadis protocol fails for any reason (e.g., no valid XRDS document is retrieved, or no valid Service Elements (Service Elements) are found in the XRDS document), then Default Discovery (Default Discovery) MUST be peformed.

6.1.  Discovered Information

Upon successful completion of discovery, the Processing Agent will have the Email Address Transform Protocol version, as well as one or both of the following pieces of information:

• OpenId URL
• Email Address Transform Template (ETT)

The OpenId URL can be used in existing OpenId Authentication protocols, meaning it could either be an OP EndPoint URL or a Claimed Identifier. If an ETT is discovered instead of an OpenId URL, the ETT SHOULD be used to transform the Normalized Email Identifier into an OpenId URL.

6.2.  XRDS-Based Discovery

If Yadis discovery was used, the result will be an XRDS Document, which is defined in Section 3 of (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Working Draft 10,” .) [XRI_Resolution_2.0]. This is an XML document with entries for services that are related to the Normalized Email Identifier.

6.2.1.  Service Elements

For non-normative examples of XRDS Service Elements supported by this protocol, see the XRDS Examples (XRDS Service Element Examples) section.

6.2.1.1.  Email Address Transform Template Element

An Email Address Transform Template (ETT) Element is an <xrd:Service> element with the following information:

• An <xrd:Type> tag whose text content is "http://openid.net/srv/oeat/1.0/ett".
• An <xrd:URI> tag whose text content is an an Email Address Transform URL (ETT).

6.2.1.2.  OpenId URL Element

An OpenId URL Element is an <xrd:Service> element with the following information:

• An <xrd:Type> tag whose text content is "http://specs.openid.net/auth/2.0/server".
• An <xrd:URI> tag whose text content is an OP Endpoint URL (An OP Endpoint URL as defined in OpenId Authentication 2.0 is an OpenId URL Identifier as defined by this extension).

6.2.2.  Extracting the OpenId URL or ETT

Once the Processing Agent has obtained an XRDS document, it MUST first search the document (following the rules described in [XRI_Resolution_2.0] (Wachob, G., Reed, D., Chasen, L., Tan, W., and S. Churchill, “Extensible Resource Identifier (XRI) Resolution V2.0 - Working Draft 10,” .) ) for either a valid OpenId URL or an Email Address Transform Template. If none of these are found, then Default Discovery (Default Discovery) SHALL be performed.

6.3.  Default Discovery

If the Yadis protocol fails (e.g., no valid XRDS document was retrieved, or no valid Service Elements were found in the XRDS document), then the OpenId URL returned by this protocol SHALL be an OP Identifier that is assembled as follows:

1. Parse the Normalized Email Address using the 'at sign' ('@' ASCII #40) as a delimeter. The result of this parsing operation SHOULD be two tokens, the second of which will be the 'domain' of the Email Address as defined by RFC2822, section 3.4.1. (The first token will be the 'local-part' as defined by RFC2822). The first token SHALL be discarded, leaving the second token, which is the 'domain'.
   
   
2. Using the 'domain' result from the first step, prepend the string "https://" to it.
   
   
3. The resulting URI is a valid OP Identifier and is the final result of this protocol extension if, and only if, OpenId discovery (as defined by the OpenId Authentication 2.0 specification) is successful on the resulting URI.
   
   
4. If OpenId discovery is not successufl on the resulting URI (i.e., no XRDS document is found, or no valid Service Elements are found in the XRDS document), then a new URI should be assembled by starting with the 'domain' result from the first step, and prepending the string "https://www." to it.
   
   
5. The resulting URI is a valid OP Identifier and is the final result of this protocol extension. If OpenId Discovery (as defined by the OpenId Authentication 2.0 specification) is unsuccessful on the final resulting URI, then Email Transformation is not possible with the supplied Email Address. The Processing Agent SHOULD treat the supplied Email Address as it would any other invalid User-Supplied Identifier.

7.  Tranforming an Email Address using an ETT

In order to tranform a Normalized Email Address into an OpenId URL, a Processing Agent must have a valid Email Address Tranform Template (ETT). This section details the structure of the ETT, as well as the steps necessary to tranform an Email Address into an OpenId Url using an ETT.

7.1.  ETT Structure

An Email Address Transform Template (ETT) is an absolute URI that contains zero or more Wildcard Replacement Fields, each of which are textual character(s) surrounded by an opening-bracket ('[' ASCII #5B ) on the left, and a closing-bracket (']' ASCII #5D) on the right.

As of this version of the Transform protocol, the only allowed replacement field is 'username'.

Because the 'opening-bracket' and 'closing-bracket' characters are prohibited by the URI syntax, these characters MUST be percent-encoded per section 2.1 of the URI Specification before being included in an XRDS document.

7.2.  ETT Validity

7.2.1.  Valid ETT

An Email Address Transform Template (ETT) is considered to be valid if it is either a valid URI, or a URI with a Wildcard Replacement Field as allowed by this protocol. Currently, only the [username] Wildcard Replacement Field is defined and allowed.

7.2.2.  Invalid ETT

An Email Address Transform Template (ETT) is considered to be invalid if the ETT has any of the following properties:

• It contains more than one of either kind of bracket.
• It contains an odd number of brackets.

An invalid ETT MUST NOT be used in an Email Address Transform operation.

8.  ETT Tranform Procedure

In order to tranform a Normalized Email Address into an OpenId URL, a Processing Agent must have a valid Email Address Tranform Template (ETT). If the valid ETT does not contain any Wildcard Replacement Fields, then the transform is complete: The ETT is the OpenId URL, and this transform extension protocol ends.

However, if the ETT does contain a Wildcard Replacement Field, then the following procedure is used to tranform the Normalized Email Address into an OpenId Url using an ETT:

1. Tokenize the Normalized Email Address using the 'at sign' ('@' ASCII #40) as a delimeter. The result of this parsing operation SHOULD be two tokens, the first of which will be the 'local-part' of the Email Address as defined by RFC2822, section 3.4.1. (The second token will be the 'domain).
   
   
2. The ETT should be percent-decoded per section 2.1 of the URI specification. Specifically, %5B should be decoded to be the opening-bracket, while %5D should be decoded to be the closing bracket, but only where these two characters surround a valid Wildcard Replacement String (such as 'username').
   
   
3. Next, in the ETT replace the portion of the ETT that contains '[username]' with the value of the 'local-part' portion of the email address.
   
   
4. The resulting URI is a valid OpenId URL (Note that this URL will likely be treated as a Claimed Identifier, although this is ultimately OP-implementation defined).
   
   

9.  Security Considerations

9.1.  Man-in-the-Middle Attacks

If DNS resolution or the transport layer is compromised, this protocol is not fully secure since the attacker can impersonate the OP and tamper with the discovery process. If an attacker can tamper with the discovery process he/she can specify any OP, and so does not have to impersonate the OP. Additionally, if an attacker can compromise the integrity of the information returned during the discovery process, by altering the XRDS document, the need for a man in the middle is removed. In such an attack, a forged OpenId Endpoint URL or forged ETT could be returned. One method to prevent this sort of attack is by digitally signing the XRDS file as per XMLDSIG (Eastlake 3rd, D., Reagle Jr., J., and D. Solo, “(Extensible Markup Language) XML-Signature Syntax and Processing,” .) [RFC3275] . The keying material is not specified, since the RP ultimately needs to make its own decision whether to trust keys used for such a signature.

Using SSL with certificates signed by a trusted authority prevents these kinds of attacks by verifying the results of the DNS look-up against the certificate. Once the validity of the certificate has been established, tampering is not possible. Impersonating an SSL server requires forging or stealing a certificate, which is significantly harder than the network based attacks.

In order to get protection from SSL, SSL must be used for all parts of this protocol, While the protocol does not require SSL be used, its use is strongly RECOMMENDED. Current best practices dictate that an OP SHOULD use SSL, with a certificate signed by a trusted authority, to secure its Endpoint URL as well as the interactions with the Processing Agent. In addition, SSL, with a certificate signed by a trusted authority, SHOULD be used so that a Relying Party can fetch the end user's URL in a secure manner. Following its own security policies, a Processing-Agent MAY choose to not complete, or even begin, a transaction if SSL is not being correctly used at these various endpoints.

10.  Acknowledgements

Textual portions of the OpenID Authentication 2.0 and XML portions of the OpenId Attribute Exchange 1.0 specifications were used in the creation of this extension document.

Appendix A.  Examples

Non-normative

Appendix A.1.  Email Address Normalization

Appendix A.2.  ETT Examples

https://[username].example.com/

https://www.example.com/server/[username]

Appendix A.3.  XRDS Service Element Examples

Appendix A.3.1.  ETT Service Element Example 1

For a Normalized Email Address 'beth@example.com' to tranform to the OpenId URL 'https://beth.example.com', the following XML snippet should be present in the the XRDS file when discovery is preformed on "https://example.com/" or "https://www.example.com":

<Service xmlns="xri://$xrd*($v*2.0)">
  <Type>http://openid.net/srv/oeat/1.0/ett</Type>
  <URI>https://%5Busername%5D.example.com/</URI>
</Service>

Appendix A.3.2.  ETT Service Element Example 2

For a Normalized Email Address 'beth@example.com' to tranform to the OpenId URL 'https://www.example.com/openid/personas/beth', the following XML snippet should be present in the the XRDS file when discovery is preformed on "https://example.com/" or "https://www.example.com":

<Service xmlns="xri://$xrd*($v*2.0)">
  <Type>http://openid.net/srv/oeat/1.0/ett</Type>
  <URI>https://www.example.com/openid/personas/%5Busername%5D/</URI>
</Service>

11. Normative References

Author's Address