OpenID Authentication 2.0 - Pre-Draft 11

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 software. OpenID is not tied to the use of cookies or any other specific mechanism of Relying Party 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.

Table of Contents

1.  Requirements Notation
2.  Terminology
3.  Protocol Overview
4.  Data Formats
    4.1.  Protocol Messages
    4.2.  Integer Representations
5.  Communication Types
    5.1.  Direct Communication
    5.2.  Indirect Communication
6.  Generating Signatures
    6.1.  Procedure
    6.2.  Signed List Algorithm
    6.3.  Signature Algorithms
7.  Initiation and Discovery
    7.1.  Initiation
    7.2.  Normalization
    7.3.  Discovery
8.  Establishing Associations
    8.1.  Association Session Request
    8.2.  Association Session Response
    8.3.  Association Types
    8.4.  Association Session Types
9.  Requesting Authentication
    9.1.  Request Parameters
    9.2.  Realms
    9.3.  Immediate Requests
10.  Responding to Authentication Requests
    10.1.  Positive Assertions
    10.2.  Negative Assertions
11.  Verifying Assertions
    11.1.  Checking the Nonce
    11.2.  Verifying Signatures
    11.3.  Verifying Discovered Information
    11.4.  Identifying the end user
12.  OpenID Authentication 1.1 Compatibility
    12.1.  Updated Initiation and Discovery
    12.2.  Security improvements
    12.3.  Extensions
    12.4.  Implementing OpenID 1.1 Authentication Compatibility
13.  Extensions
14.  Discovering OpenID Relying Parties
15.  Security Considerations
    15.1.  Preventing Attacks
    15.2.  User-Agents
    15.3.  User Interface Considerations
    15.4.  HTTP and HTTPS URL Identifiers
    15.5.  Denial of Service Attacks
    15.6.  Protocol Variants
Appendix A.  Examples
Appendix A.1.  OP-Specific Identifiers
Appendix A.2.  XRDS
Appendix A.3.  HTML Identifier Markup
Appendix A.4.  Login Form
Appendix A.5.  XRI CanonicalID
Appendix B.  Diffie-Hellman Key Exchange Default Value
16.  Normative References
§  Authors' Addresses

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

Identifier:

An Identifier is either a "http" or "https" URI, (commonly referred to as a "URL" within this document), or an XRI (Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” .) [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] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .).

Relying Party:

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

OpenID Provider:

OP. The party operating 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, discovered by dereferencing the end user's Identifier. This value MUST be an absolute URL.

User-supplied Identifier

An Identifier that was presented by the end user to the Relying Party. During the initiation phase of the protocol, an end user may enter either a Public Identifier or an OP Identifier. If an OP Identifier is used, the OP may then assist the end user in selecting either a Public Identifier or a Private 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 Identifier. The Claimed Identifier is either:

• The Identifier obtained by normalizing (Normalization) the User-supplied Identifier, if it was an URL.
• The CanonicalID (XRI and the CanonicalID Element), if it was an XRI.

OP-Specific Identifier:

An alternate Identifier for an end user that is specific to a particular OP and thus not necessarily under the end user's control.

OP Identifier:

An Identifier for an OpenID Provider.

Public Identifier:

An Identifier that is intended to be public information and not specific to the end user's relationship with one or more Relying Parties, for example a blog URL or an i-name.

Private Identifier:

An Identifier that is intended to be private information used only in the context of the end user's relationship with one or more specific Relying Parties.

Diffie-Hellman Key Exchange:

Diffie-Hellman Key Exchange [RFC2631] (Rescorla, E., “Diffie-Hellman Key Agreement Method,” .) is a protocol that allows two parties to create a shared a secret, while preventing eavesdroppers from learning the secret.

3.  Protocol Overview

1. The end user initiates authentication (Initiation) by presenting a User-supplied Identifier to the Relying Party via their User-Agent.
2. After normalizing the User-supplied Identifier, The Relying Party performs discovery (Discovery) on it and establishes the URL of the OP's OpenID Authentication service endpoint that the end user uses for authentication.
3. (optional) The Relying Party and the OP establish an association (Establishing Associations) -- a shared secret established using Diffie-Hellman Key Exchange. 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.
4. The Relying Party redirects the end user's User-Agent to the OP with an OpenID Authentication request (Requesting Authentication).
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 cyrptographic proof asserting either that authentication is approved (Positive Assertions) or authentication failed (Negative Assertions).
7. The Relying Party verifies (Verifying Assertions) the information received from the OP including checking the nonce, verifying the signature by using either the shared key established during the association or by sending a direct request to the OP, and verifying the discovered information.

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 (Yergeau, F., “UTF-8, a transformation format of Unicode and ISO 10646,” .) [RFC3629]. Messages MUST NOT contain multiple parameters with the same name.

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 (Direct Response) 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] (W3C, “HTML 4.01 Specification,” .). 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, the application processing the HTTP request MUST only use the values in the POST body and MUST ignore any GET parameters.

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] (Berners-Lee, T., “Uniform Resource Identifiers (URI): Generic Syntax,” .) 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"

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 (Establishing Associations) and verifying authentication assertions (Verifying Directly with the OpenID Provider).

5.1.1.  Direct Request

The message MUST be encoded as a POST body, as specified by Section 4.1.2 (HTTP Encoding).

All direct requests must contain the following field:

• openid.ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the request to be a valid OpenID 2.0 direct request.

5.1.2.  Direct Response

The body of a response to a Direct Request (Direct Request) consists of an HTTP Response body in Key-Value Form (Key-Value Form Encoding). The content-type of the response SHOULD be "text/plain".

All direct responses must contain the following field:

• ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 direct response.

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 MUST be a Key-Value Form Section 4.1.1 (Key-Value Form Encoding) message with the following fields:

• ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 direct error response.

• error

  Value: Unstructured text error message.

• 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.

• reference

  Value: (optional) A reference identifier, 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 (Requesting Authentication) and authentication responses (Responding to Authentication Requests).

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 (HTTP Encoding). 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 must contain the following fields:

• openid.ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the message to be a valid OpenID 2.0 indirect message.

• openid.mode

  Indirect messages can be identified by the presence and value of the this parameter.

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 (HTTP Encoding).

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 <form> element's "action" attribute value MUST be the URL of the receiving Web site. Each Key-Value pair MUST be included in the form as an <input> element. The key MUST be encoded as the "name" attribute and the value as the "value" attribute, such that the User-Agent will generate a message as specified in Section 4.1.2 (HTTP Encoding) when the form is submitted. The form MUST include a submit button.

