Authentication Server

From Armagetron
Revision as of 10:12, 24 July 2020 by Delinquent (talk | contribs) (Removed some of my poor attempts at humour which were out of keeping with the rest of the article)

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


How to run a phpbb3 forum based Authentication Server

Credits to fman23 and Lover$boy

Note: This guide was written specifically for phpbb3 only. Other/older variants of phpbb may not work, and you risk damaging your forum build. The editors of the wiki take no responsibility for the advice contained herein, although you may be able to obtain informal, unofficial assistance at the Armagetron support forums or the phpbb website.

You will need:

  • Access to FTP or a file manager
  • Access to your mysql database
  • A degree of patience, this will almost definitely not work first time.

Step One For this project, we're going to use the simpler php version of the auth that was edited by fman23, which can be found at his launchpad directory. Go ahead and copy "Config" and "index", and put them somewhere safe.

Step Two We're going to have to edit that config file to make it play nice with a mysql installation. Find the line that talks about the login information table. Edit the file so that it looks more like the following:

//Table containing login information
'table' => 'phpbb_users',

//Username column
'user_col' => 'username',

//Hash column, contains the md5 of the password after appending the prefixes and suffixes
'pass_prefix' => '',
'pass_suffix' => '',
'hash_col' => 'user_password',

//Role column, optionally contains the index of the user role (blank if disabled), it is designed to fit in with forums
'role_col' => 'group_id',

Change "Host", "User", "Pass" and "Database" to the values that match your website.

Step Three Whilst we still have the config open, we're going to amend all the columns to match our database. For example: Your "user" column may be represented by "user", "php_user", "phpbb"user", and so on. Make sure everything matches up. Save and close.

Step Four We need to edit the files in your phpbb installation to enable your forum users passwords to be stored in md5. Go to the root of your ftp folder (public_html), and find the following path:

/includes/functions.php

open up that php file and find the function "phpbb_hash"

Edit it so that it looks like so:

function phpbb_hash($password)
{
  return md5($password);
}

Save and close.

Step Five Go back to the root of your phpbb installation and create the following folder path:

/armaauth/0.1/

Now, upload the config and index files from earlier into the 0.1 folder, and exit.

Step Six Now, logout of the forum, login again, and request a password change. Change it to whatever, you can change it back to whatever was your previous password if you want to. For this to work, however, you must change the password at least once, for all users.


Understanding the requirements of 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.

However, there is not need for this you can just as well supply a FQDN after the "@".

The script

We have two example scripts. One is armagetronad/batch/authentication_reference.php [view]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