TOC 
DraftD. Recordon
 VeriSign
 J. Hoyt
 JanRain
 D. Hardt
 Sxip
 B. Fitzpatrick
 Six Apart
 September 10, 2006


OpenID Authentication 2.0 - Draft 09

Abstract

OpenID Authentication provides a way to prove that an End User owns an Identifier. It does this without passing around a 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.

Extensions built on top of the foundation created by OpenID Authentication provide a mechanism for exchanging arbitrary End User-related data.



Table of Contents

1.  Requirements Notation
2.  Terminology
3.  Overview
    3.1.  Protocol Flow
4.  Initiation and Discovery
    4.1.  Initiation
    4.2.  Discovery
        4.2.1.  Delegating Authentication
        4.2.2.  Discovered Information
        4.2.3.  Using Yadis or XRI Resolution
        4.2.4.  HTML-Based Discovery
5.  Data Formats
    5.1.  Key-Value Form Encoding
    5.2.  Encoding Messages to HTTP Servers
    5.3.  Example
6.  Communication Types
    6.1.  Direct Communication
        6.1.1.  Direct Request
        6.1.2.  Direct Response
    6.2.  Indirect Communication
        6.2.1.  HTTP Redirect
        6.2.2.  HTML FORM Redirection
        6.2.3.  Indirect Error Responses
7.  Establishing Associations
    7.1.  Generating Signatures
        7.1.1.  Signed List Algorithm
        7.1.2.  Sign-All Algorithm
    7.2.  Association Handles
    7.3.  Association Types
        7.3.1.  HMAC-SHA1 Associations
        7.3.2.  HMAC-SHA1-SIGNALL Associations
        7.3.3.  HMAC-SHA256-SIGNALL Associations
    7.4.  Association Sessions
        7.4.3.  Unencrypted Association Sessions
        7.4.4.  Diffie-Hellman Association Sessions
        7.4.5.  Unsuccessful Response Parameters
8.  Requesting Authentication
    8.1.  Request Parameters
    8.2.  Trust Roots
    8.3.  Immediate Requests
9.  Responding to Authentication Requests
    9.1.  Positive Assertions
    9.2.  Verifying Assertions
        9.2.1.  Verifying Discovered Information
        9.2.2.  Verifying Signatures
    9.3.  Identifying the End User
        9.3.1.  HTTP and HTTPS URL Identifiers
    9.4.  Negative Assertions
        9.4.1.  In Response to Immediate Requests
        9.4.2.  In Response to Non-Immediate Requests
10.  Extensions
11.  Discovering OpenID Relying Parties
12.  Security Considerations
    12.1.  Preventing Attacks
        12.1.1.  Eavesdropping Attacks
        12.1.2.  Man-in-the-Middle Attcks
    12.2.  User Agents
    12.3.  User Interface Considerations
Appendix A.  Examples
Appendix A.1.  Delegation
Appendix A.2.  XRDS
Appendix A.3.  HTML Identifier Markup
Appendix A.4.  Login Form
Appendix A.5.  XRI CanonicalID
Appendix B.  Diffie-Hellman Default Value
Appendix C.  Changes from the Previous OpenID Specification
Appendix C.1.  Updated Initiation and Discovery
Appendix C.2.  Security improvements
Appendix C.3.  Extensions
13.  Normative References
§  Authors' Addresses




 TOC 

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,” .).



 TOC 

2.  Terminology

End User:
The person who wants to prove ownership of an Identifier to a Relying Party.
Identifier:
An Identifier is a URL or XRI. The OpenID Authentication protocol proves that an End User owns a URL or XRI.
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.
Relying Party:
A Web application that wants proof that the End User owns an Identifier.
IdP:
Identity Provider. 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.
User-Agent:
The End User's Web browser. See [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .).



 TOC 

3.  Overview

The OpenID Authentication protocol provides a way to prove that an End User owns an Identifier. In essence, the protocol allows a service to proxy its authentication decisions to another service specified by the End User. OpenID uses only standard HTTP requests and responses, so does not require any special capabilities of the User-Agent or other software.

The End User initiates the protocol by providing either a Claimed Identifier or an IdP Identifier. If an IdP Identifier is provided, the IdP MAY assist the End User in selecting an identifier. For example, the IdP might automatically generate a different Identifier for each different Relying Party so that the End User cannot be tracked across different sites.



 TOC 