5.2.3.  Indirect Error Responses

In the case of a malformed request or one that contains invalid arguments, the OpenID Provider MUST redirect the User-Agent to the "openid.return_to" URL value if the value is present and it is a valid URL.

• openid.ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 indirect error response.

• openid.mode

  Value: "error"

• openid.error

  Value: Unstructured text error message.

• openid.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.

• openid.reference

  Value: (optional) A reference identifier, such as a support ticket number or a URL to a news blog, etc.

The server MAY add additional keys to this response.

If the malformed or invalid message is received by the Relying Party, or "openid.return_to" is not present or its value is not a valid URL, the server SHOULD return a response to the end user indicating the error and that it is unable to continue.

6.  Generating Signatures

The most common usage of an association is as a Message Authentication Code (MAC) key used to sign OpenID Authentication messages.

When generating MAC keys, the recommendations in [RFC1750] (Eastlake, D., Crocker, S., and J. Schiller, “Randomness Recommendations for Security,” .) SHOULD be followed.

6.1.  Procedure

To generate a message signature:

1. Determine the appropriate list of keys to be signed and signature algorithm from the association type (Establishing Associations).
2. Generate the list of key/value pairs to be signed using the correct list algorithm (Signed List Algorithm).
3. Convert the list of key/value pairs to be signed to an octet string by encoding with Key-Value Form Encoding (Key-Value Form Encoding).
4. Apply the correct signature algorithm (Signature Algorithms) to the octet string.

6.2.  Signed List Algorithm

The input to the Signed List Algorithm are the message to be signed, and the list of message keys that are to be signed with the "openid." prefix removed.

To compute the list of key/value pairs to be signed:

1. Iterate through the list of keys to be signed in the order they appear in the input to the algorithm. For each key, find the value in the message whose key is equal to the signed list key prefixed with "openid."
2. Append the signed list key and the associated value to the list of key/value pairs to be signed.

The output of this algorithm is the list of key/value pairs to be signed, and the list of keys to be signed. A message signed using this algorithm MUST append the list of signed fields to the message.

As the algorithm strips the "openid." prefix from message keys while looking for a match, it MUST only sign elements that have keys beginning with "openid." This is to prevent attacks where the Relying Party is malicious and tries to have the OP sign arbitrary data.

6.3.  Signature Algorithms

OpenID Authentication supports two signature algorithms:

• HMAC-SHA1([RFC2104] (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” .) and [RFC3174] (Eastlake, D. and P. Jones, “US Secure Hash Algorithm 1 (SHA1),” .))
• HMAC-SHA256 ([RFC2104] (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” .) and [FIPS180‑2] (U.S. Department of Commerce and National Institute of Standards and Technology, “Secure Hash Signature Standard,” .)

HMAC-SHA1 is the default for authentication requests though the use of HMAC-SHA256 is RECOMENDED. At the time of writing this document, library support for SHA256 seems lacking.

7.  Initiation and Discovery

7.1.  Initiation

To initiate OpenID Authentication, the Relying Party SHOULD present the end user with a form that has a field for entering an Identifier.

It is RECOMMENDED that a Relying Party place the OpenID logo at the beginning of the form field where the end user enters their Identifier. This aides in end user recognition that they can use an OpenID enabled Identifier at the Relying Party.

The form field's "name" attribute SHOULD have the value "openid_identifier" as to allow User-Agents to automatically prefill the end user's preferred Identifier when visiting a Relying Party. Browser extensions or other software that support OpenID Authentication may not detect a Relying Party's support if the value is not this value.

7.2.  Normalization

The end user's input MUST be normalized into an Identifier. If the end user supplies input that does not include a scheme (http, https, or xri), then the application needs to determine if the input is an XRI or a URL missing the scheme.

To do so, the Relying Party SHOULD examine the first character of the input. If it is an XRI Global Context Symbol ("=", "@", "+", "$", or "!" see Section 2.2.1.2 of (Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0,” .) [XRI Syntax 2.0]), then the input SHOULD be treated as an XRI. If it is not, then the input SHOULD be treated as an http URL, and prefixed with the string "http://". See Section 11.4.1 (HTTP and HTTPS URL Identifiers) for more information.

URL identifiers MUST then be further normalized by both following redirects when retrieving their content and finally applying the rules in Section 6 of [RFC3986] (Berners-Lee, T., “Uniform Resource Identifiers (URI): Generic Syntax,” .) to the final destination URL. This final URL MUST be noted by the Relying Party as the Claimed Identifier and be used during future requests.

7.3.  Discovery

Discovery is the process where the Relying Party uses the Identifier to look up ("discover") the necessary information for initiating requests. OpenID Authentication has three paths through which to do discovery:

1. If the identifier is an XRI, [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,” .) will yield an XRDS document that contains the necessary information.
2. If it is a URL, the Yadis protocol (Miller, J., “Yadis Specification 1.0,” .) [Yadis] SHALL be first attempted. If it succeeds, the result is again an XRDS document.
3. If the Yadis protocol fails or no Service Elements (Service Elements) are found in the XRDS document, the URL is retrieved and HTML-based discovery (HTML-Based Discovery) SHALL be attempted.

7.3.1.  Discovered Information

Upon successful completion of discovery, the Relying Party will have the following information (see the Terminology section for definitions):

OP Endpoint URL:

The absolute URL on the OP that accepts authentication requests.

Claimed Identifier:

(optional) The identifier that is the subject of this authentication request. This is:

The Identifier obtained by normalizing (Normalization) the User-supplied Identifier, if it was an URL.

The CanonicalID (XRI and the CanonicalID Element), if the User-supplied Identifier was an XRI.

OP-Specific Identifier:

(optional) An identifier that allows an OP to identify the end user of a Claimed Identifier. If no OP-specific identifier is present in the discovered information, the Claimed Identifier is also the OP-Specific Identifier.

Protocol Version:

The OpenID protocol version of the discovered OpenID Provider(s). This is determined by the <xrd:Type> tag of the OP Identifier Element.

7.3.2.  XRDS-Based Discovery

If XRI or Yadis discovery was used, the result will be an XRDS Document. This is a XML document with entries for services that are related to the Identifier. It 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]. See Appendix A.2 (XRDS) for an example XRDS document.

7.3.2.1.  Service Elements

7.3.2.1.1.  OP Identifier Element

An OP Identifier Element is a <xrd:Service> element with the following information:

An <xrd:Type> tag whose text content is "http://openid.net/server/2.0".

