Enabling your application for return URL verification

Published on and tagged with cakephp  openid

If you ever used an OpenID from Yahoo!, you probably noticed the following warning shown by Yahoo!:

“Warning: Yahoo! cannot verify this website. We recommend you do not share any personal information with this website.”

The reason you get such a warning is that Yahoo! makes use of an optional, but recommended, OpenID 2.0 feature called “Return URL Verification”, and the OpenID relying party (i.e. the application you want to log in) doesn’t provide the necessary data for this feature.

So, to avoid that the users of your application will get this warning when they log in with their OpenIDs, you have to provide a document with the return URLs, and you have to say where this document is located.

Ok, let’s start with the document. It is a Yadis (i.e. XML) document where you have to list all return URLs as services. Return URLs are URLs to which the OpenID provider redirects the user after the authentication process.

If we use an XML layout:

<?php 
echo '<?xml version="1.0" encoding="UTF-8"?>';
echo $content_for_layout; 
?>

then the Yadis document looks like:

<xrds:XRDS
    xmlns:xrds="xri://$xrds"
    xmlns:openid="http://openid.net/xmlns/1.0"
    xmlns="xri://$xrd*($v*2.0)">
    <XRD>
        <Service priority="0">
            <Type>http://specs.openid.net/auth/2.0/return_to</Type>
            <URI>http://example.com/users/login</URI>
        </Service>
    </XRD>
</xrds:XRDS>

In the corresponding action we have to set the layout and the correct content type:

public function yadis() {
    $this->layout = 'xml';
    header('Content-type: application/xrds+xml');
}

We have now a document describing the return URLs, but it’s of no use if the OpenID provider is not able to find this document.

So we have to provide an X-XRDS-Location header with the URL of the Yadis document. This header must be set at the URL we use as trust root (it is usually the root of the application). In our example we have to set the header in the action we use for rendering the homepage for example.com:

public function index() {
    header('X-XRDS-Location: http://example.com/openid/yadis');
    ...
}

The last step is to test whether the return URL verification works. For this purpose we have to log in with a Yahoo! OpenID. The warning I showed at the beginning of this article should now disappear.

That’s it. I hope it was understandable ;-)

11 comments baked

  • Brendon Kozlowski

    Dan, I’ve been reading about how everyone and their uncle (well, in the developers’ circle of family) has been using and implementing OpenID, and to a lesser degree (though I’d expect it to gain more ground as OpenID did) OpenAuth. Since it seems you’ve been working with it quite a bit…

    1.) What is (and is the diiference between OpenID and) OpenAuth exactly, in layman’s terms?

    2.) Do you know of any references (sites, articles or otherwise) that discuss how to implement OpenID from start to finish (simple is fine)? I’ve only ever seen bits and pieces of code examples, but never a full implementation example.

  • cakebaker

    @Brendon: Thanks for your questions!

    1.) OAuth allows you to authorize a website to access your data from an other website. For example, if you want to have prints of your private photos on Flickr, you could authorize a print service to access those photos, without giving the print service your Flickr credentials.

    So the difference to OpenID is, that OAuth is about authorization (“what can he do?”), whereas OpenID is about authentication (“who is it?”).

    Hope that is clear enough ;-)

    2.) For the consumer part you may try http://www.plaxo.com/api/openid_recipe, for the provider part I am not aware of such an article. You also may have a look at the examples which come with the JanRain OpenID library.

  • Brendon Kozlowski

    Dan, thank you *very, very* much!

  • AddressBoy

    very useful, thanks!

  • George E.

    Hey. Great article… except I can’t get it to work. My site is at http://openid.quickmediasolutions.com and it still gives that warning when I sign on with yahoo. The yadis document is at http://openid.quickmediasolutions.com/yadis.php and when I check the server logs, yahoo is indeed finding it and requesting it. But I still get the warning. Any ideas?

  • cakebaker

    @George: It seems like you could fix it in the meantime, at least I don’t get a warning when I log into your app with Yahoo.

  • George E.

    I finally fixed it. I think there was a problem with the XML markup in the Yadis file. Now if only SReg would work with Yahoo…

  • cakebaker

    @George: As far as I know they don’t support SReg and you have to use Attribute Exchange to retrieve the respective data.

  • min chulki

    as i see above, George E. put the document at the root of the application. so i can guess that Yahoo looks up the root, doesnt they?
    could you let me know where exactely i should put the “Yadis Document” ??

  • cakebaker

    @min chulki: You can place the Yadis document anywhere you like as long as it’s publicly accessible. You just have to ensure that the X-XRDS-Location header points to your chosen location.

    I hope this answers your question.

  • Cuong

    Hi,

    By saying this “The warning I showed at the beginning of this article should now disappear”

    Do you mean just the warning message disappears or the whole popup where you need to click ‘Agree’

    I am trying to bypass this window instead of clicking Agree everytime.

    Thanks

Bake a comment




(for code please use <code>...</code> [no escaping necessary])

© daniel hofstetter. Licensed under a Creative Commons License