3.1.  Protocol Flow

  1. The End User initiates authentication (Initiation) by supplying a Claimed Identifier or IdP Identifier to the Relying Party. The Relying Party performs discovery (Discovery) on the End User-provided identifier and establishes the location of the service that the End User uses for authentication.
  2. (optional) The Relying Party and IdP exchange information on how to cryptographically sign the request and responses. This information is referred to as an "association." OpenID associations (Establishing Associations) consist of a "handle," which is an identifier for the association, an "association type," and the data that is needed by that association type for signing and verifying signatures.
  3. The Relying Party sends the End User to the IdP with an OpenID authentication request (Requesting Authentication).
  4. The IdP establishes whether the End User is authorized to perform OpenID authentication and wishes to do so. Depending on the form of the request, the IdP may be able to interact with the End User in order to establish that they are authorized to approve OpenID authentication.
  5. The IdP sends the End User back to the Relying Party with a signed assertion if the authentication is approved (Positive Assertions) or an indication that OpenID authentication failed (Negative Assertions) if it was not approved.



 TOC 

4.  Initiation and Discovery

The OpenID Authentication protocol starts with an End User submitting an Identifier (Identifying the End User) to the Relying Party. The Relying Party examines the user input, normalizes it, and performs discovery based on the normalized identifier. After successful discovery, the Relying Party has sufficient information to submit an authentication request to an IdP (see Section 8 (Requesting Authentication)).



 TOC 

4.1.  Initiation