An <xrd:URI> tag whose text content is the OP Endpoint URL

7.3.2.1.2.  Claimed Identifier Element

A Claimed Identifier Element is an <xrd:Service> element with the following information:

An <xrd:Type> tag whose text content is "http://openid.net/signon/2.0".

An <xrd:URI> tag whose text content is the OP Endpoint URL.

An <openid:Delegate> tag (optional) whose text content is the OP-Specific Identifier.

7.3.2.2.  Extracting Authentication Data

Once the Relying Party 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 an OP Identifier Element. If none is found, the RP will search for a Claimed Identifier Element.

7.3.2.3.  XRI and the CanonicalID Element

When the identifier is an XRI, the <xrd:XRD> element that contains the OpenID Authentication <xrd:Service> element MUST also contain a <CanonicalID> element. The content of this element MUST be used as the Claimed Identifier (see Section 11.4 (Identifying the end user)). This is a vital security consideration because a primary purpose of the <CanonicalID> element is to assert a persistent identifier that will never be reassigned, thus preventing the possibility of an XRI being "taken over" by a new registrant.

The Relying Party MUST confirm that the provider of the XRD that contains the <CanonicalID> element is authoritative for that Canonical ID. The provider is identified by the contents of the <xrd:ProviderID> element that is a child of the <xrd:XRD> element. If the provider is not authoritative for the Canonical ID, the Relying Party MUST resolve the Canonical ID to confirm the OP Endpoint URL information that was discovered. The information discovered when resolving the canonical ID MUST match the information discovered when resolving the User-supplied Identifier.

When using XRI resolution, the canonical ID MUST be used as the Claimed Identifier. For an XRI to be a valid identifier, both the <ProviderID> and <CanonicalID> MUST be present in the discovered XRDS document.

When using URL-based identifiers, the CanonicalID element SHOULD be ignored if present.

7.3.2.4.  Additional Information

The "openid" namespace is "http://openid.net/signon/2.0". The "xrd" namespace is "xri://$xrd*($v*2.0)".

For compatibility with deployed code, it is RECOMMENDED that a Relying Party also accept "http://openid.net/signon/1.0" or "http://openid.net/signon/1.1" for the value of <xrd:Type>. When one of these values is used, the Relying Party MUST use OpenID Authentication 1.1 Compatibility (OpenID Authentication 1.1 Compatibility).

If an OpenID OP supports extensions (Section 13 (Extensions)), the extensions SHOULD be listed as additional <xrd:Type> child elements of the <xrd:Service> element.

7.3.3.  HTML-Based Discovery

OpenID Authentication 1.1 HTML-based discovery MUST be supported by Relying Parties. If a Relying Party locates an OP using HTML-based discovery, it MUST use OpenID Authentication 1.1 Compatibility (OpenID Authentication 1.1 Compatibility) when communicating with that OP.

To use HTML-based discovery, an HTML document MUST be available at the URL of the Claimed Identifier. In the HEAD section of the document:

A <LINK> tag MUST be included with attributes "rel" set to "openid.server", and "href" set to an OP Endpoint URL

A <LINK> tag MAY be included with attributes "rel" set to "openid.delegate" and "href" set to the end user's OP-Specific Identifier

The host of the HTML document MAY be different from the end user's OP's host.

The "openid.server" and "openid.delegate" URLs MUST NOT include entities other than "&amp;", "&lt;", "&gt;", and "&quot;". Other characters that would not be valid in the HTML document or that cannot be represented in the document's character encoding MUST be escaped using the percent-encoding (%xx) mechanism described in [RFC3986] (Berners-Lee, T., “Uniform Resource Identifiers (URI): Generic Syntax,” .).

8.  Establishing Associations

An "association" is a shared secret between the OP and Relying Party. Once established, it is used to verify subsequent protocol messages and reduces round trips.

It is RECOMMENDED that a Relying Party form associations if it is possible for it to do so. If a Relying Party is incapable of creating or storing associations, Section 11.2 (Verifying Signatures) provides an alternate verification mechanism referred to as Stateless Mode (note that this was referred to as "dumb mode" in previous versions of this specification).

8.1.  Association Session Request

An association session is initiated by a direct request (Direct Communication) from a Relying Party to an OP Endpoint URL with the "openid.mode" key having the value of "associate".

8.1.1.  Common Request Parameters

These parameters are common to all association requests:

• openid.ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the request to be a valid OpenID 2.0 association request.

• openid.mode

  Value: "associate"

• openid.assoc_type

  The preferred association type. The association type defines the algorithm to be used to sign subsequent messages.

  Value: A valid association type from Section 8.3 (Association Types)

  Default: "HMAC-SHA1".

• openid.session_type

  The preferred association session type. This defines the method used to encrypt the association's MAC key in transit.

  Value: A valid association session type from Section 8.4 (Association Session Types).

  Note: Unless using transport layer encryption, it is NOT RECOMMENDED to use "no-encryption" on a public network, see Section 15.1.1 (Eavesdropping Attacks).

8.1.2.  Diffie-Hellman Request Parameters

The following parameters are common to requests whose requested association session type is "DH-SHA1" or "DH-SHA256":

• openid.dh_modulus

  Value: base64(btwoc(p))

  Default: See Appendix B (Diffie-Hellman Key Exchange Default Value)

• openid.dh_gen

  Value: base64(btwoc(g))

  Default: g = 2

• openid.dh_consumer_public

  Value: base64(btwoc(g ^ xa mod p))

See Section 8.4.2 (Diffie-Hellman Association Sessions) for more information on these parameters.

NOTE: the 'btwoc' function is defined in Section 4.2 (Integer Representations).

8.2.  Association Session Response

An association session response is a direct response from the OP to the Relying Party in Key-Value Form (Key-Value Form Encoding).

8.2.1.  Common Response Parameters

• ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 association response.

• session_type

  The session type for this association. If the OP is unwilling or unable to support this session type, it MUST return an unsuccessful response.

• assoc_handle

  The association handle is used as a key to refer to this association in subsequent messages.

  Value: A string 255 characters or less in length. It MUST consist only of ASCII characters in the range 33-126 inclusive (printable non-whitespace characters).

• assoc_type

  The value of the "openid.assoc_type" parameter from the request. If the OP is unwilling or unable to support this association type, it MUST return an unsuccessful response.

• expires_in

  The lifetime, in seconds, of this association. The Relying Party MUST NOT use the association after this time has expired.

  Value: An integer, represented in base 10 ASCII.

