Draft D. Recordon VeriSign J. Hoyt JanRain D. Hardt Sxip B. Fitzpatrick Six Apart October 13, 2006 OpenID Authentication 2.0 - Draft 10 Recordon, et al. [Page 1] OpenID Authentication 2.0 - Draft 10 October 2006 Abstract OpenID Authentication provides a way to prove that an End User owns an Identifier. It does this without the Relying Party needing access to password, email address, or other sensitive information. OpenID is decentralized. No central authority must approve or register Relying Parties or Identity Providers. An End User can freely choose which Identity Provider to use. They can preserve their Identifier if they switch Identity Providers. While nothing in the protocol requires JavaScript or modern browsers, the authentication scheme plays nicely with "AJAX"-style setups, so an End User can prove their Identity to a Relying Party without having to leave the page they are on. OpenID Authentication uses only standard HTTP requests and responses, so does not require any special capabilities of the User-Agent or other software. The exchange of profile information, and other features not covered in this specification, is addressed through additional Service Types built on top of OpenID. Recordon, et al. [Page 2] OpenID Authentication 2.0 - Draft 10 October 2006 Table of Contents 1. Requirements Notation . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 4. Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1. Protocol Messages . . . . . . . . . . . . . . . . . . . . 8 4.1.1. Key-Value Form Encoding . . . . . . . . . . . . . . . 8 4.1.2. HTTP Encoding . . . . . . . . . . . . . . . . . . . . 8 4.1.3. Example . . . . . . . . . . . . . . . . . . . . . . . 8 4.2. Integer Representations . . . . . . . . . . . . . . . . . 9 5. Communication Types . . . . . . . . . . . . . . . . . . . . . 10 5.1. Direct Communication . . . . . . . . . . . . . . . . . . . 10 5.1.1. Direct Request . . . . . . . . . . . . . . . . . . . . 10 5.1.2. Direct Response . . . . . . . . . . . . . . . . . . . 10 5.2. Indirect Communication . . . . . . . . . . . . . . . . . . 11 5.2.1. HTTP Redirect . . . . . . . . . . . . . . . . . . . . 11 5.2.2. HTML FORM Redirection . . . . . . . . . . . . . . . . 11 5.2.3. Indirect Error Responses . . . . . . . . . . . . . . . 11 6. Generating Signatures . . . . . . . . . . . . . . . . . . . . 13 7. Signatures . . . . . . . . . . . . . . . . . . . . . . . . . . 14 7.1. Signature Algorithms . . . . . . . . . . . . . . . . . . . 14 7.2. Procedure . . . . . . . . . . . . . . . . . . . . . . . . 14 8. Initiation and Discovery . . . . . . . . . . . . . . . . . . . 15 8.1. Initiation . . . . . . . . . . . . . . . . . . . . . . . . 15 8.2. Normalization . . . . . . . . . . . . . . . . . . . . . . 15 8.3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 15 8.3.1. Discovered Information . . . . . . . . . . . . . . . . 16 8.3.2. XRDS-Based Discovery . . . . . . . . . . . . . . . . . 16 8.3.3. HTML-Based Discovery . . . . . . . . . . . . . . . . . 18 9. Establishing Associations . . . . . . . . . . . . . . . . . . 19 9.1. Association Session Request . . . . . . . . . . . . . . . 19 9.2. Association Session Response . . . . . . . . . . . . . . . 20 9.2.1. Common Response Parameters . . . . . . . . . . . . . . 20 9.2.2. Unencrypted Response Parameters . . . . . . . . . . . 21 9.2.4. Unsuccessful Response Parameters . . . . . . . . . . . 21 9.3. Association Types . . . . . . . . . . . . . . . . . . . . 22 9.3.1. HMAC-SHA1 . . . . . . . . . . . . . . . . . . . . . . 22 9.3.2. HMAC-SHA256 . . . . . . . . . . . . . . . . . . . . . 22 9.4. Association Session Types . . . . . . . . . . . . . . . . 22 10. Requesting Authentication . . . . . . . . . . . . . . . . . . 24 10.1. Request Parameters . . . . . . . . . . . . . . . . . . . . 24 10.2. Realms . . . . . . . . . . . . . . . . . . . . . . . . . . 25 10.3. Immediate Requests . . . . . . . . . . . . . . . . . . . . 26 11. Responding to Authentication Requests . . . . . . . . . . . . 27 11.1. Positive Assertions . . . . . . . . . . . . . . . . . . . 27 11.2. Negative Assertions . . . . . . . . . . . . . . . . . . . 29 11.2.1. In Response to Immediate Requests . . . . . . . . . . 29 Recordon, et al. [Page 3] OpenID Authentication 2.0 - Draft 10 October 2006 11.2.2. In Response to Non-Immediate Requests . . . . . . . . 30 12. Verifying Assertions . . . . . . . . . . . . . . . . . . . . . 31 12.1. Checking the Nonce . . . . . . . . . . . . . . . . . . . . 31 12.2. Verifying Signatures . . . . . . . . . . . . . . . . . . . 31 12.3. Verifying Discovered Information . . . . . . . . . . . . . 33 12.4. Identifying the End User . . . . . . . . . . . . . . . . . 33 12.4.1. HTTP and HTTPS URL Identifiers . . . . . . . . . . . . 34 13. OpenID Authentication 1.1 Compatibility . . . . . . . . . . . 35 13.1. Relying Parties . . . . . . . . . . . . . . . . . . . . . 35 13.2. Identity Providers . . . . . . . . . . . . . . . . . . . . 35 14. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 37 15. Discovering OpenID Relying Parties . . . . . . . . . . . . . . 38 16. Security Considerations . . . . . . . . . . . . . . . . . . . 39 16.1. Preventing Attacks . . . . . . . . . . . . . . . . . . . . 39 16.1.1. Eavesdropping Attacks . . . . . . . . . . . . . . . . 39 16.1.2. Man-in-the-Middle Attcks . . . . . . . . . . . . . . . 39 16.2. User Agents . . . . . . . . . . . . . . . . . . . . . . . 40 16.3. User Interface Considerations . . . . . . . . . . . . . . 40 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 41 Appendix A.1. Delegation . . . . . . . . . . . . . . . . . . . . . 41 Appendix A.2. XRDS . . . . . . . . . . . . . . . . . . . . . . . . 41 Appendix A.3. HTML Identifier Markup . . . . . . . . . . . . . . . 41 Appendix A.4. Login Form . . . . . . . . . . . . . . . . . . . . . 41 Appendix A.5. XRI CanonicalID . . . . . . . . . . . . . . . . . . 42 Appendix B. Diffie-Hellman Key Exchange Default Value . . . . . 43 Appendix C. Changes from the Previous OpenID Authentication Specification . . . . . . . . . . . . . . . . . . . 44 Appendix C.1. Updated Initiation and Discovery . . . . . . . . . . 44 Appendix C.2. Security improvements . . . . . . . . . . . . . . . 44 Appendix C.3. Extensions . . . . . . . . . . . . . . . . . . . . . 44 17. Normative References . . . . . . . . . . . . . . . . . . . . . 46 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 48 Recordon, et al. [Page 4] OpenID Authentication 2.0 - Draft 10 October 2006 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]. Recordon, et al. [Page 5] OpenID Authentication 2.0 - Draft 10 October 2006 2. Terminology Identifier: An Identifier is a URL or XRI [1]. An "Identifier" may be a Claimed Identifier, Delegate Identifier, IdP Identifier, or Verified Identifier, depending on context. End User: The person who wants to prove ownership of an Identifier. User-Agent: The End User's Web browser. See [RFC2616]. Claimed Identifier: An Identifier that the End User claims to own that has not yet been verified by the Relying Party. Verified Identifier: An Identifier that the End User has proven to a Relying Party that they own. Delegate Identifier: An alternate Identifier that can be included in the discovery response. Relying Party: RP. A Web application that wants proof that the End User owns an Identifier. Identity Provider: IdP. This is the OpenID Authentication server that a Relying Party contacts for cryptographic proof that the End User owns an Identifier. IdP Identifier: An Identifier which represents an IdP. Diffie-Hellman Key Exchange: Diffie-Hellman Key Exchange [RFC2631] is a protocol that allows two parties to share a secret, while preventing eavesdroppers from learning the secret. Recordon, et al. [Page 6] OpenID Authentication 2.0 - Draft 10 October 2006 3. Protocol Overview 1. The End User initiates authentication (Section 8.1) by supplying an Identifier to the Relying Party. 2. The Relying Party performs discovery (Section 8.3) on the Claimed Identifier and establishes the location of the IdP's endpoint that the End User uses for authentication. 3. (optional) The Relying Party and the IdP establish an association (Section 9) -- a shared secret established using Diffie-Hellman Key Exchange. The IdP uses an association to sign subsequent messages and the Relying Party to verify those messages. 4. The Relying Party redirects the End User's User Agent to the IdP with an OpenID Authentication request (Section 10). 5. The IdP establishes whether the End User is authorized to perform OpenID Authentication and wishes to do so. The manner in which the End User authenticates to their IdP is beyond the scope of this document. 6. The IdP redirects the End User's User Agent back to the Relying Party with an indication either that authentication is approved (Section 11.1) or authentication failed (Section 11.2). 7. The Relying Party verifies (Section 12) the information received from the IdP. Recordon, et al. [Page 7] OpenID Authentication 2.0 - Draft 10 October 2006 4. Data Formats 4.1. Protocol Messages The OpenID Authentication protocol messages are mappings of plain- text keys to plain-text values. The keys and values are Unicode strings. When the keys and values need to be converted to bytes, they MUST be encoded using UTF-8. 4.1.1. Key-Value Form Encoding A Key-Value form message is a sequence of lines. Each line begins with a key, followed by a colon, and the value associated with the key. The line is terminated by a single newline (codepoint 10, "/n"). A key or value MUST NOT contain a newline and a key MUST NOT either contain a colon. Additional characters, including whitespace, MUST NOT be added before or after the colon or newline. The message MUST be encoded in UTF-8 to produce a byte string. Key-Value Form encoding is used for signature calculation and for direct responses (Section 5.1.2) to relying parties. 4.1.2. HTTP Encoding When a message is sent to an HTTP server, it MUST be encoded using a form encoding specified in section 17.13.4 of the [HTML401]. Likewise, if the "Content-Type" header is included in the request headers, its value MUST also be such an encoding. All of the keys in the request message are prefixed with "openid.". This prefix prevents interference with other parameters that are passed along with the OpenID message. When a message is sent as a POST, the application processing the HTTP request MUST only use the values in the POST body and MUST ignore any "openid." parameters that are present on the request URL. This model applies to messages from the User Agent to both the Relying Party and the IdP, as well as messages from the Relying Party to the IdP. 4.1.3. Example Non-normative Recordon, et al. [Page 8] OpenID Authentication 2.0 - Draft 10 October 2006 The following examples encode the following information: Key | Value --------+--------------------------- mode | error error | This is an example message Key-Value Form encoded mode:error error:This is an example message x-www-urlencoded, as in a HTTP POST body or in a URL's query ([RFC3986] section 3). openid.mode=error&openid.error=This%20is%20an%20example%20message 4.2. Integer Representations Arbitrary precision integers MUST be encoded as big-endian signed two's complement binary strings. Henceforth, "btwoc" is a function that takes an arbitrary precision integer and returns its shortest big-endian two's complement representation. All integers that are used with Diffie-Hellman are positive. This means that the left-most bit of the two's complement representation MUST be zero. If it is not, implementations MUST add a zero byte at the front of the string. Non-normative example: Base 10 number | btwoc string representation ---------------+---------------------------- 0 | "\x00" 127 | "\x7F" 128 | "\x00\x80" 255 | "\x00\xFF" 32768 | "\x00\x80\x00" Recordon, et al. [Page 9] OpenID Authentication 2.0 - Draft 10 October 2006 5. Communication Types 5.1. Direct Communication Direct communication is initiated by a Relying Party to an IdP endpoint URL. It is used for establishing associations (Section 9) and verifying authentication assertions (Section 12.2.2). 5.1.1. Direct Request The message MUST be encoded as a POST body, as specified by Section 4.1.2. 5.1.2. Direct Response The body of a response to a Direct Request (Section 5.1.1) consists of an HTTP Response body in Key-Value Form (Section 4.1.1). The content-type of the response SHOULD be "text/plain". 5.1.2.1. Successful Responses A server receiving a properly formed request MUST send a response with an HTTP status code of 200. 5.1.2.2. Error Responses If a request is malformed or contains invalid arguments, the server MUST send a response with a status code of 400. The response body MUST be a Section 4.1.1 message with the following fields: o error Value: Unstructured text error message. o contact Value: (optional) Contact address for the administrator of the IdP. The contact address may take any form, as it is intended to be displayed to a person. o reference Value: (optional) A reference identifier, such as a support ticket number or a URL to a news blog, etc. The IdP MAY add additional keys to this response. The particular wire format of these messages will depend on whether Recordon, et al. [Page 10] OpenID Authentication 2.0 - Draft 10 October 2006 they are responses to direct or indirect requests. 5.2. Indirect Communication In indirect communication, messages are passed through the User- Agent. This can be initiated by either the Relying Party or the IdP. Indirect communication is used for authentication requests (Section 10) and authentication responses (Section 11). There are two methods for indirect communication: HTTP redirects and HTML form submission. Both form submission and redirection require that the sender know a recipient URL and that the recipient URL expect indirect messages, as specified in Section 4.1.2. The initiator of the communication chooses which method of indirect communication is appropriate. 5.2.1. HTTP Redirect Data can be transferred by issuing a 302, 303, or 307 HTTP Redirect to the End User's User-Agent. The redirect URL is the URL of the receiver with the OpenID Authentication message appended to the query string, as specified in Section 4.1.2. This method is deprecated as of OpenID Authentication version 2.0 though is still required for implementation to aide in backwards compatibility. 5.2.2. HTML FORM Redirection A mapping of keys to values can be transferred by returning an HTML page to the User-Agent that contains an HTML form element. Form submission MAY be automated using JavaScript. The