From Yadis

The key words and word pairs, "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL", in this document are to be interpreted as described in RFC 2119.

Back to Conventions.

6. The Yadis Protocol

This is Clause 6 of Yadis Specification Version 0.8

6.1 Overview of the Yadis Protocol

The purpose of the Yadis protocol is to enable a Relying Party, which has been proffered a Yadis ID, to obtain a Yadis Resource Descriptor that describes the services available using that Yadis ID.

6.1.1 Obtaining the Yadis Resource Descriptor

When a User provides a Yadis ID to a Relying Party, that Relying Party will want to discover which services are available using that Yadis ID. (Is it a LID or OpenID URL? What authentication methods are available?)

To do that, the Relying Party makes an HTTP request. This request may take any one of several forms, discussed later in this document.

In response to the request, the Relying Party obtains either:

1. A Yadis Resource Descriptor.

2. A URL that locates a Yadis Resource Descriptor.

3. Some other response; in this case the identifier is not a Yadis ID or there has been a failure.

If the response is 2, the Relying Party uses that URL to obtain the Yadis Resource Descriptor.

The Resource Descriptor lists the services available using that Yadis ID, including services that can authenticate the User.

For a description of the Yadis Resource Descriptor, see Yadis Resource Descriptor.

Whenever 'HTTP' is specified in this document, a request must use either the HTTP protocol or the HTTPS protocol, according to the scheme name in the URL being used.

6.1.2 Authentication

Yadis delegates authentication to the Identity Services.

The Relying Party uses the information in the Yadis Resource Descriptor to choose an Identity Service suitable to its purposes, and uses that Service to authenticate the user.

6.1.3 Other services

Identity Services offer other services, in addition to authentication. These services are identified in the Yadis Resource Descriptor and each Service operates according to the specification of the particular Identity Service providing that Service.

Example: LID defines a RESTful protocol that allows the structured query of profile information independent of the schema in which that information is expressed.

6.2 Protocol Specification

6.2.1 Yadis ID

A Yadis ID MUST be a URL (or a URI or XRI resolvable to a URL). The scheme name of that URL must be HTTP or HTTPS. In the remainder of this Section 5.2, that URL is called the ‘Yadis URL.’

6.2.2 Alternatives

A Relying Party MAY use the Yadis URL to make an HTTP GET request. This request MAY return an HTML document. If it does, either that document itself or the HTTP response-headers will contain a URL giving the location of the Yadis Resource Descriptor. The Relying Party then obtains the Yadis Service Descriptor using that URL.

The Yadis Protocol also includes two alternatives:

The Relying Party MAY first issue an HTTP HEAD request. In that case, the URL MAY be returned in an HTTP response-header.

The Relying Party MAY include in the HTTP GET request an Accept request-header asking for the Yadis Resource Descriptor to be returned. In that case the Yadis Resource Descriptor MAY be returned in response to that request, instead of an HTML document.

Note: If the resource located by a Yadis ID will be returning a Yadis Resource Descriptor document in response to an Accept request-header, all responses to a request using the Yadis URL need to include a Vary: Accept response-header to indicate to intervening caches that differing values of the Accept header may return different responses. This header needs to be present even in the case where the HTML page is returned (instead of a Yadis Resource Descriptor document).

The following sections specify the steps of the Yadis Protocol.

[I will later provide an illustration for each of the alternatives in the form of UML sequence diagrams. –jm]

6.2.3 Initiation

The Yadis Protocol is initiated by the Relying Party with an initial HTTP (or HTTPS) request using the Yadis URL.

This request MUST be either a GET or a HEAD request.

A GET request MAY include an HTTP Accept request-header [HTTP 14.1] specifying MIME type, application/xrds+xml.

6.2.4 Response

The response to the initial request MUST comply with the HTTP (or HTTPS) protocol.

The response MUST be one of:

1. An HTML document with a element which includes a element with http-equiv attribute, X-Yadis-Location

2. An HTML document with HTTP response-headers which include an X-Yadis-Location response-header

3. HTTP response-headers only, which MAY include an X-Yadis-Location response-header

4. A document of MIME type, application/xrds+xml

Note: Since the response to the initial request MUST comply with the HTTP (or HTTPS) protocol, if the request is a GET and does not include an "Accept: application/xrds+xml" header, the response MUST be of type 1 or 2. This is required because the Relying Party MAY omit the Accept and so might only look for the X-Yadis-Location.

6.2.5 Document

If the response is a document of MIME type, application/xrds+xml, that document MUST be a Yadis Resource Descriptor (see Clause 7).

6.2.6 URL

If the response includes an X-Yadis-Location response header or an HTML element whose http-equiv attribute is X-Yadis-Location the value MUST be an absolute URL. That URL is a Yadis Resource Descriptor locator; it MUST locate a Yadis Resource Descriptor.

The Relying Party MUST issue an HTTP GET to retrieve that Yadis Resource Descriptor document.

6.2.7 Second Request

Unless a Relying Party using an HTTP Accept request-header obtains the Yadis Resource Descriptor in response to that request, that Relying Party MUST examine the response to determine if it contains a Yadis Resource Descriptor Locator in either the HTTP response-headers or the HTML element and request the document as specified in Section 6.2.6.

Unless a Relying Party using an HTTP HEAD request obtains a Yadis Resource Descriptor Locator in response to that request, that Relying Party MUST then issue an HTTP GET request and examine the response to determine if it contains a Yadis Resource Descriptor Locator in either the HTTP response-headers or the HTML element and request the document as specified in Section 6.2.6.

6.2.8 Termination

When a Yadis Resource Descriptor is returned to the Relying Party the Yadis Protocol terminates.

If none of the requests succeed in obtaining a Yadis Resource Descriptor then the URL used in the initial request is not a Yadis URL or there has been a failure.

On to Yadis Resource Descriptor