Protocol-d001

From Yadis

5.1 Capability Discovery Protocol

The user has enters a Yadis URL (http://myid.idhost.com/, for the sake of example) into the “My URL” text field at a website (known as an Identity Consumer). The Identity Consumer must then use the capability discovery protocol to discover what operations the given URL supports, including which sign-on protocols are available.

The first step is to retrieve the identity URL. In the request, the consumer must include an HTTP "Accept" header field which includes the MIME type application/x-meta-identity with the highest precedence. See section 14.1 of the HTTP/1.1 specification (RFC 2616) for information about this header field. It is recommended that consumers use a full HTTP library to make this request, but the following HTTP request is provided as an example:

GET / HTTP/1.1
Host: myid.idhost.com
Accept: application/x-meta-identity, text/html;q=0.5

This produces exactly one of the following responses:

1. A document of MIME type "application/x-meta-identity". This conveys to the identity consumer what capabilities the Yadis URL supports.
2. An HTML document (MIME type text/html) that contains a LINK element like the following in its HTML HEAD section. This occurs in case the Yadis URL refers to a regular HTML web page that is using HTML indirection. Note that the given URL MUST be an absolute URL; relative URLs are not permitted.

3. Any other response. This indicates that the entered URL is not a Yadis identity URL; the consumer should display some kind of error message and give up.

If the response is an HTML document and the linked URL is properly formed, the consumer repeats this process for the new URL. However, the response MUST NOT be an HTML document; only one level of HTML indirection is permitted for efficiency reasons. Consumers are permitted to check the "type" attribute in the HTML LINK and ensure that it is correct before making the request, but this is not required.

The document of MIME type "application/x-meta-identity" lists the capabilities of the Yadis URL; the Identity Consumer can use this information to initiate an authentication according to the identity protocol it chooses from the obtained capabilities. If no appropriate capabilities are declared, the consumer must display some kind of error message and give up.

All consumers must be prepared to follow a resonable number of standard HTTP redirect responses (response codes starting with 3) when making HTTP requests, but are recommended to limit both the maximum time taken to retrieve the document( to avoid 'tarpitting') and the number of redirects permitted (to avoid redirect loops).

A description of the format of the capability declaration document is given in the following chapter.

Note: The server hosting the identity URL is not required to have a full implementation of the HTTP Accept header. It is permitted for the mere presence of the capability document MIME type to trigger a Yadis protocol document response. This compromise is provided for simplicity of implementation. (Editor's note: should maybe be a little more specific about the extent to which the server is allowed to simplify the parsing of this header; naive handling may cause interoperability issues. --jm)