8.2.2.  Unencrypted Response Parameters

• mac_key

  The MAC key (shared secret) for this association, Base 64 (Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” .) [RFC3548] encoded.

8.2.3.  Diffie-Hellman Response Parameters

• dh_server_public

  Value: base64(btwoc(g ^ xb mod p))

  Description: The OP's Diffie-Hellman public key.

• enc_mac_key

  Value: base64(H(btwoc(g ^ (xa * xb) mod p)) XOR MAC key)

  Description: The MAC key (shared secret), encrypted with the secret Diffie-Hellman value. H is either "SHA1" or "SHA256" depending on the session type.

NOTE: The 'btwoc' function is defined in Section 4.2 (Integer Representations)

8.2.4.  Unsuccessful Response Parameters

If the OP does not support an association session type or association type, it MUST respond with a direct error message indicating that the association request failed. If there is another association session type or association type that is supported, the OP MAY include that information in the response.

• ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 association failure response.

• error

  Value: A human-readable message indicating why the association request failed.

• error_code

  Value: "unsupported-type"

• session_type

  Value: A valid association session type from Section 8.4 (Association Session Types) that the OP supports.

• assoc_type

  Value: (optional) An association type supported by the OP from Section 8.3 (Association Types).

Upon receipt of an "unsupported-type" response, the Relying Party MAY make another request with the specified association session type and association type. If no association is established, the Relying Party MAY continue the authentication process in stateless mode.

8.3.  Association Types

8.3.1.  HMAC-SHA1

An association of type "HMAC-SHA1" uses the HMAC-SHA1 (Signature Algorithms) signature algorithm in combination with the Signed List (Signed List Algorithm) algorithm.

8.3.2.  HMAC-SHA256

An association of type "HMAC-256" uses the HMAC-SHA256 (Signature Algorithms) signature algorithm in combination with the Signed List (Signed List Algorithm) algorithm.

8.4.  Association Session Types

OpenID Authentication defines three valid association session types: "no-encryption", "DH-SHA1", and "DH-SHA256".

8.4.1.  No-Encryption Association Sessions

In a "no-encryption" association session, the OP sends the association MAC key in plain-text to the Relying Party. This makes it possible for an eavesdropper to intercept the key, and forge messages to this Relying Party. Therefore, no-encryption association sessions SHOULD NOT be used unless the messages are using transport-level encryption. See Section 15.1.1 (Eavesdropping Attacks) for more information.

The MAC key sent by the OP MUST be the length specified for this association in Section 6.3 (Signature Algorithms).

8.4.2.  Diffie-Hellman Association Sessions

The "DH-SHA1" and DH-SHA256" association types use Diffie-Hellman Key Exchange to securely transmit the shared secret.

The MAC key MUST be the same length as the output of H, the hash function - 160 bits (20 bytes) for DH-SHA1 or 256 bits (32 bytes) for DH-SHA256, as well as the output of the signature algorithm of this association.

The Relying Party specifies a modulus, p, and a generator, g. The Relying Party chooses a random private key xa and OpenID Provider chooses a random private key xb, both in the range [1 .. p-1]. The shared secret used to encrypt the MAC key is thus g ^ (xa * xb) mod p = (g ^ xa) ^ xb mod p = (g ^ xb) ^ xa mod p. For more information, see [RFC2631] (Rescorla, E., “Diffie-Hellman Key Agreement Method,” .). For information on the selection of random values, see [RFC1750] (Eastlake, D., Crocker, S., and J. Schiller, “Randomness Recommendations for Security,” .).

9.  Requesting Authentication

Once the Relying Party has successfully performed discovery and (optionally) created an association with the discovered OP Endpoint URL, it can send an authentication request to the OP to obtain an assertion. An authentication request is an indirect request (Indirect Communication).

9.1.  Request Parameters

• openid.ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the request to be a valid OpenID Authentication 2.0 request.

  Note: If an OP receives an authentication request with this parameter missing or with a lower version number, it SHOULD still respond to the request. If it does respond it MUST use OpenID Authentication 1.1 Compatibility (OpenID Authentication 1.1 Compatibility) when communicating with that Relying Party.

• openid.mode

  Value: "checkid_immediate" or "checkid_setup"

  Note: If the Relying Party wishes the end user to be able to interact with the OP, "checkid_setup" should be used. An example of a situation where interaction between the end user and the OP is not desired is when the authentication request is happening asynchronously in JavaScript.

• openid.claimed_id

  Value: (optional) The Claimed Identifier. MUST be present if, and only if, openid.identity is present.

  Note: The Claimed Identifier is the same as the OP-Specific Identifier if a different OP-Specific Identifier is not supplied. If neither value is present, the assertion is not about an identifier, and will contain other information in its payload, using extensions (Extensions).

• openid.identity

  Value: (optional) The OP-Specific Identifier.

  Note: If this is set to the special value "http://openid.net/identifier_select/2.0" then the OP SHOULD choose an Identifier that belongs to the end user. This parameter MAY be omitted if the request is not about an identifier (for instance if an extension is in use that makes the request meaningful without it; see openid.claimed_id above).

• openid.assoc_handle

  Value: (optional) A handle for an association between the Relying Party and the OP that SHOULD be used to sign the response.

  Note: If no association handle is sent, the transaction will take place in stateless mode.

• openid.return_to

  Value: (optional) URL to which the OP SHOULD return the User-Agent with the response indicating the status of the request.

  Note: If this value is not sent in the request it signifies that the Relying Party does not wish to for the end user to be returned to it as something else useful will have been performed via an extension. If the RP needs to ensure that query parameters are not modified by outside parties, it must prevent this through an out-of-band method.

• openid.realm

  Value: (optional) URL pattern the OP SHOULD ask the end user to trust. See Section 9.2 (Realms). This value MUST be sent if openid.return_to is ommitted.

  Default: return_to URL

9.2.  Realms

A "realm" is a pattern that represents the part of URL-space for which an OpenID Authentication request is valid. A realm is designed to give the end user an indication of the scope of the authentication request. OPs SHOULD present the realm when requesting the end user's approval for an authentication request. OPs MAY use the realm to allow the end user to automate approval of authentication requests. The realm SHOULD be used by OPs to uniquely identify Relying Parties.

A realm pattern is a URL, with the following changes:

• A realm MUST NOT contain a URI fragment
• A realm MAY contain a wild-card at the beginning of the URL authority section. A wild-card consists of the characters "*." prepended to the DNS name in the authority section of the URL.

