Authentication Server

From Armagetron
Revision as of 21:09, 21 February 2009 by Joda (talk | contribs) (→‎The script)

Sections: Installing the Game | Playing the Game | Competition Hub | Server Administration | Extending Armagetron Advanced | Development Docs


How to run an Authentication Server

Have a look at the protocol to see what is expected of an Authentication Server. Game servers will issue HTTP requests to it with

  • user name
  • salt
  • scrambled password hash

And your job is to figure out whether the password the hash was generated from was correct. That's easiest if you have the users' plainext password stored somewhere; however, that is not common practice. To support the bmd5 hash protocol (the only one available on 0.2.8.2.1 resp. 0.3.0 clients and earlier), you specifically need the md5 hashsum of the password with an appended 0 byte. For the newer md5 hash protocol, the md5 sum of (prefix + password + suffix), where prefix and suffix choice is up to you, is needed.

If you don't have the password in this form in your database, you'll need to generate it. forums.armagetronad.net uses a trick: whenever a user logs on, the server gets the plaintext password, and then the hash for the bmd5 protocol is stored. phpBB2 already stores the plain md5 hash of the password, so the md5 protocol is natively supported with prefix=suffix="".

To run an authentication server, you need control over a web server with scripting available. If your authority name shall be bla.blubb.net, game servers will query the URI http://bla.blubb.net/armaauth/0.1 with an appended query string; if you make /armaauth/0.1 a directory and put your authentication script there, named index.php or index.py or even index.sh, whatever your server supports, it will be called to process the requests.

If you can't access /armaauth/0.1, you can put it into a subdirectory. If you put it into /~user/armaauth/0.1, then your authority will be named bla.blubb.net/~user.

Users of your authority will be known as username@authority. Don't worry about naming collisions between users of equal name at different authorities, the authority part appears in all logs, and by default, there is no forced link between the screen name and user name of a player.

Shorthand names

If you want a shorthand authority name, talk to Tank Program/Guru3. Shorthand names get expanded to <shorthand>.authentication.armagetronad.net, and we can set up a DNS CNAME entry that maps this name to your server. There are some conditions for that:

  • Your authority must be free for everyone to join. Clan authorities that only authorize clan members are out.
  • Your authority must make a reasonable effort to give only one username to a single person; email verification is enough.
  • It needs to either already have a couple of members or show promise for growth. We don't need Yet Another Dead Forum.

The script

We have two example scripts. One is armagetronad/batch/authentication_reference.php of the current 0.2.8 branch or the trunk. It is written by a php n00b and therefore should be understandable by php n00bs :) You can attach your "business logic", the password retrieval, either in the getPassword() function or the getPasswordHash() function. The comments there should tell you what you need to do.

The other script is more elaborate and can directly plug into user databases; you'll just have to configure it with your database connection and tell it in what row and table of a database username and password hash can be found. it can be checked out with

bzr co lp:~armagetronad-dev/armagetronad/trunk-http-auth-server-work [browse]

Blurb

On successful authentication, you can also pass additional data about the user in the lines following the one containing "PASSWORD_OK". In the future, there may be standard blurb messages the game server itself understands; currently, however, there is only one effect: A blurb line of the form

<TOKEN> <further data>

where <TOKEN> is a single word and <further data> is arbitrary text will be logged in ladderlog.txt as

AUTHORITY_BLURB_<TOKEN> user@authority <further data>

One standard blurb message would be

ALIAS otheruser@otherauthority

telling ladderlog parsers that choose to believe your authority that the just authenticated user is actually the same person as the user given in the alias.

Proposed Blurbs for spec 0.2

  • EMAIL_VERIFIED true/false

Sections: Installing the Game | Playing the Game | Competition Hub | Server Administration | Extending Armagetron Advanced | Development Docs