/tg/ OAuth2.0 User API Documentation

[ABearInTheWoods]

This is early stages. Oauth application registration requires a manual process only I can do, a self serve system may or may not get coded at some later point in time.

Basic details: (for people who know how to use OAuth apis)

Code: Select all

Auth endpoint: https://tgstation13.org/phpBB/app.php/tgapi/oauth/auth
Token endpoint: https://tgstation13.org/phpBB/app.php/tgapi/oauth/token
User endpoint: https://tgstation13.org/phpBB/app.php/tgapi/user/me

(Warning, per the oauth2 spec, attempting to double spend the initial authorization code grant invalidates the entire authorization grant and all tokens/refresh tokens issued by it, as an additional security matter, the same applies to refresh tokens)

• Token format: bearer (length between 40 and 50 characters currently, never more than 255 in the future, but even 128 would be stretching it)
• Token TTL: app defined.
• Token endpoint supports url-form-encoded and json encoded POST bodies.
• Token endpoint does NOT support authorization header client authentication (pass it in as client_id and client_secret via the post body or json body)
• Refresh tokens: Supported, Single use rotating refresh tokens.
• Redirect_uris must be pre-registered and must exactly match. if provided to any of the oauth endpoints, it will be validated against the registered redirect uri, but is optional.

Scopes:

► Show Spoiler

Code: Select all

user - Forum username and user id.
user.details - Details about the forum account (avatar, post count, date of register and last access, etc)
user.linked_accounts - Linked accounts (byond, github, digg)
user.groups - User's public forum groups
user.groups.private - User's private/hidden forum groups
user.email - User's email address.

(child scopes imply the parent scope, ie, user.groups.private implies user.groups and user)
Default scope is user.linked_accounts

For more info on how to interface with OAuth2 apis, see this page: https://aaronparecki.com/oauth-2-simplified

User endpoint:

https://tgstation13.org/phpBB/app.php/tgapi/user/me

Only bearer token authorization is supported. (see here for more details)

Response(json):

► Show Spoiler

Code: Select all

{
    "user_id": 2,
    "username": "MrStonedOne",
    "phpbb_username": "MrStonedOne",
    "username_clean": "mrstonedone",
    "primary_group": 32,
    "user_type": 3,
    "registered": 1397516164,
    "lastvisit": 1635284432,
    "rank": "19",
    "posts": 2237,
    "timezone": "America\/Vancouver",
    "avatar": "2_1611023016.png",
    "email": "[email protected]",
    "byond_key": "MrStonedOne",
    "byond_ckey": "mrstonedone",
    "github_username": "MrStonedOne",
    "digg_username": "monarchmra",
    "groups": [
        {
            "group_id": 5,
            "group_name": "ADMINISTRATORS",
            "group_leader": true,
            "group_type": 3
        },
        {
            "group_id": 11,
            "group_name": "Byond Users",
            "group_leader": false,
            "group_type": 1
        },
        {
            "group_id": 40,
            "group_name": "DB Operator",
            "group_leader": false,
            "group_type": 2
        },
        {
            "group_id": 18,
            "group_name": "FNR banned.",
            "group_leader": true,
            "group_type": 1
        },
        {
            "group_id": 4,
            "group_name": "GLOBAL_MODERATORS",
            "group_leader": false,
            "group_type": 3
        },
        {
            "group_id": 16,
            "group_name": "Game Server Operators",
            "group_leader": true,
            "group_type": 1
        },
        {
            "group_id": 25,
            "group_name": "Github Users",
            "group_leader": false,
            "group_type": 1
        },
        {
            "group_id": 36,
            "group_name": "Head Admin Candidate",
            "group_leader": false,
            "group_type": 0
        },
        {
            "group_id": 32,
            "group_name": "Host",
            "group_leader": true,
            "group_type": 1
        },
        {
            "group_id": 8,
            "group_name": "In-Game Admin",
            "group_leader": true,
            "group_type": 1
        },
        {
            "group_id": 15,
            "group_name": "In-Game Head Admins",
            "group_leader": true,
            "group_type": 1
        },
        {
            "group_id": 2,
            "group_name": "REGISTERED",
            "group_leader": false,
            "group_type": 3
        },
        {
            "group_id": 28,
            "group_name": "digg Users",
            "group_leader": false,
            "group_type": 1
        }
    ]
}

(phpbb_username is an alias for username for compatibility with consumers of the old api)

Group type:

► Show Spoiler

Code: Select all

// Group type
define('GROUP_OPEN', 0);
define('GROUP_CLOSED', 1);
define('GROUP_HIDDEN', 2);
define('GROUP_SPECIAL', 3);
define('GROUP_FREE', 4);

[bobbahbrown]

for those who might be interested in using this in an ASP.NET 5.0 (or greater) project, i have created an easy-to-use oauth handler for /tg/station. you can find it on nuget at Tgstation.Auth, or alternatively on GitHub here.

once you get a client ID registered with MSO, it is as simple as adding a dependency on that package and using the extension methods like in the following example...

Code: Select all

services.AddAuthentication(options =>
    {
        options.DefaultAuthenticateScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultSignInScheme = CookieAuthenticationDefaults.AuthenticationScheme;
        options.DefaultChallengeScheme = TgDefaults.AuthenticationScheme;
    })
    .AddCookie()
    .AddTgstation(options =>
    {
        var tgAuthSection = Configuration.GetSection("Authentication:Tgstation");
        options.ClientId = tgAuthSection["ClientId"];
        options.ClientSecret = tgAuthSection["ClientSecret"];
        options.Scope.Add("user.details");
        options.Scope.Add("user.groups");
    });

best wishes,
bobbah 'bee' brown