Feature: Allow configuring API URLs

[evan-goode]

I would like to configure the API_BASE_URL to point to a different server than api.geysermc.org. Perhaps config options like api.base-url and api.websocket-url. Happy to prepare a PR if one would be welcome!

[SleepyPopp]

Feel free to open a new pull request. We welcome any contributions.

[SleepyPopp]

Please note we have an AI policy: https://github.com/GeyserMC/.github/blob/master/AI_POLICY.md

[Tim203]

Something like that would defeat the purpose of the global api, which is why I personally would be hesitant to accept something like that (especially as config option.) When the global api becomes a local api then you could've just used local linking. There are also sites using the global api to get skin information about players (e.g. to show an avatar on their website), which would also stop working if it becomes a local api.
I could maybe see something in an environment variable, but due to reasons like the ones mentioned above I also wouldn't be a big fan about that.

[Tim203]

I'm more open to a local linking type that calls an URL to look if the player is linked (instead of looking at a database like the current local linking database types.) Would that also fit your use case?

[tnqzh123]

I'm more open to a local linking type that calls an URL to look if the player is linked (instead of looking at a database like the current local linking database types.) Would that also fit your use case?

One use case of custom Global API is using Geyser & Floodgate with a custom Yggdrasil authentication server (e.g. public services like LittleSkin / Ely.by or self-hosted Blessing Skin / Drasl instance). You may refer to authlib-injector for more information.

In this circumstance, "global" is the custom Yggdrasil authentication server but not Mojang. As players may have a different UUID with their Mojang account in those auth servers, the official Geyser Global API is not usable. HTTP interface for Local Linking can absolutely "work" since Global Linking and Local Linking are basically doing the same thing but in different scopes, but it's still Local Linking, 1) if a player is not linked in local then Floodgate may fallback to global (Mojang), resulting a totally wrong profile, 2) game server owners may want to build their own Local Linking while not breaking the Global Linking of public custom Yggdrasil auth servers.

[tnqzh123]

One use case of custom Global API is using Geyser & Floodgate with a custom Yggdrasil authentication server (e.g. public services like LittleSkin / Ely.by or self-hosted Blessing Skin / Drasl instance). You may refer to authlib-injector for more information.

A bunch of servers are already doing this. Before the sunset of traditional username & password login API, it's okay since players could just enter their credentials in those custom Yggdrasil auth server and authlib-injector will handle these calls of the login API to the custom Yggdrasil auth server, but for now Global Linking / Local Linking is the only way to do this. You may refer to yushijinhun/authlib-injector#230 and yushijinhun/authlib-injector#295 for more information.

[Tim203]

if a player is not linked in local then Floodgate may fallback to global (Mojang), resulting a totally wrong profile

This is only true if you've enabled global linking, which is something you should disable if you want to use your own auth server.
If the player isn't linked locally and global linking is disabled, Floodgate will use the Bedrock's XUID as UUID.

game server owners may want to build their own Local Linking while not breaking the Global Linking of public custom Yggdrasil auth servers.

I don't think that this something that should be in scope of Floodgate. Using a custom authentication server is already unsupported territory and having to consider this use case too would be pushing it. And if we were to add a http local linking type, there's nothing stopping you from implementing such a fallback system yourself. Your local linking http server could call auth server's global linking endpoint and return it, Floodgate would blindly accept what is returned from that endpoint.

By using your own http local linking you'd gain the functionality you want to see, without the downsides that using a different global api would bring to the wider Minecraft community.

[tnqzh123]

And if we were to add a http local linking type, there's nothing stopping you from implementing such a fallback system yourself. Your local linking http server could call auth server's global linking endpoint and return it, Floodgate would blindly accept what is returned from that endpoint.

Then for /linkaccount and /unlinkaccount, how to distingush whether the HTTP Local Linking interface is a real Local Linking or a "Global Linking"? Some public custom auth servers may only allow account linking / unlinking on web, and bad designs in game may lead to confusion. Or will you just recommend turn it off in this circumstance?

By using your own http local linking you'd gain the functionality you want to see, without the downsides that using a different global api would bring to the wider Minecraft community.

Just curious: wdym "downsides that using a different global api would bring to the wider Minecraft community"? IMO others don't use custom Global API / custom auth server won't be affected at all. I'm not familar with Geyser ecosystem, a more clear explanation would help me to evaluate the feature we're talking here better.

Thanks for your patience, hope these questions won't be too pushy!

[evan-goode]

Yes, I'm also thinking of the custom authentication server use case. I absolutely understand why a single global API is preferable for linking Microsoft BE and Microsoft JE accounts (ideally, Mojang would offer this API themselves, right?). But Floodgate could also be useful for linking Microsoft BE accounts and JE accounts on some other authentication server. @tnqzh123 and I are imagining a design where the JE authentication server also implements the Floodgate linking API. In that situation, the linking API server is still "global" in the sense that there is a single linking server for the authentication server, and all MC servers using that authentication server should also be configured to use that linking server.

HTTP local linking sounds promising too.

[Tim203]

Then for /linkaccount and /unlinkaccount, how to distingush whether the HTTP Local Linking interface is a real Local Linking or a "Global Linking"? Some public custom auth servers may only allow account linking / unlinking on web, and bad designs in game may lead to confusion. Or will you just recommend turn it off in this circumstance?

