Multiplayer authentication API: Difference between revisions
Jump to navigation
Jump to search
(Created page with "<div align="center" class="stub">'''Category:''' Internal API</div> 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 [https://www.factorio.com/blog/post/fff-139 FFF-139]. All endpoints are...") |
mNo edit summary |
||
| Line 28: | Line 28: | ||
! Key !! Type !! Description | ! Key !! Type !! Description | ||
|- | |- | ||
| <code>server_padlock</code> || string || Opaque random string | | <code>server_padlock</code> || string || Opaque random string, shared secret between game server and auth server | ||
|- | |- | ||
| <code>server_hash</code> || string || Opaque identifier | | <code>server_hash</code> || string || Opaque game server identifier | ||
|} | |} | ||
=== <code>/generate-user-server-key-2</code> === | |||
==== Request ==== | |||
{| class="wikitable" | |||
|+ Query parameters | |||
|- | |||
! Key !! Description | |||
|- | |||
| <code>api_version</code> || always set to <code>6</code> by clients | |||
|} | |||
{| class="wikitable" | |||
|+ x-www-form-urlencoded body | |||
|- | |||
! Key !! Description | |||
|- | |||
| <code>username</code> || The player's username, as obtained from the [[Web authentication API]] | |||
|- | |||
| <code>token</code> || User auth token, as obtained from the [[Web authentication API]] | |||
|- | |||
| <code>sever_hash</code> || Server's identifier, transmitted during connection establishment | |||
|} | |||
==== Response ==== | |||
{| class="wikitable" | |||
|+ JSON body | |||
|- | |||
! Key !! Type !! Description | |||
|- | |||
| <code>server_key</code> || string || Base-64 encoded user-server-key | |||
|- | |||
| <code>server_key_timestamp</code> || string || Timestamp when <code>server_key</code> was issued, in <code>YYMMDDhhmmss</code> format | |||
|} | |||
== User-server-key algorithm == | |||
The game server verifies the join by calculating its own version of the user-server-key using the <code>server_padlock</code>, username, and <code>server_key_timestamp</code>. If it matches the <code>server_key</code> transmitted by the client, it knows that it was generated by the authentication server, attesting the validity of the user's credentials. | |||
The algorithm is as follows: | |||
1. Concatenate the padlock, username and timestamp strings, separated by underscores. | |||
2. Generate an MD5 HMAC over the resulting string, with the server padlock as the key | |||
3. Base64-encode the result | |||
As an illustrative example, using shell commands: | |||
<pre> | |||
$ 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== | |||
</pre> | |||
Revision as of 21:59, 18 October 2024
Category: Internal 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
Request
| Key | Description |
|---|---|
api_version |
always set to 6 by clients
|
Response
| Key | Type | Description |
|---|---|---|
server_padlock |
string | Opaque random string, shared secret between game server and auth server |
server_hash |
string | Opaque game server identifier |
/generate-user-server-key-2
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 |
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 knows that it was generated by the authentication server, attesting the validity of the user's credentials.
The algorithm is as follows:
1. Concatenate the padlock, username and timestamp strings, separated by underscores. 2. Generate an MD5 HMAC over the resulting string, with the server padlock as the key 3. 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==