A URL matches a realm if:

• The URL scheme and port of the URL are identical to those in the realm. See RFC 3986 (Berners-Lee, T., “Uniform Resource Identifiers (URI): Generic Syntax,” .) [RFC3986], section 3.1 for rules about URI matching.
• The URL's path is equal to or a sub-directory of the realm's path.
• Either:
  1. The realm's domain contains the wild-card characters "*.", and the trailing part of the URL's domain is identical to the part of the realm following the "*." wildcard, or
  2. The URL's domain is identical to the realm's domain

When present, the "openid.return_to" URL MUST match the "openid.realm", or the OP MUST return an error.

It is RECOMMENDED that OP's protect their end users from requests with overly-general realms, like http://*.com/ or http://*.co.uk/. Determining if a realm is overly-general is at the discretion of the OP.

9.3.  Immediate Requests

When requesting authentication, the Relying Party MAY request that the OP not interact with the end user. In this case the OP MUST respond immediately with either an assertion that authentication is successful, or a response indicating that the request cannot be completed without further user interaction. This is accomplished by an authentication request with "openid.mode" set to "checkid_immediate".

10.  Responding to Authentication Requests

When an authentication request comes from the User-Agent via indirect communication (Indirect Communication), the OP SHOULD identify the User-Agent, and determine whether the end user wishes to complete the authentication. If the end user can be identified and wishes to complete the authentication, the OP should send a positive assertion (Positive Assertions) to the Relying Party.

Methods of identifying and authenticating the end user and obtaining approval to return an OpenID Authentication assertion are beyond the scope of this specification.

If the relying party requested OP-driven identifier selection by setting "openid.identity" to "http://openid.net/identifier_select/2.0" and there are Identifiers in the control of the end user, the OP SHOULD allow the end user to choose which Identifier to use.

If the Relying Party supplied an association handle with the authentication request, the OP SHOULD attempt to look up an association based on that handle. If the association is missing or expired, the OP SHOULD send the "openid.invalidate_handle" parameter as part of the response with the value of the request's "openid.assoc_handle" parameter, and SHOULD proceed as if no association handle was specified.

If no association handle is specified, the OP SHOULD create a private association for signing the response. The OP MUST store this association and MUST respond to later requests to check the signature of the response in stateless mode (Verifying Signatures).

If the "openid.return_to" value is ommitted in the request, it signifies that the initiating server does not wish to for the end user to be returned to it as something else useful will have been performed via an extension.

10.1.  Positive Assertions

Positive assertions are indirect responses (Indirect Communication) with the following fields:

• openid.ns

  Value: "http://openid.net/signon/2.0"

  Note: This defines the interpretation of the OpenID Authentication arguments without a namespace. To be an OpenID Authentication 2.0 response, the given value MUST be present.

• openid.mode

  Value: "id_res"

• openid.claimed_id

  Value: (optional) The Claimed Identifier. MUST be present if, and only if, openid.identity is present.

  Note: The Claimed Identifier is the same as the OP-Specific Identifier if a different OP-Specific Identifier is not supplied. If neither value is present, the assertion is not about an identifier, and will contain other information in its payload, using extensions (Extensions).

• openid.identity

  Value: (optional) The OP-Specific Identifier

  Note: Relying Parties MUST accept assertions about Identifiers for which they have not requested authentication. OpenID Providers MAY assist the end users in selecting the Claimed and OP-Specific Identifiers about which the assertion is made. The openid.identity field MAY be omitted if an extension is in use that makes the response meaningful without it (see openid.claimed_id above).

• openid.return_to

  Value: Verbatim copy of the return_to URL parameter sent in the request.

• openid.response_nonce

  Value: A string that MUST be unique to this particular successful authentication response. The nonce MUST start with the current time on the server, and MAY have additional characters appended to the end as necessary to make each response unique. The date and time MUST be formatted as specified in section 5.6 of [RFC3339] (Newman, C. and G. Klyne, “Date and Time on the Internet: Timestamps,” .), with the following restrictions:

  • All times must be in the UTC timezone, indicated with a "Z".
  • No fractional seconds are allowed

  For example: 2005-05-15T17:11:51ZUNIQUE

• openid.invalidate_handle

  Value: (optional) If the Relying Party sent an invalid association handle with the request, it SHOULD be included here.

• openid.assoc_handle

  Value: The handle for the association that was used to sign this assertion.

• openid.signed

  Value: Comma-separated list of signed fields.

  Note: This entry consists of the fields without the "openid." prefix that the signature covers. This list MUST contain at least "return_to" and "response_nonce", and if present in the response, "claimed_id" and "identity". For example, "identity,claimed_id,return_to,response_nonce".

• openid.sig

  Value: Base 64 encoded signature calculated as specified in Section 6 (Generating Signatures).

  Note: Successful authentication messages from the OP to the Relying Party MUST be signed.

10.2.  Negative Assertions

If the OP is unable to identify the end user or the end user does not or cannot approve the authentication request, the OP SHOULD send a negative assertion to the Relying Party as an indirect response (Indirect Communication).

When receiving a negative assertion in response to an immediate mode request, Relying Parties SHOULD construct a new authentication request using the "checkid_setup" mode to complete the transaction. This is a change from OpenID Authentication 1.1 and more details can be found in Section 12 (OpenID Authentication 1.1 Compatibility).

10.2.1.  In Response to Immediate Requests

If the request was an immediate request, there is no chance for the end user to interact with pages on the OP to provide identifying credentials or approval of a request. A negative assertion of an immediate request takes the following form:

• openid.ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 immediate negative assertion.

• openid.mode

  Value: "id_res"

10.2.2.  In Response to Non-Immediate Requests

Since the OP may display pages to the end user and request credentials from the end user, a negative response to a request that is not immediate is definitive. It takes the following form:

• openid.ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 non-immediate negative assertion.

• openid.mode

  Value: "cancel"

In a lot of cases, the Relying Party won't get a cancel mode response; the end user will just quit or press back within their User-Agent. But if it is returned, the Relying Party SHOULD return to what it was doing.

11.  Verifying Assertions

When the Relying Party receives a positive assertion, it MUST verify the following before accepting the assertion:

• An assertion has not yet been accepted from this OP with the same value for "openid.response_nonce"
• The signature on the assertion is valid
• Discovered information from the Identifier matches the information in the assertion.

If all three of these conditions are met, the Claimed Identifier in the response is now verified.

11.1.  Checking the Nonce