To initiate OpenID Authentication, the Relying Party SHOULD present the End User with a form that has a field for entering a Claimed Identifier or an IdP's Identifier. It is RECOMMENDED that every Relying Party places the OpenID logo at the beginning of the form field where the End User enters their Identifier. The form field's "name" attribute SHOULD have the value "openid_identifier" so that User-Agents can auto-complete the End User's Identifier.

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 "http://". To do so, the application SHOULD examine the first character of the input. If it is an XRI Global Context Symbol (Section 2.2.1.1 of XRI Syntax (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://".

URL identifiers MUST be further normalized by applying the rules in section 6 of RFC 3986, following redirects when retrieving their content, and finally applying the rules in section 6 of RFC 3986 (Normalization and Comparison) to the final destination URL.



 TOC 

4.2.  Discovery

Discovery consists of taking a Claimed Identifier or IdP Identifier and extracting the necessary information for initiating authentication. OpenID has three paths through which to do discovery. If the identifier is an XRI, XRI resolution will yield an XRDS document that contains the necessary information. If it is a URL, the Yadis protocol (Miller, J., “Yadis Specification 1.0,” .) [Yadis] is first attempted. If it succeeds, the result is again an XRDS document. If the Yadis protocol fails, the URL is retrieved and HTML-based discovery is attempted on the content located by the URL.



 TOC 

4.2.1.  Delegating Authentication

A "Delegate Identifier" is an alternate Identifier that can be included in the discovery response. When it is present, the Relying Party requests authentication using that identifier rather than the Claimed Identifier. Upon successful authentication, the Relying Party recognizes the End User using the Claimed Identifier. This mechanism is called Delegation.

Delegation allows the End User to use a URL or XRI as an Identifier without having to perform any configuration other than specifying what should be returned by discovery. This allows a broad range of URLs and XRIs to be used. Delegation allows an End User to keep the same Identifier over many years, even as services come and go; they'll just keep changing the IdP Endpoint URL and Delegate Identifier.



 TOC 

4.2.2.  Discovered Information

Upon successful completion of discovery, the Relying Party will have the following information:

IdP Endpoint URL:
The URL that accepts authentication requests. This MUST be an absolute URL.
Claimed Identifier:
(optional) The normalized Identifier upon which discovery was performed. The Claimed Identifier is present unless the End User enters an IdP's Identifier. The discovery process allows a Relying Party to differentiate the two kinds of identifiers by supplying different information in response to the discovery request.
Delegate Identifier:
(optional) The Identifier that should be sent in the authentication request to the IdP. The Delegate Identifier can only be present when the End User enters a Claimed Identifier.



 TOC 

4.2.3.  Using Yadis or XRI Resolution

If a URL is supplied, the Relying Party MUST attempt the Yadis protocol on that URL. The Yadis protocol and XRI resolution both yield an XRDS document. This is an XML document with entries for services that are related to the identifier.

Once the Relying Party has obtained an XRDS document, it MUST first check for an <xrd:Service> element describing an IdP Endpoint. If no IdP Endpoint is found, it MUST check for an <xrd:Service> element describing a Claimed Identifier.



 TOC 

4.2.3.1.  IdP Identifiers

If the entered Identifier is an IdP Identifier, the OpenID information is contained in a service element with the following information:



 TOC 

4.2.3.2.  Claimed Identifiers

If the entered Identifier is a Claimed Identifier, the remaining OpenID information is contained in a <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 IdP Endpoint URL
An <openid:Delegate> tag (optional) whose text content is The Delegate Identifier

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" for the value of <xrd:Type>.

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



 TOC 

4.2.3.2.1.  XRI and the CanonicalID Element

When the identifier is an XRI, the <xrd:XRD> element that contains the OpenID <xrd:Service> element will also contain a <CanonicalID> element. The content of this element MUST be preserved for use after a successful authentication request. See Section 9.3 (Identifying the End User).

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 <ProviderID> element that is a child of the <XRD> element. If the provider is not authoritative for the canonical ID, the Relying Party MUST resolve the canonical ID to confirm the OpenID Service Endpoint 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 discovery result.

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



 TOC 

4.2.4.  HTML-Based Discovery

In the interests of backward compatibility, the HTML-based discovery mechanism from OpenID 1.1 MUST be supported by Relying Parties. The host of the HTML document MAY be different from the End User's IdP's host.

To use HTML-based discovery, the following markup MUST be added to the HEAD section of the HTML document located at the identifier URL:

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

A <LINK> tag MAY be included with attributes "rel" set to "openid.delegate" and "href" set to the End User's Delegate Identifier

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 %xx mechanism as described in [RFC3986] (Berners-Lee, T., “Uniform Resource Identifiers (URI): Generic Syntax,” .).



 TOC 

5.  Data Formats

The OpenID Authentication protocol consists of messages passed between the Relying Party and the IdP. These messages consist of a mapping 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.



 TOC 

5.1.  Key-Value Form Encoding

Key-Value Form is an encoding of an OpenID message to a byte string. It is used for signature calculation and for direct responses to relying parties.

A Key-Value form message is a sequence of lines, each containing a pair of key and value. No key or value can contain a newline. No key can contain a colon. Each key-value pair is joined with a colon, and then a newline is appended. Every line MUST end with a newline, codepoint 10 ("\n"). Additional characters, including whitespace, MUST NOT be added before or after the colon or newline. The Key-Value form representation of a mapping is the concatenation of all of the lines generated from the pairs in the mapping. The message MUST be encoded in UTF-8 to produce a byte string.



 TOC 

5.2.  Encoding Messages to HTTP Servers

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 HTML 4.01 specification (W3C, “HTML 4.01 Specification,” .) [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 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.



 TOC 

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

openid.mode=error&openid.error=This%20is%20an%20example%20message


 TOC 

6.  Communication Types

Data is transferred between a Relying Party and IdP in two different ways. Either the Relying Party directly connects to the IdP, or the Relying Party or IdP sends data indirectly via the User-Agent. In no instance does the IdP directly connect to the Relying Party.



 TOC 

6.1.  Direct Communication

Direct communication between a Relying Party and IdP is accomplished using an HTTP POST (see [RFC2616] (Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” .)) initiated by a Relying Party to an IdP endpoint URL. Direct communication is used for establishing associations (Establishing Associations) and verifying authentication assertions (Verifying Directly with the Identity Provider).



 TOC 

6.1.1.  Direct Request

The message MUST be encoded as a POST body, as specified by Section 5.2 (Encoding Messages to HTTP Servers).



 TOC 

6.1.2.  Direct Response

The body of a response to a Direct Request (Direct Request) consists of a mapping of keys to values encoded in Key-Value Form, as specified by Section 5.1 (Key-Value Form Encoding). The content-type header of the response SHOULD be "text/plain".



 TOC 

6.1.2.1.  Successful Responses

The HTTP Status Code of a response to a valid request is 200. The contents of the resulting message depend on the mode of the request.



 TOC 

6.1.2.2.  Error Responses

If a request is malformed or contains invalid arguments, the HTTP Status Code of the response is 400. The message encoded in the response will have the following form:

The IdP MAY add additional keys to the response.

The particular wire format of these messages will depend on whether they are responses to direct or indirect queries.



 TOC 

6.2.  Indirect Communication

Indirect communication between Relying Party and IdP passes a message through the User-Agent. This can be initiated by either the Relying Party or the IdP. Indirect communication allows the messages to be associated with the End User. 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 5.2 (Encoding Messages to HTTP Servers). The initiator of the communication chooses which method of indirect communication is appropriate. Authentication requests (Requesting Authentication) and responses (Responding to Authentication Requests) both take the form of indirect communication.



 TOC 

6.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 message appended to the query string, as specified in Section 5.2 (Encoding Messages to HTTP Servers).

This method is deprecated as of OpenID version 2.0.



 TOC 

6.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 5.2 (Encoding Messages to HTTP Servers) when the form is submitted. The form MUST include a submit button.



 TOC 

6.2.3.  Indirect Error Responses

If a request is malformed or contains invalid arguments and there is an "openid.return_to" argument whose value is a valid URL, the IdP SHALL send the User Agent to that URL with a message of the following form:

The IdP MAY add additional keys to the response.

If the "openid.return_to" value is missing or not a valid URL, the IdP SHOULD return a response to the End User indicating the error and that it is unable to return the End User to the Relying Party.



 TOC 

7.  Establishing Associations

An "association" is a set of information that allows a Relying Party to check the cryptographic signature of a response from the IdP. An association is a relationship between a Relying Party and an IdP. If a Relying Party is incapable of creating or storing associations, OpenID provides a mechanism (Section 9.2.2 (Verifying Signatures)) for authentication to complete securely by using a back-channel between the Relying Party and the IdP to verify the signature on the response without of using an association. When a Relying Party is operating without creating associations, it is said to be in "stateless mode."

It is RECOMMENDED that a Relying Party form associations if it is possible for it to do so. After the initial request, using an association saves one HTTP request per authentication, which saves network resources and improves performance.

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



 TOC 

7.1.  Generating Signatures

Successful authentication messages from the Identity Provider to the Relying Party MUST be cryptographically signed.

Signing a message is a two-phase process. The first phase is converting the response into an octet string to sign. The second phase is generating a signature for that octet string. The precise algorithm used for each phase depends on the type of association being used.

There are two algorithms for each phase that an IdP SHOULD support. The two algorithms for converting the response to an octet string are an algorithm with a list of signed parameters, and an algorithm that signs all parameters. The two algorithms for signing the generated octet string are HMAC-SHA1 and HMAC-SHA256. Other algorithms for either phase may be defined by extensions and used by Relying Parties and IdPs which support them.



 TOC 

7.1.1.  Signed List Algorithm

When using this algorithm to create an octet string, the signed information is a subset of the mapping of keys to values as specified in Section 5 (Data Formats). A signed message contains of a list of signed fields, an association handle, and a signature. The algorithm for generating the signature depends on the type of association.

To compute the signature from an association, an ordered list of signed fields and a set of query parameters:

  1. Iterate over the list of signed fields in order, taking the field name as the key. For each key, find the value in the query parameters whose key is equal to the field name prefixed with "openid.".
  2. Generate a Key-Value Form string (Key-Value Form Encoding) built from the (field name, value) pairs in the order that they appear in the sequence of key-value pairs. (This results in the "openid." prefix being stripped off the the keys from the original message.)
  3. Generate the signature by evaluating the keyed message digest function specified by the association on the resulting Key-Value Form string.



 TOC 

7.1.2.  Sign-All Algorithm

When using this algorithm to create an octet string, the signed information is the mapping of keys to values as specified in Section 5 (Data Formats). A signed message contains an association handle and a signature. The algorithm for generating the signature depends on the type of association.

To compute the signature from an association and a set of query parameters:

  1. Generate a Key-Value Form string (Key-Value Form Encoding) built from all the (key, value) pairs in the message sorted in byte order. (Unlike the Signed List Algorithm, this doesn't result in the "openid." prefixes being stripped off the keys in this format.)
  2. Generate the signature by evaluating the keyed message digest function specified by the association on the resulting Key-Value Form string.



 TOC 

7.2.  Association Handles

Associations are referred to by a handle, which MUST be a string 255 characters or less, and consist only of ASCII characters in the range 33-126 inclusive (printable non-whitespace characters). The handle is used to look up stored associations. A Relying Party SHOULD re-use the association for a server until it expires or is instructed to stop using it by the IdP.



 TOC 

7.3.  Association Types

An association type indicates the algorithm for computing the signature of messages created with that association. OpenID associations use keyed message digest functions. The key for the message digest function is known as a Message Authentication Code (MAC) key.



 TOC 

7.3.1.  HMAC-SHA1 Associations

An association of type HMAC-SHA1 ([RFC2104] (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” .), [RFC3174] (Eastlake, D. and P. Jones, “US Secure Hash Algorithm 1 (SHA1),” .)) uses the following algorithm to compute a signature of the message:

  HMAC-SHA1(MAC key, Key-Value Form message)

HMAC-SHA1 associations have the association type "HMAC-SHA1". The size of the MAC key for HMAC-SHA1 associations is 160 bits. These associations use the signed list method to generate the octet string to sign.



 TOC 

7.3.2.  HMAC-SHA1-SIGNALL Associations

An association of type HMAC-SHA1-SIGNALL ([RFC2104] (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” .), [RFC3174] (Eastlake, D. and P. Jones, “US Secure Hash Algorithm 1 (SHA1),” .)) uses the following algorithm to compute a signature of the message:

  HMAC-SHA1(MAC key, Key-Value Form message)

HMAC-SHA1 sign-all associations have the association type "HMAC-SHA1-SIGNALL". The size of the MAC key for HMAC-SHA1 associations is 160 bits. These associations use the sign-all method to generate the octet string to sign.



 TOC 

7.3.3.  HMAC-SHA256-SIGNALL Associations

An association of type HMAC-SHA256 ([RFC2104] (Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” .), [FIPS180‑2] (U.S. Department of Commerce and National Institute of Standards and Technology, “Secure Hash Signature Standard,” .)) uses the following algorithm to compute a signature of the message:

  HMAC-SHA256(MAC key, Key-Value Form message)

HMAC-SHA256 associations have the association type "HMAC-SHA256-SIGNALL". The size of the MAC key for HMAC-SHA1 associations is 256 bits. These associations use the sign-all method to generate the octet string to sign.



 TOC 

7.4.  Association Sessions

An association session consists of an association request from a Relying Party to the IdP Endpoint URL. An association session is a direct request as specified in Section 6.1 (Direct Communication) with "openid.mode" set to "associate". There are several association session types defined. All association session types have a common parameter, "openid.assoc_type" that indicates the type of the established association.

If the IdP supports the association session type and association type requested by the Relying Party, an association session is successful. If an IdP does not or chooses not to support the requested association or association session type, the association request is unsuccessful.



 TOC 

7.4.1.  Request Parameters

These parameters are common to all association requests.



 TOC 

7.4.2.  Successful Response Parameters

The format of responses to associate requests is Key-Value pairs (Key-Value Form Encoding). All association session responses share the following fields:



 TOC 

7.4.3.  Unencrypted Association Sessions

If the IdP's Endpoint URL is an HTTPS URL, a "no-encryption" association session may be used. "no-encryption" association sessions also allow for Relying Parties or IdPs to be run in environments where there is no support for arbitrary precision arithmetic. In all other cases, "no-encryption" association sessions SHOULD NOT be used.

An IdP MAY respond to an association request with a "no-encryption" association session response regardless of the type of association session requested. For better security, a Relying Party MAY choose not to use the resulting association on subsequent authentication requests.



 TOC 

7.4.3.1.  Request Parameters

There are no extra parameters defined for a no-encryption association session request. To request a no-encryption association, leave blank the "openid.session_type" query parameter on the request.



 TOC 

7.4.3.2.  Response Parameters

The response to a no-encryption association session has the following extra fields:



 TOC 

7.4.4.  Diffie-Hellman Association Sessions

OpenID supports two different kinds of associations based on Diffie-Hellman key exchange, "DH-SHA1" and "DH-SHA256". 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.

If the IdP does not support Diffie-Hellman, it MUST ignore the Diffie-Hellman fields in the request and reply with a no-encryption association session response. Relying Parties MAY choose to use "stateless mode" in this case.

The Relying Party specifies a modulus, p, and a generator, g. The Relying Party chooses a random private key xa and Identity 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,” .).



 TOC 

7.4.4.1.  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, 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"


 TOC 

7.4.4.2.  Request Parameters



 TOC 

7.4.4.3.  Response Parameters

dh_server_public

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

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

enc_mac_key

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

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



 TOC 

7.4.5.  Unsuccessful Response Parameters

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

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.



 TOC 

8.  Requesting Authentication

Once the Relying Party has successfully performed discovery and optionally created an association with the discovered IdP Endpoint URL, it can send the End User to the IdP to obtain an assertion, using one of the mechanisms in Section 6.2 (Indirect Communication).



 TOC 

8.1.  Request Parameters



 TOC 

8.2.  Trust Roots

A "trust root" is a pattern that represents the part of URL-space for which an OpenID authentication request is valid. A trust root SHOULD give the End User an indication of the scope of the authentication request. IdPs SHOULD present the trust root when requesting the End User's approval for an authentication request. IdPs MAY use the trust root to allow the End User to automate approval of authentication requests.

A trust root pattern is a URL, with the following changes:

The "openid.return_to" URL MUST match the "openid.trust_root", or the IdP MUST return an error. A URL matches a trust root if:

It is RECOMMENDED that IdP's protect their End Users from requests with overly-general trust roots, like http://*.com/ or http://*.co.uk/. Whether a trust root is overly-general is at the discretion of the IdP.



 TOC 

8.3.  Immediate Requests

When requesting authentication, the Relying Party MAY request that the IdP not interact with the End User, and instead respond immediately with either an assertion that they can and wants to proceed 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".



 TOC 

9.  Responding to Authentication Requests

An authentication request comes from the User-Agent. The IdP SHOULD identify the User-Agent, through some method of authentication or by browser session state, such as cookies. How the End User authenticates to the IdP is outside of the scope of OpenID Authentication. Once the End User has been identified, the IdP should determine if the End User wishes for this authentication request to complete. This determination is also out of the scope of OpenID Authentication. If the End User wishes for it to complete, the End User has approved authentication, and a positive assertion SHOULD be issued.

Once the End User is known to the IdP, the IdP decides whether to issue an assertion as specified in Section 9.1 (Positive Assertions). If no Identifier was specified and there are Identifiers that are in the control of the End User, the IdP SHOULD allow the End User to choose an identifier to assert control over to the Relying Party. If an Identifier was specified, the IdP SHOULD only issue assertions about the specified Identifier.

In order to make an assertion, the IdP needs to have an association for the response. If the Relying Party supplied an association handle, the association information SHOULD be looked up based on that handle. If the association is expired or missing, the IdP SHOULD indicate to the Relying Party that the association was invalid by setting the value of "openid.invalidate_handle" to the Relying Party-specified handle. If an invalid association was sent, aside from including the "openid.invalidate_handle" parameter in the response, the IdP should treat the request the same as a request without an association handle specified.

If no association handle is specified, the request is a "stateless mode" request. The IdP will create a private association for signing the response, and will respond to later requests to check the signature of that response.



 TOC 

9.1.  Positive Assertions

If the End User approves the authentication, the Identity Provider sends a response back through the User-Agent with the following information as specified in Section 6.2 (Indirect Communication):



 TOC 

9.2.  Verifying Assertions

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



 TOC 

9.2.1.  Verifying Discovered Information

Either the Identifier in the assertion points to the OpenID IdP making the assertion, or the assertion is being made using delegation (Delegating Authentication) and the Identifier with the delegate information points to that IdP, and specifies the identifier in the assertion as a delegate. Specifically, the Relying Party MUST have performed discovery (Discovery) on the Identifier that will be used and the information in the assertion MUST match the discovered information. When 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 IdP is authorized to make assertions about the identifier.

To prevent replay attacks, the Relying Party SHOULD keep track of the nonce values included in positive assertions and never accept the same value more than once for the same association. The Relying Party MAY use the time-stamp to reject responses that are outside of a range it has chosen as accpetable, limiting the amount of time that nonces must be stored to prevent replays.



 TOC 

9.2.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 no association is found, it MUST request that the IdP verify the signature.



 TOC 

9.2.2.1.  Verifying with an Association

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



 TOC 

9.2.2.2.  Verifying Directly with the Identity Provider

If the association handle is not recognized, the Relying Party MUST attempt to contact the IdP to verify the signature. The Relying Party generates a POST to the IdP Endpoint URL with the signed values from the assertion and the association information. The response to that request indicates whether the signature is correct.

When the IdP is verifying the signature, the "openid.mode" value MUST be changed to "id_res".

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

The IdP SHOULD only return is_valid once for each authentication request. An authentication request may be identified by its "openid.nonce" value.

Implementation Note for Stateless Relying Parties: The Relying Party must verify the signature at the same IdP Endpoint from which it was issued. In the event that there are multiple endpoints defined for a Claimed Identifier, this requires the Relying Party to remember the endpoint with whom they are conversing. The Relying Party MAY choose to encode this information in a parameter on the return_to URL it provides in the id_res request. That encoded data MUST be signed to prevent tampering from malicious agents.



 TOC 

9.2.2.2.1.  Request Parameters



 TOC 

9.2.2.2.2.  Response Parameters

Response format: Key-Value Pairs



 TOC 

9.3.  Identifying the End User

A successful authentication response provides the Relying Party with a Verified Identifier, which MAY be used as a user-visible identifier. Identifiers in OpenID MUST be URLs or XRIs. If the identifier is a URL, its scheme MUST be "http" or "https". Except in the case that the Verified Identifier is an XRI, the Relying Party SHOULD use the Verified Identifier as a key for local storage of information about the End User. If the Verified Identifier is an XRI, the discovered CanonicalID field from the XRD SHOULD be used as a key for local storage of information about the End User.

If a request is using delegation, the Verified Identifier is the Identifier on which discovery was performed, and not the identifier that is contained in the assertion. If an assertion is made for an Identifier on which discovery has not been performed, the Relying Party MUST perform discovery on that Identifier and compare the discovered information to that in the assertion.



 TOC 

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



 TOC 

9.4.  Negative Assertions

The IdP sends a response back through the User-Agent if it is unable to identify the End User or the End User does not or cannot approve the request.



 TOC 

9.4.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 IdP to provide identifying credentials or approval of a request. A negative assertion of an immediate request takes the following form:



 TOC 

9.4.2.  In Response to Non-Immediate Requests

Since the IdP 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:

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.



 TOC 

10.  Extensions

An Extension to OpenID is a protocol that rides on top of the OpenID authentication request and response. Extensions are useful for providing extra information about an authentication request or response or providing extra information about the subject of the authentication response.

OpenID extensions are identified by a URI. The 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. It 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.



 TOC 

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

The Relying Party's XRDS document's <xrd:Service> entry should have the return_to URL as the content of the <xrd:URI> tag and should have http://openid.net/return_to/2.0 as the content of the <xrd:Type> tag.

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>


 TOC 

12.  Security Considerations



 TOC 

12.1.  Preventing Attacks



 TOC 

12.1.1.  Eavesdropping Attacks

There are two places in this specification 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 IdP 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 instead of "no-encryption" to protect from eavesdropping. If the nonce is checked in message verification, the positive authentication assertion cannot be re-used.



 TOC 

12.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, there is no tractable attack 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 IdP 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 IdP, and so does not have to impersonate the IdP.

SSL with certificates signed by a trusted authority prevents these kinds of attacks by verifying the results of the DNS lookup 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 user through the browser.



 TOC 

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

Cross-site-scripting attacks against IdPs may be used to the same effect. For the best security, IdPs should not depend on scripting so that User Agents without scripting enabled can make authentication decisions.



 TOC 

12.3.  User Interface Considerations

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



 TOC 

Appendix A.  Examples

Non-normative



 TOC 

Appendix A.1.  Delegation

For example, an End User wants to use http://www.example.com/ as their Identifier, but http://www.example.com/ doesn't have the means, or desire, to run an IdP. LiveJournal is an Identity Provider, so if the End User has a LiveJournal OpenID Identifier, they can delegate their authentication to LiveJournal.



 TOC 

Appendix A.2.  XRDS

To use www.example.com as their Identifier, but have Relying Parties actually verify http://exampleuser.livejournal.com/ with the Identity Provider located at http://www.livejournal.com/openid/server.bml, the following XML snippet should be present in the final XRD in the XRDS file:

<Service xmlns="xri://$xrd*($v*2.0)">
  <Type>http://openid.net/signon/2.0</Type>
  <URI>http://www.livejournal.com/openid/server.bml</URI>
  <Delegate xmlns="http://openid.net/signon/2.0">
    http://exampleuser.livejournal.com/
  </Delegate>
</Service>


 TOC 

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 Identity 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/"/>


 TOC 

Appendix A.4.  Login Form

Continuing this example, 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 Identifier or their IdP's identifier.

For Example:

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


 TOC 

Appendix A.5.  XRI CanonicalID

For example, if =example and =exmpl both yield an XRD document with the CanonicalID xri://(example)!1234 then those identifiers should be treated as equivalent. For applications with user accounts, those identifiers should both be attached to the same account.



 TOC 

Appendix B.  Diffie-Hellman Default Value

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

DCF93A0B883972EC0E19989AC5A2CE310E1D37717E8D9571BB7623731866E61E
F75A2E27898B057F9891C2E27A639C3F29B60814581CD3B2CA3986D268370557
7D45C2E7E52DC81C7A171876E5CEA74B1448BFDFAF18828EFD2519F14E45E382
6634AF1949E5B535CC829A483B8A76223E5D490A257F05BDFF16F2FB22C583AB


 TOC 

Appendix C.  Changes from the Previous OpenID Specification

This specification is based on the original specification for OpenID 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 most significant changes to the specification are outlined in this section.



 TOC 

Appendix C.1.  Updated Initiation and Discovery



 TOC 

Appendix C.2.  Security improvements

A nonce is now part of the protocol for built-in protection against replay attacks.

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



 TOC 

Appendix C.3.  Extensions

Extensions are a new mechanism to support data exchange and other Relying Party-IdP 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 the response.



 TOC 

13. Normative References

[FIPS180-2] U.S. Department of Commerce and National Institute of Standards and Technology, “Secure Hash Signature Standard,” FIPS 180-2.

Defines Secure Hash Algorithm 256 (SHA256)

[HTML401] W3C, “HTML 4.01 Specification.”
[RFC1750] Eastlake, D., Crocker, S., and J. Schiller, “Randomness Recommendations for Security,” RFC 3986.
[RFC2104] Krawczyk, H., Bellare, M., and R. Canetti, “HMAC: Keyed-Hashing for Message Authentication,” RFC 2104.
[RFC2119] Bradner, B., “Key words for use in RFCs to Indicate Requirement Levels,” RFC 2119.
[RFC2616] Fielding, R., Gettys, J., Mogul, J., Frystyk, H., Masinter, L., Leach, P., and T. Berners-Lee, “Hypertext Transfer Protocol -- HTTP/1.1,” RFC 2616.
[RFC2631] Rescorla, E., “Diffie-Hellman Key Agreement Method,” RFC 2631.
[RFC3174] Eastlake, D. and P. Jones, “US Secure Hash Algorithm 1 (SHA1),” RFC 3174.
[RFC3339] Newman, C. and G. Klyne, “Date and Time on the Internet: Timestamps,” RFC 3174.
[RFC3548] Josefsson, S., “The Base16, Base32, and Base64 Data Encodings,” RFC 3548.
[RFC3986] Berners-Lee, T., “Uniform Resource Identifiers (URI): Generic Syntax,” RFC 3986.
[XRI Syntax 2.0] Reed, D. and D. McAlpin, “Extensible Resource Identifier (XRI) Syntax V2.0” (HTML, PDF).
[Yadis] Miller, J., “Yadis Specification 1.0.”


 TOC 

Authors' Addresses

  David Recordon
  VeriSign, Inc.
  487 E Middlefield Road
  Mountain View, CA 94109
  USA
Email:  drecordon@verisign.com
  
  Josh Hoyt
  JanRain, Inc.
  5331 SW Macadam Avenue
  Suite #375
  Portland, OR 97239
  USA
Email:  josh@janrain.com
  
  Dick Hardt
  Sxip Identity Corporation
  798 Beatty Street
  Vancouver, BC V6B 2M1
  Canada
Email:  dick@sxip.com
  
  Brad Fitzpatrick
  Six Apart, Ltd.
  548 4th Street
  San Francisco, CA 94107
  USA
Email:  brad@danga.com