authorize - tsukinoko-kun/papermc-web-api GitHub Wiki

The /authorize route is for the OAuth login.

OAuth2.0 Roles

The idea of roles is part of the core specification of the OAuth2.0 authorization framework. These define the essential components of an OAuth 2.0 system, and are as follows:

Resource Owner: The user or system that owns the protected resources and can grant access to them.

Client: The client is the system that requires access to the protected resources. To access resources, the Client must hold the appropriate Access Token.

Authorization Server: This server receives requests from the Client for Access Tokens and issues them upon successful authentication and consent by the Resource Owner. The authorization server exposes two endpoints: the Authorization endpoint, which handles the interactive authentication and consent of the user, and the Token endpoint, which is involved in a machine to machine interaction.

Resource Server: A server that protects the user’s resources and receives access requests from the Client. It accepts and validates an Access Token from the Client and returns the appropriate resources to it.

Process

Your client has to be registered in preferences.jsonc. You can have multiple clients.

You have to create the client yourself. This way, you can fully customize your users' experience.

This plugin is an OAuth provider (like Google, Microsoft, or GitHub). You can use any OAuth Library to log your user in.

The authorization process itself is done by this plugin. The user gets a one-time code to their Minecraft chat. The user then has to enter this code on the authorization website. If the code is correct, the user gets an access token to use the API and a refresh token to refresh the access token without redoing the whole authorization process. The user gets redirected to your client automatically.

Symbol	Description
User1	The user of the website
Client	Your client (website/app/…)
API	This plugin, running on a Minecraft Server
Player1	The player character of `User1` on the Minecraft Server

sequenceDiagram
    User1->>Client: Login player1
    Client->>API: Authorize player1 for client1
    API->>Player1: Login code is: ABCD
    API-->>Client: Please enter code
    Client-->>User1: Please enter code
    User1->>Client: ABCD
    Client->>API: ABCD
    API-->>Client: Access Token is: abc123def456
    Client-->>User1: Access Token is: abc123def456

First request

Parameters

URL Parameter	Description
`client_id`	Identifier of your client from the `preferences.jsonc`
`login`	The username or UUID of the user you want to use

Example

http://localhost:8080/authorize?client_id=d01&login=2fb36f12-426b-4610-9287-d43c24486db4

Final response

After the user successfully logged in, you will receive the tokens to the specified redirectUri for your client in preferences.jsonc.

The refreshToken is valid for 30 days.

The accessToken is valid for one day.

Schema

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "refreshToken": {
      "type": "string"
    },
    "accessToken": {
      "type": "string"
    }
  },
  "required": [
    "refreshToken",
    "accessToken"
  ]
}

Example

{
    "refreshToken": "UqmuxbrhkEep8I2qEOH73Xxa5TYC92Ogc8lWs65WlUTfmRPOjnb781QThUchIR1bPanoL86CnjBw2qFolOsOYw\u003d\u003d",
    "accessToken": "XSUjXNN1jhWkUeuN2i_RDLhN7oqT63YrQwZC1Kc38pFN_m3ZHDctVI0cLP5_g4tPuZQyr4_Xl6W3b0_dFVJZug\u003d\u003d"
}