To prevent replay attacks, the agent checking the signature SHOULD keep track of the nonce values included in positive assertions and never accept the same value more than once for the same OP Endpoint URL. When using "check_authentication", the OP is responsible for preventing replay attacks. When the Relying Party checks the signature on an assertion, it is responsible for preventing replay attacks.

The time-stamp may be used to reject responses that are too far away from the current time, limiting the amount of time that nonces must be stored to prevent attacks. The acceptable range is implementation dependent. A larger range requires storing more nonces for a longer time. A shorter range increases the chance that clock-skew and transaction time will cause a spurious rejection.

11.2.  Verifying Signatures

If the Relying Party has stored an association with the association handle specified in the assertion, it MUST check the signature on the assertion itself. If it does not have an association stored, it MUST request that the OP verify the signature (Verifying Directly with the OpenID Provider) via Stateless mode.

11.2.1.  Verifying with an Association

The Relying Party follows the same procedure that the OP followed in generating the signature (Generating Signatures), and then compares the signature in the response to the signature it generated. If the signatures do not match, the assertion is invalid.

If an authentication request included an association handle for an association between the OP and the Relying party, and the OP no longer wishes to use that handle (because it has expired or the secret has been compromised, for instance), the OP will send a response that must be verified directly with the OP, as specified in Section 11.2.2 (Verifying Directly with the OpenID Provider). In that instance, the OP will include the field "openid.invalidate_handle" set to the association handle that the Relying Party included with the original request.

11.2.2.  Verifying Directly with the OpenID Provider

To verify a signature directly with the OP, the Relying Party sends a direct request (Direct Request) to the OP. This is known as Stateless mode.

11.2.2.1.  Request Parameters

• openid.mode

  Value: "check_authentication"

• Exact copies of all fields from the authentication response, except for "openid.mode".

11.2.2.2.  Response Parameters

• ns

  Value: "http://openid.net/signon/2.0"

  This value MUST be present for the response to be a valid OpenID 2.0 verification response.

• mode

  Value: "id_res"

• is_valid

  Value: "true" or "false"

  Description: Boolean; whether the signature is valid.

• invalidate_handle

  Value: (optional) An association handle

  Description: The association handle sent in the request, if the server confirms that it is invalid.

An OP MUST NOT verify signatures for associations that have shared MAC keys. If an OP did verify signatures for associations with shared MAC keys, it would be possible for parties other than the OP to create valid assertions that seemed to come from the OP.

The OP SHOULD only return "is_valid" once for each authentication response. An authentication response may be identified by its "openid.response_nonce" value.

If the OP responds with "is_valid" set to "true", and "invalidate_handle" is present, the Relying Party SHOULD NOT send further authentication requests with that handle. "invalidate_handle" will only be present when the original authentication request to the OP included an association that the OP deemed invalid. This implies that it will only be present in this response if it was also present in the "id_res" response (Positive Assertions). Including "invalidate_handle" in the direct verification is necessary to prevent an attacker from invalidating an association at will by adding it to an authentication response.

11.3.  Verifying Discovered Information

The Claimed Identifier MUST have been discovered (Discovery) by the Relying Party and the information in the assertion MUST exactly match the discovered information.

If the Claimed Identifier was not present in the request ("openid.identity" was "http://openid.net/identifier_select/2.0"), the Relying Party MUST perform discovery on the Identifier in the response to make sure that the OP is authorized to make assertions about the Claimed Identifier.

11.4.  Identifying the end user

The Claimed Identifier in a successful authentication response MAY be used as a user-visible Identifier. The Relying Party SHOULD use it as a key for local storage of information about the end user.

If an assertion is made for a Claimed Identifier which has not been discovered, the Relying Party MUST perform discovery on that Identifier and verify that the discovered information matches that in the assertion, including that the OP is authoritative for the Identifier.

11.4.1.  HTTP and HTTPS URL Identifiers

Relying Parties MUST differentiate between URL Identifiers that have different schemes. When user input is processed into a URL, it is processed into a HTTP URL. If the same end user controls the same URL, differing only by scheme, and it is desired that the Identifier be the HTTPS URL, it is RECOMMENDED that a redirect be issued from the HTTP URL to the HTTPS URL. Because the HTTP and HTTPS URLs are not equivalent and the Identifier that is used is the URL after following redirects, there is no reduction in security when using this scheme. If an attacker could gain control of the HTTP URL, it would have no effect on the HTTPS URL, since the HTTP URL is not ever used as an Identifier.

12.  OpenID Authentication 1.1 Compatibility

This specification is based on the original specification for OpenID Authentication as written by Brad Fitzpatrick. That specification did not have a version number, but was called OpenID 1.0, and then OpenID 1.1 when it was revised. The protocol outlined in this specification is intended to be backwards-compatible with the revised OpenID protocol. The changes to the specification are outlined in this section.

12.1.  Updated Initiation and Discovery

• Supports OP Identifiers. This new variation of the protocol flow is initiated by an end user entering an OP Identifier instead of a Public Identifier. This allows the OP to assist the end user in selecting an Identifier, which may be either a Public Identifier (one of multiple "personas"), or a Private Identifier (which may be generated by the OP to be used only in the context of a single RP).
• Supports the use of XRIs as Identifiers. XRIs may be used as Identifiers for both end users and OPs, and provide automatic mapping from one or more reassignable i-names to a synonymous persistent Canonical ID that will never be reassigned.
• When URLs are used as Identifiers, they are normalized according to the guidelines in [RFC3986] (Berners-Lee, T., “Uniform Resource Identifiers (URI): Generic Syntax,” .), for better compatibility with existing Web infrastructure.
• Uses the Yadis protocol for discovery. This allows for using multiple OPs for a single Identifier, for load-balancing and fallback in the case of OP failure. Additionally, it allows for discovery of supported extensions and other associated services.

12.2.  Security improvements

A nonce is now part of the protocol for built-in protection against replay attacks, which was previously implemented out-of-band by each library or application.

A new association type, HMAC-SHA256, and a new association session type, DH-SHA256, allow for stronger signatures on authentication assertions.

12.3.  Extensions

Extensions are now an officially supported mechanism to support data exchange and other Relying Party-OP communication along with the authentication exchange. Extensions allow for the exchange of arbitrary attributes, as well as for protocol extensions, such as the inclusion of additional information about the Relying Party in the authentication request.

Because extensions can transfer arbitrary data, the Identifier is now optional in authentication messages.

12.4.  Implementing OpenID 1.1 Authentication Compatibility

