mc-drasl/doc/recipes.md

Recipes

This document is intended to exhibit the variety of use cases Drasl can support. Each example includes a complete configuration file and may be used as a starting place to configure your own instance.

See configuration.md for detailed documentation of each config option.

Example 1: Basic, minimal setup

• Private and standalone: does not interact with any other API servers
• Registering a new account requires an invite from an admin (RegistrationUsernamePassword.CreateNewPlayer.RequireInvite)
• Seamless migration from online-mode=false servers: UUIDs of new players will be derived from their player name using the same algorithm used by Minecraft to derive player UUIDs in online-mode=false servers (PlayerUUIDGeneration)

Domain = "drasl.example.com"          # CHANGE ME!
BaseURL = "https://drasl.example.com" # CHANGE ME!
DefaultAdmins = ["myusername"]        # CHANGE ME!
PlayerUUIDGeneration = "offline"

[RegistrationUsernamePassword.CreateNewPlayer]
  Allow = true
  RequireInvite = true

Example 2: Mojang-dependent

• Minecraft servers must set enforce-secure-profile=false in server.properties. (FallbackAPIServers).
• Users can register a new account only if they verify ownership of a Mojang account. Their account will be assigned the UUID of the Mojang account, so servers will see them as the same player. (RegistrationUsernamePassword.ImportExistingPlayer, RequireSkinVerification).
• Clients logged in with either Drasl or Mojang will be able to play on the same server (FallbackAPIServers, EnableAuthentication).
• Drasl players will be able to see Mojang players' skins (but not vice-versa) (ForwardSkins).
• Useful for public instances wanting to limit registration.

Show config.toml

Domain = "drasl.example.com"          # CHANGE ME!
BaseURL = "https://drasl.example.com" # CHANGE ME!
DefaultAdmins = ["myusername"]        # CHANGE ME!

SignPublicKeys = false
AllowChangingPlayerName = false

[RegistrationUsernamePassword.CreateNewPlayer]
  Allow = false

[[FallbackAPIServers]]
  Nickname = "Mojang"
  DiscoveryMinecraftClientURL = "https://discovery.minecraftservices.com/minecraft/client"
  EnableAuthentication = true
  ForwardSkins = true
  SetSkinURL = "https://www.minecraft.net/msaprofile/mygames/editskin"

[[RegistrationUsernamePassword.ImportExistingPlayer]]
  FallbackAPIServerNickname = "Mojang"
  RequireSkinVerification = true

Example 3: Proxy multiple authentication servers

• Minecraft servers must set enforce-secure-profile=false in server.properties. (FallbackAPIServers).
• Allow users to authenticate with either an Ely.by account or a Blessing Skin account ([[FallbackAPIServers]])
• Players logged in with Ely.by unfortunately won't see the skins of players logged in with Blessing Skin, and vice versa. You might be able to fix that by using CustomSkinLoader to have the clients load skins through Drasl.
• Registration is disabled (RegistrationUsernamePassword.CreateNewPlayer.Allow)
• Warning: Fallback API Servers are tried in the order they are listed in the config file. A malicious user may be able to impersonate a user on the second-listed Fallback API Server by making an account on the first-listed Fallback API Server with the same username (or possibly even the same UUID).

Show config.toml

Domain = "drasl.example.com"          # CHANGE ME!
BaseURL = "https://drasl.example.com" # CHANGE ME!
DefaultAdmins = ["myusername"]        # CHANGE ME!

SignPublicKeys = false

[RegistrationUsernamePassword.CreateNewPlayer]
  Allow = false

[[FallbackAPIServers]]
  Nickname = "Ely.by"
  AuthlibInjectorURL = "https://account.ely.by/api/authlib-injector"

[[FallbackAPIServers]]
  Nickname = "Blessing Skin"
  AuthlibInjectorURL = "https://skin.example.net/api/yggdrasil"

Example 4: Stealth setup

• Basic setup, but add a random, secret suffix to the BaseURL to limit unwanted access. Everything still works even if / is not the root of the API.

Show config.toml

