Multiplayer authentication API
The multiplayer authentication API allows multiplayer servers (be they dedicated headless servers or games hosted from within a client) to verify that a connecting user is who they claim to be.
An overview of the API architecture is given in FFF-139.
All endpoints are relative to the https://auth.factorio.com/ URL.
API endpoints
/generate-server-padlock-2
This endpoint is called by the game server once on startup to obtain a public identifier and a shared secret.
Request
| Key | Description |
|---|---|
api_version |
always set to 6 by clients
|
Response
| Key | Type | Description |
|---|---|---|
server_padlock |
string | Shared secret between game server and auth server, opaque string |
server_hash |
string | Server identifier, opaque string |
/generate-user-server-key-2
This endpoint is called by a client when attempting to join a game server.
Request
| Key | Description |
|---|---|
api_version |
always set to 6 by clients
|
| Key | Description |
|---|---|
username |
The player's username, as obtained from the Web authentication API |
token |
User auth token, as obtained from the Web authentication API |
sever_hash |
Game server's identifier, transmitted during connection establishment |
Response
| Key | Type | Description |
|---|---|---|
server_key |
string | Base-64 encoded user-server-key |
server_key_timestamp |
string | Timestamp when server_key was issued, in YYMMDDhhmmss format
|
User-server-key algorithm
The game server verifies the join by calculating its own version of the user-server-key using the server_padlock, username, and server_key_timestamp. If it matches the server_key transmitted by the client, it must have been generated by the authentication server (because only it shares knowledge of the server padlock), thereby attesting the validity of the user's credentials.
The algorithm is as follows:
- Concatenate the padlock, username and timestamp strings, separated by underscores.
- Generate an MD5 HMAC over the resulting string, with the server padlock as the key
- Base64-encode the result
As an illustrative example, using shell commands:
$ padlock=ZjX+YSCEZgdFMVCzLLt8F8NOoWAmAG9WkUwv1dir4gg=
$ username=Xiretza
$ timestamp=240208183717
$ printf '%s_%s_%s' "$username" "$padlock" "$timestamp" | openssl mac -digest md5 -macopt "key:$padlock" -binary HMAC | base64
nV89TIBaIOvwUDQwrdK0/Q==
The game server should additionally verify that the server_key_timestamp is not too far in the past (so leaked user-server-keys cannot be reused indefinitely), but it is currently unknown whether this is done, and if so, what the expiry time is.