OpenID Authentication 2.0 implementations SHOULD support OpenID Authentication 1.1 compatibility, unlesss security considerations make it undesirable.

All messages in OpenID Authentication 1.1 omit the "openid.ns" parameter, which is an easy way for an RP to determine if the message is from an OpenID Authentication 1.1 endpoint. OpenID Authentication 1.1 supports only HMAC-SHA1 associations.

12.4.1.  Relying Parties

• Relying Parties MUST implement HTML-Based Discovery (HTML-Based Discovery).
• Relying Parties SHOULD extract and use OpenID 1.x service elements from XRDS documents, if Yadis succeeds on an URL identifier. Such service elements are identified by <xrd:Type> tags whose text contents are "http://openid.net/server/1.0" or "http://openid.net/server/1.1". Although this is not specified in the previous version of the protocol, it is a generally accepted practice of advertising OpenID 1.x services through Yadis.
• "openid.identity" MUST be sent in a authentication request (Responding to Authentication Requests).
• Relying Parties MUST send a blank session_type parameter in "no-encryption" association requests.
• Relying Parties MUST accept a "no-encryption" association response with a blank or missing session_type parameter, if they choose to accept "no-encryption" sessions.
• In authentication requests (Requesting Authentication), the "openid.identity" parameter MUST NOT be the special value "http://openid.net/identifier_select/2.0", because OpenID Authentication 1.1 does not support the use of OP Identifiers.
• The "openid.realm" parameter in authentication requests was known as "openid.trust_root". The syntax and meaning are identical.
• When responding with a negative assertion to a "checkid_immediate" mode authentication request, the "user_setup_url" paramater MUST be returned. This is a URL that the end user may visit to complete the request. The OP may redirect the end user to this URL, or provide the end user with a link that points to this URL.
• The Relying Party MUST accept an authentication response (Positive Assertions) that is missing the "openid.response_nonce" parameter. It SHOULD however implement an out-of-band method for preventing replay attacks.

12.4.2.  OpenID Providers

• "openid.identity" MUST be sent in a positive authentication assertion (Positive Assertions).
• OPs MUST accept a "no-encryption" association request with a blank session_type parameter, if they choose to accept "no-encryption" sessions.
• OPs MUST accept association requests with no assoc_type parameter, and assume them to be of type HMAC-SHA1.
• Unsuccessful association responses (Unsuccessful Response Parameters) MUST NOT be sent, since they are not part of the OpenID Authentication 1.1 protocol.
• OPs MAY choose to return a successful "no-encryption" response to any association request.
• Omit or set to blank the "session_type" parameter when making "no-encryption" responses to association requests.
• The "openid.realm" parameter in authentication requests was known as "openid.trust_root". The syntax and meaning are identical.
• When responding with a negative assertion to a "checkid_immediate" mode authentication request, the "user_setup_url" paramater MUST be returned. This is a URL that the end user may visit to complete the request. The Relying Party may redirect the end user to this URL, or provide the end user with a link that points to this URL.

13.  Extensions

An Extension to OpenID Authentication is a protocol that "piggybacks" on the authentication request and response. Extensions are useful for providing extra information about an authentication request or response as well as providing extra information about the subject of the authentication response.

OpenID extensions are identified by a Type URI. The Type URI MAY be used as the value of an <xrd:Type> element of an OpenID <xrd:Service> element in an XRDS document associated with a Claimed Identifier. The Type URI is also used to associate key-value pairs in messages with the extension.

To associate keys and values in a message with an extension, the key MUST be associated with the Type URI. To associate keys with a Type URI, establish an alias by adding a key prefixed with "openid.ns." and ending with the alias text whose value is the Type URI. Once an alias has been established, all pairs in the message whose keys start with "openid." followed by the alias text, followed by a period or the end of the key are associated with that extension.

A namespace alias MUST NOT contain a period, MUST NOT be the name of a field in a message defined in this specification, and MUST NOT be the same as another namespace alias in the same message. A namespace MUST NOT be assigned more than one alias in the same message. If a message is a response to another message, the response MAY use a different alias to refer to the same namespace.

Non-normative example:

An extension's type URI is "<http://example.com/ext/1.0>".

openid.ns.x=http://example.com/ext/1.0

openid.x=example

openid.x.foo=bar

openid.xx=notx

In this example, the keys openid.x and openid.x.foo are associated with the extension; the openid.xx key is not.

Extensions MUST NOT define parameters with the same name. It is RECOMMENDED that commas are used as value delimiters, though other characters may be better suited in certain situations. Another approach is to append a numeric value to each key to differentiate between each value.

14.  Discovering OpenID Relying Parties

Relying Parties are RECOMMENDED to use the Yadis protocol to publish their return_to URL. This allows for automated discovery of OpenID Relying Parties.

In this case, the XRDS document published by the Relying Party, SHOULD have an <xrd:Service> element where the content of the <xrd:URI> tag is the return_to URL and the content of the <xrd:Type> tag is "http://openid.net/return_to/2.0".

For example:

<Service xmlns="xri://$xrd*($v*2.0)">
  <Type>http://openid.net/return_to/2.0</Type>
  <URI>http://consumer.example.com/return</URI>
</Service>

15.  Security Considerations

15.1.  Preventing Attacks

15.1.1.  Eavesdropping Attacks

There are two places in this protocol that are vulnerable to eavesdropping attacks. An eavesdropper could intercept an unencrypted association session and recover the shared secret, allowing an attacker to masquerade as the OP to that relying party. An eavesdropper could also intercept a successful authentication assertion and re-use it, if the nonce is not checked.

Both of these attacks can be prevented by using SSL for these connections. The association session can also use Diffie-Hellman Key Exchange instead of "no-encryption" to protect from eavesdropping. If the nonce is checked in message verification, the positive authentication assertion cannot be re-used.

15.1.2.  Man-in-the-Middle Attcks

Associations prevent tampering of signed fields by a man in the middle, except during discovery, association sessions and stateless mode. Altering signed fields without the shared secret requires breaking the MAC. Currently, no tractable attack is known on the MACs used in this protocol. The quality of the protection provided by the MAC depends on the randomness of the shared MAC key, so it is important that an unguessable value be used.

If DNS resolution or the transport layer is compromised, signatures on messages are not adequate, since the attacker can impersonate the OP and issue its own associations, or its own decisions in stateless mode. If an attacker can tamper with the discovery process, he can specify any OP, and so does not have to impersonate the OP. Addtionally, 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. One method to prevent this sort of attack is by digitally signing the XRDS file as per XMLDSIG. The keying material is not specified, since the RP ultimately needs to make its own decision whether to trust keys used for such 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 attacks.