Domain = "drasl.example.com"                  # CHANGE ME!
BaseURL = "https://drasl.example.com/jaek7iNe # CHANGE ME!
DefaultAdmins = ["myusername"]                # CHANGE ME!

[CreateNewPlayer]
  AllowChoosingUUID = true

[RegistrationUsernamePassword.CreateNewPlayer]
  Allow = true
  RequireInvite = true

Example 5: Single sign-on (SSO) via OpenID Connect (OIDC)

• Users can sign in to Drasl using the OIDC providers idm.example.com and/or lastlogin.net ([[RegistrationOIDC]]). Drasl users linked to one or more OIDC accounts will not be able to log in with a password. To log in to Minecraft launchers, they'll need to instead use their "Minecraft Token" shown on their user page.
• The OIDC user's email address will be used as their Drasl username. When a user registers, the user's player name will be the IDP-provided preferred_username or the player name of the user's choice (AllowChoosingPlayerName = true).
• Users will not be allowed to register an account with a password (AllowPasswordLogin = false). Existing Drasl users who already have an account with a password will not be able to sign in until they link their account with an OIDC provider.
• IDPs should be configured to allow Drasl the email, openid, and profile scopes.

Show config.toml

Domain = "drasl.example.com"                  # CHANGE ME!
BaseURL = "https://drasl.example.com          # CHANGE ME!
DefaultAdmins = ["myusername"]                # CHANGE ME!

AllowPasswordLogin = false

[RegistrationUsernamePassword.CreateNewPlayer]
  Allow = true

[[RegistrationOIDC]]
  Name = "Kanidm"
  Issuer = "https://idm.example.com/oauth2/openid/drasl"            # CHANGE ME!
  ClientID = "drasl"                                                # CHANGE ME!
  ClientSecret = "yfUfeFuUI6YiTU23ngJtq8ioYq75FxQid8ls3RdNf0qWSiBO" # CHANGE ME!
  RequireInvite = false
  AllowChoosingPlayerName = true

[[RegistrationOIDC]]
  Name = "LastLogin"
  Issuer = "https://lastlogin.net"                                  # CHANGE ME!
  ClientID = "https://drasl.example.com"                            # CHANGE ME!
  ClientSecret = ""                                                 # CHANGE ME!
  RequireInvite = false
  AllowChoosingPlayerName = true

Configurations for common fallback servers

When using fallback API servers for authentication ([[FallbackAPIServers]].EnableAuthentication):

• Set SignPublicKeys = false for compatibility with 1.21+.
• Minecraft servers must set enforce-secure-profile=false in server.properties.

Note for fallback servers implementing the authlib-injector API: you can usually get the AuthlibInjectorURL with curl --head https://example.com | grep x-authlib-injector-api-location.

Mojang

[[FallbackAPIServers]]
  Nickname = "Mojang"
  DiscoveryMinecraftClientURL = "https://discovery.minecraftservices.com/minecraft/client"
  SetSkinURL = "https://www.minecraft.net/msaprofile/mygames/editskin"

Ely.by

[[FallbackAPIServers]]
  Nickname = "Ely.by"
  AuthlibInjectorURL = "https://account.ely.by/api/authlib-injector"
  SetSkinURL = "https://ely.by/skins/add"

Blessing Skin

# For a Blessing Skin instance hosted at `skin.example.com`:

[[FallbackAPIServers]]
  Nickname = "Blessing Skin"
  AuthlibInjectorURL = "https://skin.example.com/api/yggdrasil"
  SetSkinURL = "https://skin.example.com/skinlib/upload"

LittleSkin

[[FallbackAPIServers]]
  Nickname = "LittleSkin"
  AuthlibInjectorURL = "https://littleskin.cn/api/yggdrasil"
  SetSkinURL = "https://littleskin.cn/skinlib/upload"

Drasl

[[FallbackAPIServers]]
  Nickname = "Fallback Drasl"
  AuthlibInjectorURL = "https://otherdrasl.example.com/authlib-injector"
  SetSkinURL = "https://otherdrasl.example.com/web/user"