How to implement a web widget with OAuth 2.0

Question

I want to create a web widget that will display information from my site.

The widget will be included in the client's website HTML using JavaScript, and should only be usable for my clients -- web sites that were registered at my site.

The information in the widget should be specific to the user who is currently visiting the client's site.

So, I need to authenticate both the client (website owner) and the resource owner (website visitor). This seems to map nicely to OAuth 2.0, but I couldn't find a complete example or explanation for such an implementation.

Any resources or pointers to such information will be appreciated.

Update: I've stumbled upon this article, which provides an outline for an approach that uses OAuth. However, it is not detailed enough for me to really understand how to use this with OAuth 2.

Answer 1

There are many large organizations that have done this, and I'm sad to see no other answers for this question since it's such an important web pattern.

I'm going to presume that you are not rolling your own OAuth 2.0 provider from scratch, if you are - well done otherwise you should be using something kickass like Doorkeeper to do this for you.

Now, in OAuth 2.0 you have the following entities:

1. Users registered on your website
2. Applications registered on your website (who subscribe to your oauth2)
3. User Permissions which is a list of Applications that a user has 'allowed'
4. Developer (who is consuming your auth API / widgets and building an Application)

The first thing to note is you must have a domain name associated with each Application. So if a developer registers for a API token / secret on your website, the Application he creates is mapped to a unique domain.

Now, I presume that the flow for an application to authenticate users via your website is already clear. That being said, you don't need to do much for this to work.

When an Application sends the user to your website (in order to sign in) you place a session cookie on the user's computer. Lets call this "Cookie-X".

Now the user is authenticated by your website and goes back to the Application. There we want to show a custom widget with information pertaining to that user.

The developer will be need to copy paste some code into this app.

The flow is like this:

1. The code will contain a url to your website with his Application ID (not secret) which he got when registering his application on your website.

2. When that code runs, it will ping your website with his appId. You need to check that AppID with your database, and additionally check that the referrer url is from the same domain as that which is registered in your website for that AppID. Edit: Alternatively or additionally, the code can check for document.domain and include it in the ping to your website, allowing you to verify that the request has come from the domain that has registered with the given AppID.

3. If that is correct, you reply back with some JS code.

4. Your JS code looks for the session cookie your website had set when the user had signed in. If that cookie is found, it pings back to your website with the session and your website responds with the custom view content.

Edit: as rightfully mentioned in a comment, the cookie should be HttpOnly to safeguard against common XSS attacks.

Additional Notes

The reasons this is a secure approach:

1. The AppId and domain name are a good enough combination to verify that other people are not fetching this information. Even thou the appId is visible in the applications html source, the domain name would have to be spoofed by anyone attempting to use someone else's AppID.

2. Presuming someone takes an AppID which is not his, and writes code to spoof the domain name of the referrer when requesting for your widget, he still won't be able to see any information. Since you are showing user specific information, the widget will only render if your website can find the session cookie it placed on the users browser which can't really be spoofed. There are ways around like session-hijacking, etc. But I think that's beyond the scope of this question.

Other Methods Just by looking at Facebook's Social Plugins, you can tell that there are other options.

For example, one might be to use an Iframe. If you ask the developer to add an Iframe to his application, you can even reduce a few of the steps mentioned above. But you will have to add JS along with it (outside the iframe) to grab the correct domain, etc. And ofcourse from an accessibility and interface standpoint I'm not very found of Iframes.