Yesterday, I posted about my planned work on writing a PHP5 OpenID library. As I mentioned towards the end, I would be blogging about specific topics required for such a library. This first entry is an examination of Yadis, a Specification which is relied upon by OpenID. Of course Yadis is a topic of its own, since it is also used by Light-Weight Identity (LID), sxip Identity, and mIDm. You can bet more will join in once Yadis becomes more firmly established.

This post is mainly to introduce Yadis, and what my upcoming effort towards a Zend_Service_Yadis would entail performing. Part 2, later, will briefly examine the format of a Yadis XRD document and how it should follow the Yadis Specification 1.0.

So what is Yadis?

The purpose of Yadis is to specify a standard for enabling any party (“the Relying Party”) to obtain an XML document containing relevant details of a specific Service (“the Yadis Resource Descriptor”) which describes Service details such as Type, Url, and other optional data to be included in Service requests. If that’s mumbo jumbo, it’s easily explained with an example.

Let’s take OpenID. In OpenID, the Yadis ID is simply your OpenID URL. If you have a Livejournal Blog, for example, you can use your blog URL as an Identity for other websites which support OpenID authentication. These will fire off a request to your Identity Provider to check you out. The problem is that the website doesn’t know where to send the request – it needs to discover your Provider’s authentication service, a process called “Service Discovery”. Service Discovery is what Yadis is all about since it defines a standard HTTP GET process, and a standard Service data format (XML XRDS syntax) anyone can use.

Service Discovery

The Yadis Specification 1.0 describes all the steps a Relying Party needs to perform in order to obtain a description of the services associated with an ID. In our example, an OpenID URL will be associated with an OpenID Server URL which can be used by any website to authenticate a user.. Service Discovery describes the steps in finding out where that OpenID Server is located, i.e. its URL. In case you’re wondering, an OpenID URL could be subdomain on your OpenID Provider’s website, or even your own personal website URL – this is very different from the Service URL.

Performing discovery relies on finding a Yadis Resource Descriptor which details the Services associated with any Yadis ID. This document will be XML, using the Extensible Resource Descriptor (XRD) format (an OASIS specification). It’s a bit tricky to find the end YRD XRDS document, so bear with me as I describe the process.

The first step is to make a simple HTTP GET request to the ID (if a URL). For example, our OpenID URL. The response now needs to be examined. There are broadly three types of valid responses detailed in the specification:

1. An HTML document with a “head” element that includes a “meta” element with a http-equiv
attribute of “X-XRDS-Location”. The “content” attribute of this element should contain a URL pointing to the Yadis ID’s associated Yadis XRD Document. For example:
[geshi lang=xml][/geshi]

2. Any document, so long as the response-headers contain an “X-XRDS-Location” response-header whose value should contain a URL pointing to the Yadis ID’s associated Yadis XRD Document.

3. A document of MIME media type, “application/xrds+xml”. We’ll hit gold when we receive this one! It means we just received the XRD document we were looking for. The MIME type will typically be contained in the “Content-Type” response-header.

The Bread Crumb Trail

In the above, two of the valid responses to an initial HTTP GET request to a Yadis ID (the OpenID URL in our example) don’t provide the needed Yadis XRD document, but provide a means of figuring out its actual location. Typically Service Discovery under Yadis will require at least two HTTP GET requests – the first to find the XRD location, the second to actually fetch it.

The first valid response is often used when an OpenID URL is an alias. You can actually create any number of aliases (and hence any number of aliasing OpenID URLs) based on a personal URL using this method since the aliases can simply inform a website (via either a response-header or “meta” element) where to look for the underlying Service Provider’s XRD document. Of course the underlying XRD is specific to only one account – that URL or ID which your aliases are each aliasing. Last time I mention “alias” in case I get dizzy…;).

In short, the Yadis Specification ensures any Relying Party can follow the valid responses from one to another until they finally receive the required Yadis document. Of course, if someone throws a spanner in the works you should ensure an application doesn’t follow a circular trail until PHP bumps its max execution limit. The Yadis Specification is a bit vague, but in general if you make more than 4 HTTP requests then I’d suggest the Yadis process should be considered to have failed.

Part 2 continues by examining the Yadis XRD Document format…

Related posts:

  1. OpenID library for the Zend Framework?
  2. OpenID support for PHP openssl extension? Yes, please.