When you run /unlinkaccount then it first checks if you're linked, and then it tries to unlink which will result in Floodgate e.g. calling POST /unlink { xuid: *your xuid* }. Because Bedrock doesn't have a system like chat/command signing it's not possible to verify that the Bedrock player actually wants to link or unlink, which is exactly why you can't link/unlink from global linking on a third-party server, because third parties cannot be trusted. So managing global linking inside a third-party server is probably not something that you'd want.

It's true though that if we'd add HTTP local linking today and you're only linked on your global level linking using the HTTP local linking then running /unlinkaccount will either tell you that an error occurred while unlinking (since you won't be able to unlink from your global level linking) or that unlinking was successful (and nothing happened because you were only linked globally) depending on how you'd implement this. There is currently no in between, as local linking was only meant to have one level of linking. Maybe this can be improved in the future.

The link commands are behind a permission, so if you need to link on a website then it'd be your responsibility to make that clear. You could just disabled the linking commands and only use the HTTP local linking for the actual fetching.

Just curious: wdym "downsides that using a different global api would bring to the wider Minecraft community"? IMO others don't use custom Global API / custom auth server won't be affected at all. I'm not familar with Geyser ecosystem, a more clear explanation would help me to evaluate the feature we're talking here better.

Currently the global api has 4 main features: Bedrock skin conversion so that Java players can see some version of a Bedrock skin, global linking so that you link once and use it on thousands of servers, xuid<->gamertag lookups allowing you to lookup what the gamertag (Bedrock username) is given a Xbox Unique ID (xuid, Bedrock's UUID variant) and visa versa, getting the current skin of a Bedrock player. These features can be used on various types of websites like: shops, leaderboards, profile lookups (like your NameMC, laby.net) and more.
If you use a different global api then those features will be less accurate. This will also impact e.g. the /fwhitelist command, which also depends on that profile lookup functionality.

... are imagining a design where the JE authentication server also implements the Floodgate linking API. In that situation, the linking API server is still "global" in the sense that there is a single linking server for the authentication server, and all MC servers using that authentication server should also be configured to use that linking server.

I honestly don't know: is it common that people share the same authentication server? Or is the average use case one authentication server for a single server and that people register per server? I'd imagine that it'd be fragmented

[tnqzh123]

... These features can be used on various types of websites like: shops, leaderboards, profile lookups (like your NameMC, laby.net) and more.

If you use a different global api then those features will be less accurate. This will also impact e.g. the /fwhitelist command, which also depends on that profile lookup functionality.

Shops and leaderboards are inherently server-specific ecosystem services, which must be integrated or implemented by server operators themselves and must use the identity system selected by the server. IMO if a server uses a third-party Yggdrasil authentication server, then they should build their own ecosystem services or use ecosystem services provided by the auth server, otherwise it will make their data inaccurate, since they're detached from the official Java Edition identity system.

Bedrock skin conversion and lookups can also be handled by third-party Yggdrasil auth server, since it's already handling skins and capes of Java Edition players, but yeah, using GeyserMC's Global API could be simpler. Profile lookups are same, it can also be handled by third-party Yggdrasil auth server (maintaining a XUID <-> Gamertag map by auth server itself), but servers may benefit from the larger cache of GeyserMC's Global API.

It will be nice if Geyser and Floodgate could separate Global Linking and other Global APIs, that's my initial idea on yushijinhun/authlib-injector#291: intercept Global Linking query requests only.

I honestly don't know: is it common that people share the same authentication server? Or is the average use case one authentication server for a single server and that people register per server? I'd imagine that it'd be fragmented

According to our (@LittleSkinChina) statistics, more than 4000 Minecraft servers and 10000 players use our public Yggdrasil authentication service every day, and more than 60000 players joined at least two Minecraft servers using the same identity in the past 90 days. It's certainly not a huge number, but it's not a small one either, especially considering our major user base is in mainland China. Ely.by is also providing public Yggdrasil authentication service, they have higher ranking in both Tranco and Cloudflare Radar. So "share the same authentication server" is definately not something just exists in theory.

There are also many servers that run their own self-hosted Yggdrasil authentication server, but I cannot tell the number.

[Tim203]

but servers may benefit from the larger cache of GeyserMC's Global API.

Yeah that's the idea, one centralized place with the most accurate data.

It will be nice if Geyser and Floodgate could separate Global Linking and other Global APIs, that's my initial idea on yushijinhun/authlib-injector#291: intercept Global Linking query requests only.

I still think that it makes more sense to create a HTTP local linking type, even if this HTTP type is an outlier compared to our other local linking types which are directly connected to databases. Because by providing a different global linking server it no longer feels global to me because it's automatically a subset of servers. Currently the definition of local linking is account linking that's specific to your Minecraft network. Normally this means a single Minecraft server that can exists of multiple backing servers like Hypixel or CubeCraft, but I think that expanding that definition to use the generic term network (which is simply a group of communicating servers) feels the most logical.
Strictly speaking Floodgate 2.0 is currently in maintenance-only mode, and all development effort goes to Floodgate 3.0. But adding another local linking type should be something that can be implemented in less than a day, so maybe I'll just pick it up someday - no promises.
You're also free to make a PR if you'd like, it'd probably be similar to the current /v2/link/bedrock/{xuid} minus the last_name_update field (and a 404 when the profile isn't found instead of 200 with an empty object)