Authentication API

The authentication API allows a plugin to communicate with your own server securely, allowing you to verify who is talking to your server really is who they say they are.

For example, imagine a scenario where Bob is using your plugin. You want Bob to be able to send messages to your server, to let you know of something that Bob did. So you make your plugin make an HTTP request to your server with the information you want to handle. But how do you know that this request really is from Bob, and not Alice pretending to be Bob? This is where the authentication API comes in.

Openplanet's authentication API is built on top of Nadeo's own authentication that happens when you connect to a game server. This authentication has been abstracted to be as straight forward as possible for someone to use while still being secure.

Initial setup

In order to use authentication, you must first have a plugin created on the website already. If you haven't created a plugin on the website yet, click here to do so.

You must then also turn on authentication in your plugin admin settings from the Authentication tab.

You also have to include a siteid in your info.toml file manually, as this is needed for the authentication API to know which plugin on the website you are requesting a token for. You can find the site ID associated to your plugin on the public page of your plugin (the "Numeric ID") but also as part of the URL of your plugin admin page. The siteid should be added to the [meta] section, like this:

[meta]
name = "Shoutbox"
author = "Miss"
siteid = 201

There's 2 parts

In order for authentication to work, there's 2 parts to it:

1. The client side part (your plugin)
2. The server side part (your server)

You need for both of these to be implemented correctly in order to have a secure authentication.

On the client

You must do a couple things on the client, but the most important is to call Auth::GetToken. This function will asynchronously talk to Nadeo's and Openplanet's backend to create an intermediate Openplanet authentication token:

// Start the task to get the token from Openplanet
auto tokenTask = Auth::GetToken();

// Wait until the task has finished
while (!tokenTask.Finished()) {
  yield();
}

// Get the token
string token = tokenTask.Token();

At this point, you must send the token to your server. This can be in any way you are communicating with your server, but note that these intermediate tokens are very short lived and expire after a very short time. (At the time of writing the expiration time is set to 5 minutes, but this may change in the future. The point is that you should not keep this token around, in most scenarios you should only need it for maybe a few seconds during authentication.)

When your server receives the token, it should validate that the token is actually valid. You do this by making an HTTP POST request to:

https://openplanet.dev/api/auth/validate

The body of the request should be of content type application/x-www-form-urlencoded, and contain the token passed by the user, and secret as shown to you on the Authentication tab of the plugin admin site. For example:

token=the_token_from_the_user&secret=your_unique_plugin_secret

If something went wrong, you'll receive an error json response like this:

{
  "error": "a description of the encountered error"
}

When an error is received, do not trust the user, and reject their authentication. You can't trust who they say they are at this time.

If everything went well, you will get a json response that looks like this:

{
  "account_id": "7398eeb6-9b4e-44b8-a7a1-a2149955ac70",
  "display_name": "Miss-tm",
  "token_time": 1729446589
}

If you receive this information, it means that the user has successfully proven who they are, and you can trust that the request containing this token really came from them. token_time is provided as the timestamp at which the user's intermediary token was generated.

Persistency

As a result of Openplanet's intermediary tokens being so short-lived, you may want to exchange this token with a token of your own, so that you don't have to call any of Openplanet's architecture anymore to authenticate them in the future. This is not strictly necessary, but it is highly recommended if you need to keep a persistent authentication. This way you don't unnecessarily stress the Openplanet API. (We may disable a plugin's access to authentication should they abuse our resources.)

Examples

We have developed a feature-complete example plugin to demonstrate the authentication API, which can be used as a reference: the Shoutbox plugin. It's available to install through the plugin manager, and will authenticate your game account into a small "chatroom".

You can find the source code for the plugin on Github, as well as the source code for its backend.