Step one:
Code: Select all
GET: https://tgstation13.org/phpBB/oauth_create_session.php?site_private_token=SomeTokenHere&return_uri=https%3A%2F%2Fsomesite.com%2Freceive.php
- site_private_token: base64 encoded string (between 32 and 255 bytes decoded) as an identifier for your site. This will be needed to retrieve any details. This should be kept secret and remembered. (note: base64 strings are not url safe and must be url encoded)
- return_uri: Place to send the user when they approve the login. The hostname portion of this will be shown to the user.
- Note: No information will be appended by the oauth system to this uri, it is your responsibility to either include some sort of identifier here so you can link the returning user to the oauth session or use cookies to do the same.
Code: Select all
{
"status":"OK",
"session_private_token":"4ZeInoLFLqK65bp7XJHD9TOS+kzFvT2KhTLv3Zg0ARfrlUc75HmMIIxhWR2kQLy\/tMfFdW7pdeJ6wnUbU3rK8g==",
"session_public_token":"greeXIElmDjHmL3Nn+zw75cNRmGx0o\/m3d01MOWg3p387OGO+h1vjAQzjZhapd4\/E5bZhtpmIdqvmirXLd35mA=="
}
- status: OK|error
- error: Error message explaining what went wrong (or nonexistent). (Please include the full unmodified error message in all help requests. There are errors with similar but different messages so that I can know what exact check failed.)
- session_private_token: base64 encoded 64 byte string. This will be used to get the user details after they approve your access. This is private and not even the user should be allowed to see it. Do not accept user provided private tokens.
- session_public_token: base64 encoded 64 byte string. This will be sent with the user when asking permission to log in.
Step two:
Code: Select all
USER REDIRECT: https://tgstation13.org/phpBB/oauth.php?session_public_token=SomeTokenHere
- session_public_token: the public session token from the first step. (note: base64 strings are not url safe and must be url encoded)
Step Three:
After the user returns to the site listed in return_uri in the first step:
Code: Select all
GET: https://tgstation13.org/phpBB/oauth_get_session_info.php?site_private_token=SomeTokenHere&session_private_token=SomeTokenHere
- site_private_token: base64 encoded string (between 32 and 255 bytes decoded) from step 1. (note: base64 strings are not url safe and must be url encoded)
- session_private_token: the private session token from the first step. (note: base64 strings are not url safe and must be url encoded)
Code: Select all
{
"status":"OK",
"phpbb_username":"MrStonedOne",
"byond_key":"MrStonedOne",
"byond_ckey":"mrstonedone"
}
- status: OK|error
- error: Error message explaining what went wrong (or nonexistent). (Please include the full unmodified error message in all help requests. There are errors with similar but different messages so that I can know what exact check failed.)
- phpbb_username: The users forum username
- byond_key: The user's byond username (key) or false if they haven't linked a byond account
- byond_ckey: The ckey version of the user's byond username. This will be all lowercase and not contain special characters. Internally to byond and /tg/station's systems this is the user's TRUE username, the key is only for displaying.
- oauth_get_session_info.php does not expire tokens unless they go long (30 days) without use or the user changes their password. Do not cache the info it provides for too long, and consider re-validating the session when processing protected actions.
- This system is secure (in theory) against spoofing, but not reverse spoofing. an attacker cannot spoof a user's account but could in theory trick a user into logging in as the attackers account. To protect against this (if it actually matters for your use case, it doesn't for most), when processing a return from an oauth.php redirect, give the user a prompt displaying the phpbb and byond account names they are about to login as and protect this prompt against CSRF.
- Base64 strings are not url safe and must be url encoded