In order to get protection from SSL, SSL must be used for all parts of the interaction, including interaction with the end user through the User-Agent. While the protocol does not require SSL be used, its use is strongly RECOMMENDED. Current best practicies dictate that an OP SHOULD use SSL, with a certificate signed by a trusted authority, to secure its service endpoint. 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 Relying Party MAY choose to not complete, or even begin, a transaction if SSL is not being correctly used at these various endpoints.

15.2.  User-Agents

Since this protocol is intended to be used interactively, User-Agents will primarily be common Web browsers. Web browsers or their hosts may be infected with spyware or other malware, which limits the strength of the authentication assertion, since untrusted software makes it impossible to know whether the authentication decision has been made with the end user's approval. With that said, many web applications and protocols today rely on the security of the Web browser and their hosts.

Cross-site-scripting attacks against OPs may be used to the same effect. For the best security, OPs should not depend on scripting. This enables User-Agents that do not support scripting, or have scripting disabled, to still employ the protocol.

15.3.  User Interface Considerations

The Relying Party SHOULD redirect the end user to the OP Endpoint URL in a top-level browser window with all controls visible. This allows better protection for the end user against OP look-alike sites (phishing).

OPs SHOULD educate their end users about the potential for OpenID phishing attacks and SHOULD equip their end users with the tools to defeat such attacks, for example browser plugins that verify the authenticity of the OP's Authentication Service Endpoint URL.

15.4.  HTTP and HTTPS URL Identifiers

While these types of Identifiers have been previously discussed (HTTP and HTTPS URL Identifiers), they are worth mentioning again. As previously stated, the RECOMMENDED method of an End User expressing control over a URL differing only be scheme is to setup a redirect from the HTTP URL to the HTTPS URL. Relying Parties will never store the HTTP URL as during the discovery and initiation phase will follow the redirect and use the HTTPS URL as the Claimed Identifier.

End Users with concerns over this recommendation should directly enter their HTTPS URL at each Relying Party. This thus removes the step where the Relying Party follows the redirect to the HTTPS URL. The single security consideration currently seen is if an attacker were to compromise the integrity of the HTTP URL by removing the redirect and pointing the Identifier at a rogue OP. This however will alter the user experience, is detectable by anti-phishing technologies, and the security of the Identifier itself is a fundamental principle within OpenID.

15.5.  Denial of Service Attacks

Within the protocol there are places where a rogue RP could launch a denial of service attack against an OP since there is nothing in this message that allows the OP to quickly check that it is a genuine request. This can be done by the RP repeatedly requesting associations, authentication, or verification of a signature.

The potentially most severe attack is during the association phase as each message requires the OP to execute a discrete exponentiation. Since the RP has the ability to specify modulus and generator per message, an attacker can even force the OP to perform this exponentiation in real time prior to responding for each message.

While this could be particularly harmful, OpenID Providers can easily use generic IP based rate-limiting and banning techniques to help combat these sorts of attacks. OPs can also look at banning requests based on the "openid.realm" and "openid.return_to" values.

15.6.  Protocol Variants

The following are known variations in the protocol which may or may not directly affect the security of the use of the protocol. It is imagined that these values could be used in the creation of security profiles for this protocol. The following list of variants are from the perspective of an OpenID Provider.

Identified security variants.

Appendix A.  Examples

Non-normative

Appendix A.1.  OP-Specific Identifiers

An end user wants to use "http://www.example.com/" as their Claimed Identifier. The end user has an account with Example Provider, which functions as an OpenID Provider. The end user's OP-Specific Identifier is "https://exampleuser.exampleprovider.com/".

In this scenario, with the proper configuration of Yadis or HTML-based Discovery (see Section 7.3 (Discovery) and Appendix A.2 (XRDS) below), a Relying Party will discover the following information about the end user:

Claimed Identifier

http://www.example.com/

OP-Specific Identifier

https://exampleuser.exampleprovider.com/

Appendix A.2.  XRDS

For an end user to use "http://www.example.com/" as their Identifier, but have Relying Parties actually verify https://exampleuser.exampleprovider.com/ with the OP Endpoint URL https://www.exampleprovider.com/endpoint/, the following XML snippet should be present in the final XRD element in the XRDS file when discovery is preformed on "http://www.example.com":

<Service xmlns="xri://$xrd*($v*2.0)">
  <Type>http://openid.net/signon/2.0</Type>
  <URI>https://www.exampleprovider.com/endpoint/</URI>
  <LocalID>https://exampleuser.exampleprovider.com/</LocalID>
</Service>

Appendix A.3.  HTML Identifier Markup

To use www.example.com as their Identifier, but have Relying Parties actually verify http://exampleuser.livejournal.com/ with the OpenID Provider located at http://www.livejournal.com/openid/server.bml, the following markup should be present in the <head> of the HTML document located by the identifier URL:

<link rel="openid.server"
      href="http://www.livejournal.com/openid/server.bml"/>
<link rel="openid.delegate"
      href="http://exampleuser.livejournal.com/"/>

Appendix A.4.  Login Form

The end user visits a Relying Party site which supports OpenID Authentication. The Relying Party presents the end user with a form field for them to enter their Claimed Identifier or their OP Identifier.

For example:

              ----------------------------------
              |[logo]example.com               | [Login Button]
              ----------------------------------

Appendix A.5.  XRI CanonicalID

For example, if the XRI i-names =example and =exmpl both yield an XRDS document with the CanonicalID xri://(example)!1234 then those Identifiers should be treated as equivalent. For applications with user accounts, the persistant Canonical ID xri://(example)!1234 should be used the the primary key for the account. Although the i-names =example and =exmpl may also be stored for reference as display names, they are reassignable identifier and should not be used as persistent keys.

Appendix B.  Diffie-Hellman Key Exchange Default Value

This is a confirmed-prime number, used as the default modulus for Diffie-Hellman Key Exchange. In hexadecimal:

DCF93A0B883972EC0E19989AC5A2CE310E1D37717E8D9571BB7623731866E61E
F75A2E27898B057F9891C2E27A639C3F29B60814581CD3B2CA3986D268370557
7D45C2E7E52DC81C7A171876E5CEA74B1448BFDFAF18828EFD2519F14E45E382
6634AF1949E5B535CC829A483B8A76223E5D490A257F05BDFF16F2FB22C583AB

16. Normative References

Authors' Addresses