Implementor's Draft specs@openid.net January 18, 2007 OpenID Authentication 2.0 - Draft 11 specs@openid.net [Page 1] OpenID Authentication 2.0 - Draft 11 January 2007 Abstract OpenID Authentication provides a way to prove that an end user controls an Identifier. It does this without the Relying Party needing access to end user credentials such as a password or to other sensitive information such as an email address. OpenID is decentralized. No central authority must approve or register Relying Parties or OpenID Providers. An end user can freely choose which OpenID Provider to use, and can preserve their Identifier if they switch OpenID Providers. While nothing in the protocol requires JavaScript or modern browsers, the authentication scheme plays nicely with "AJAX"-style setups. This means an end user can prove their Identity to a Relying Party without having to leave their current Web page. OpenID Authentication uses only standard HTTP(S) requests and responses, so it does not require any special capabilities of the User-Agent or other client software. OpenID is not tied to the use of cookies or any other specific mechanism of Relying Party or OpenID Provider session management. Extensions to User-Agents can simplify the end user interaction, though are not required to utilize the protocol. The exchange of profile information, or the exchange of other information not covered in this specification, can be addressed through additional service types built on top of this protocol to create a framework. OpenID Authentication is designed to provide a base service to enable portable, user-centric digital identity in a free and decentralized manner. specs@openid.net [Page 2] OpenID Authentication 2.0 - Draft 11 January 2007 Table of Contents 1. Requirements Notation and Conventions . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 3. Protocol Overview . . . . . . . . . . . . . . . . . . . . . . 7 4. Data Formats . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.1. Protocol Messages . . . . . . . . . . . . . . . . . . . . 8 4.2. Integer Representations . . . . . . . . . . . . . . . . . 10 5. Communication Types . . . . . . . . . . . . . . . . . . . . . 11 5.1. Direct Communication . . . . . . . . . . . . . . . . . . . 11 5.2. Indirect Communication . . . . . . . . . . . . . . . . . . 12 6. Generating Signatures . . . . . . . . . . . . . . . . . . . . 15 6.1. Procedure . . . . . . . . . . . . . . . . . . . . . . . . 15 6.2. Signature Algorithms . . . . . . . . . . . . . . . . . . . 15 7. Initiation and Discovery . . . . . . . . . . . . . . . . . . . 16 7.1. Initiation . . . . . . . . . . . . . . . . . . . . . . . . 16 7.2. Normalization . . . . . . . . . . . . . . . . . . . . . . 16 7.3. Discovery . . . . . . . . . . . . . . . . . . . . . . . . 16 8. Establishing Associations . . . . . . . . . . . . . . . . . . 21 8.1. Association Session Request . . . . . . . . . . . . . . . 21 8.2. Association Session Response . . . . . . . . . . . . . . . 22 8.3. Association Types . . . . . . . . . . . . . . . . . . . . 24 8.4. Association Session Types . . . . . . . . . . . . . . . . 25 9. Requesting Authentication . . . . . . . . . . . . . . . . . . 26 9.1. Request Parameters . . . . . . . . . . . . . . . . . . . . 26 9.2. Realms . . . . . . . . . . . . . . . . . . . . . . . . . . 27 9.3. Immediate Requests . . . . . . . . . . . . . . . . . . . . 28 10. Responding to Authentication Requests . . . . . . . . . . . . 29 10.1. Positive Assertions . . . . . . . . . . . . . . . . . . . 29 10.2. Negative Assertions . . . . . . . . . . . . . . . . . . . 31 11. Verifying Assertions . . . . . . . . . . . . . . . . . . . . . 33 11.1. Verifying the Return URL . . . . . . . . . . . . . . . . . 33 11.2. Verifying Discovered Information . . . . . . . . . . . . . 33 11.3. Checking the Nonce . . . . . . . . . . . . . . . . . . . . 34 11.4. Verifying Signatures . . . . . . . . . . . . . . . . . . . 35 11.5. Identifying the end user . . . . . . . . . . . . . . . . . 37 12. Extensions . . . . . . . . . . . . . . . . . . . . . . . . . . 38 13. Discovering OpenID Relying Parties . . . . . . . . . . . . . . 40 14. OpenID Authentication 1.1 Compatibility . . . . . . . . . . . 41 14.1. Changes from OpenID Authentication 1.1 . . . . . . . . . . 41 14.2. Implementing OpenID Authentication 1.1 Compatibility . . . 42 15. Security Considerations . . . . . . . . . . . . . . . . . . . 45 15.1. Preventing Attacks . . . . . . . . . . . . . . . . . . . . 45 15.2. User-Agents . . . . . . . . . . . . . . . . . . . . . . . 46 15.3. User Interface Considerations . . . . . . . . . . . . . . 47 15.4. HTTP and HTTPS URL Identifiers . . . . . . . . . . . . . . 47 15.5. Denial of Service Attacks . . . . . . . . . . . . . . . . 47 15.6. Protocol Variants . . . . . . . . . . . . . . . . . . . . 48 specs@openid.net [Page 3] OpenID Authentication 2.0 - Draft 11 January 2007 Appendix A. Examples . . . . . . . . . . . . . . . . . . . . . . 50 Appendix A.1. Normalization . . . . . . . . . . . . . . . . . . . 50 Appendix A.2. OP-Local Identifiers . . . . . . . . . . . . . . . . 50 Appendix A.3. XRDS . . . . . . . . . . . . . . . . . . . . . . . . 51 Appendix A.4. HTML Identifier Markup . . . . . . . . . . . . . . . 51 Appendix A.5. XRI CanonicalID . . . . . . . . . . . . . . . . . . 51 Appendix B. Diffie-Hellman Key Exchange Default Value . . . . . 52 Appendix C. Acknowledgements . . . . . . . . . . . . . . . . . . 53 16. Normative References . . . . . . . . . . . . . . . . . . . . . 54 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 56 specs@openid.net [Page 4] OpenID Authentication 2.0 - Draft 11 January 2007 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. specs@openid.net [Page 5] OpenID Authentication 2.0 - Draft 11 January 2007 2. Terminology Identifier: An Identifier is either a "http" or "https" URI, (commonly referred to as a "URL" within this document), or an XRI [XRI_Syntax_2.0]. This document defines various kinds of Identifiers, designed for use in different contexts. User-Agent: The end user's Web browser which implements HTTP/1.1 [RFC2616]. 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. OP Identifier: An Identifier for an OpenID Provider. User-Supplied Identifier: An Identifier that was 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. 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 (Section 7.2) the User- Supplied Identifier, if it was an URL. * The CanonicalID (Section 7.3.2.3), if it was an XRI. OP-Local Identifier: An alternate Identifier for an end user that is local to a particular OP and thus not necessarily under the end user's control. specs@openid.net [Page 6] OpenID Authentication 2.0 - Draft 11 January 2007 3. Protocol Overview 1. The end user initiates authentication (Section 7.1) by presenting a User-Supplied Identifier to the Relying Party via their User- Agent. 2. After normalizing (Section 7.2) the User-Supplied Identifier, the Relying Party performs discovery (Section 7.3) on it and establishes the OP Endpoint URL that the end user uses for authentication. It should be noted that the User-Supplied Identifier may be an OP Identifier, as discussed in Section 7.3.1, which allows selection of a Claimed Identifier at the OP or for the protocol to proceed without a Claimed Identifier if something else useful is being done via an extension (Section 12). 3. (optional) The Relying Party and the OP establish an association (Section 8) -- a shared secret established using Diffie-Hellman Key Exchange [RFC2631]. The OP uses an association to sign subsequent messages and the Relying Party to verify those messages; this removes the need for subsequent direct requests to verify the signature after each authentication request/response. 4. The Relying Party redirects the end user's User-Agent to the OP with an OpenID Authentication request (Section 9). 5. The OP 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 OP and any policies surrounding such authentication is out of scope for this document. 6. The OP redirects the end user's User-Agent back to the Relying Party with either an assertion that authentication is approved (Section 10.1) or a message that authentication failed (Section 10.2). 7. The Relying Party verifies (Section 11) the information received from the OP including checking the Return URL, verifying the discovered information, checking the nonce, and verifying the signature by using either the shared key established during the association or by sending a direct request to the OP. specs@openid.net [Page 7] OpenID Authentication 2.0 - Draft 11 January 2007 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 permit the full Unicode character set (UCS). When the keys and values need to be converted to/from bytes, they MUST be encoded using UTF-8 [RFC3629]. Messages MUST NOT contain multiple parameters with the same name. Throughout this document, all OpenID message parameters are REQUIRED, unless specifically marked as OPTIONAL. 4.1.1. Key-Value Form Encoding A message in Key-Value form 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 (UCS codepoint 10, "\n"). A key or value MUST NOT contain a newline and a key also MUST NOT 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 [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 MUST be prefixed with "openid.". This prefix prevents interference with other parameters that are passed along with the OpenID Authentication message. When a message is sent as a POST, OpenID parameters MUST only be sent in, and extracted from, the POST body. All messages that are sent as HTTP requests (GET or POST) MUST contain the following fields: o openid.ns specs@openid.net [Page 8] OpenID Authentication 2.0 - Draft 11 January 2007 Value: "http://specs.openid.net/auth/2.0" This particular value MUST be present for the request to be a valid OpenID Authentication 2.0 request. Future versions of the specification may define different values in order to allow message recipients to properly interpret the request. If this value is absent or set to one of "http://openid.net/signon/1.1" or "http://openid.net/signon/1.0", then this message SHOULD be interpreted using OpenID Authentication 1.1 Compatibility mode (Section 14). o openid.mode Value: Specified individually for each message type. The "openid.mode" parameter allows the recipient of the message to know what kind of message it is processing. If "openid.mode" is absent, the party processing the message SHOULD assume that the request is not an OpenID message. This model applies to messages from the User-Agent to both the Relying Party and the OP, as well as messages from the Relying Party to the OP. 4.1.3. Example Non-normative 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 string ([RFC3986] section 3): openid.mode=error&openid.error=This%20is%20an%20example%20message specs@openid.net [Page 9] OpenID Authentication 2.0 - Draft 11 January 2007 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 Key Exchange 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" specs@openid.net [Page 10] OpenID Authentication 2.0 - Draft 11 January 2007 5. Communication Types 5.1. Direct Communication Direct communication is initiated by a Relying Party to an OP endpoint URL. It is used for establishing associations (Section 8) and verifying authentication assertions (Section 11.4.2). 5.1.1. Direct Request The message MUST be encoded as a POST body, as specified by Section 4.1.2. All direct requests are HTTP POSTs, and so contain the required fields listed in 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". All Key-Value form message MUST contain the following field: o ns Value: "http://specs.openid.net/auth/2.0" This particular value MUST be present for the response to be a valid OpenID 2.0 response. Future versions of the specification may define different values in order to allow message recipients to properly interpret the request. If this value is absent or set to one of "http://openid.net/signon/1.1" or "http://openid.net/signon/1.0", then this message SHOULD be interpreted using OpenID Authentication 1.1 Compatibility mode (Section 14). 5.1.2.1. Successful Responses A server receiving a valid 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 specs@openid.net [Page 11] OpenID Authentication 2.0 - Draft 11 January 2007 MUST be a Key-Value Form (Section 4.1.1) message with the following fields: o ns As specified in Section 5.1.2. o error Value: A human-readable message indicating the cause of the error. o contact Value: (optional) Contact address for the administrator of the sever. The contact address may take any form, as it is intended to be displayed to a person. o reference Value: (optional) A reference token, such as a support ticket number or a URL to a news blog, etc. The OP MAY add additional fields to this response. 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 OP. Indirect communication is used for authentication requests (Section 9) and authentication responses (Section 10). 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 depending on capabilities, message size, or other external factors. All indirect messages arrive as HTTP requests, and so contain the required fields listed in Section 4.1.2. 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 specs@openid.net [Page 12] OpenID Authentication 2.0 - Draft 11 January 2007 string, as specified in Section 4.1.2. 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, for example by using JavaScript. The