Integration Guide
From Neuron Interactive
If your website support user registration, you can integrate OpenID enabled browser games.
Contents |
OpenID
Introduction
The most important part of the integration is the authentication protocol. Given it's open nature, we have decided to (ab)use OpenID for this. OpenID is a protocol that uses signed data and a whole bunch of redirects to ensure proper authentication. The weird thing about OpenID is that the authentication is handled on client side, not on server side. There is no server-to-server communication, which might look a little weird at first, but makes perfectly sense.
The regular use of OpenID is as following:
- A user registers an account with an OpenID provider. The provider shows this user a unique Identity URL.
- When a user visits a website that allows OpenID login, he writes his Identity URL in the login form.
- The user is now redirected to the providers website. The provider checks if this user is actually logged in, checks if this user has approved authentication for this site, etc.
- When everything is right, the user is redirected back to the website and is logged in. If it's the first time he logs in there, he might have to fill in some extra information, like choosing a nickname etc. However, the user is already logged in when he is redirected back, so no huzzle with passwords.
Our abuse
This is, ofcourse, a great idea: having one single identity on the web. But we're not going to use that. Your website will have to be its own OpenID provider in order for everything to work.
So the first step is setting up an OpenID provider on your website. This is, in fact, a fairly easy job if you use one of the libraries from OpenID.net. You will have to adapt it to make it use your own user database, etc.
The game has information about its OpenID URLs. This information can be found in the Information API, in the servers part.
You should fetch this information file on a regular basis (let's say once a day) and update your (game and) server list.
If everything is right, it should look like this:
<openid_url>http://testing.neuroninteractive.com/openid/login/?openid_url=%s</openid_url>
From now on it's simple: when a player chooses to play a game, you redirect him to it's openid_url. The only thing you have to do is replace the %s with the users personal OpenID account. If the game has implemented everything right, the user should be back in just a few nanoseconds.
Ideally, the user does not notice this authentication process. That's why I prefer not to show the "Please confirm that you want to login at xxx" part. In fact, before the user is redirected to the game, it should be redirected to a script on your side that adds this specific game URL to a whitelist.
All regular OpenID features are ofcourse available. One of them, the Simple Registration Extension is particularly handy to speed up the registration process. A lot of games will require an email, so, if available, send it to them.
Notifications
Why not allow users to use their own OpenID to join the game? One simple reason: server to server communication. Some games support notification, news items, profile box updates, etc. Documentation for these can be found on this wiki, but let's take a look at notification.
A notification is a message that notifies a user (or his friends) about an action taken by this user. They are sent by the game and should be received by the players platform. Each platform is free to implement these and they are not required. However, the more information you can show your users, the better, right?
The idea is simple: while the user is logging in, you send a secret notification URL to the game. This notification URL should be unique for every game and every server and should, in fact, be updates once in a while. (Security is no concern for the game owner, the provider should make sure everything is secured.)
The game then uses this URL to send notification.
To make this all safe, we have to use another OpenID extension: Attribute Exchange. This allows use to send any information we want during the login procedure. This extension requires online schemas of every attribute we use; these can be found here.
When the game receives a notification URL, it will start sending notifications. For syntax and more information, take a look at the Notification API page.
