{"id":16374356,"url":"https://github.com/raphimc/minecraftauth","last_synced_at":"2025-03-21T01:32:01.497Z","repository":{"id":144935090,"uuid":"585325637","full_name":"RaphiMC/MinecraftAuth","owner":"RaphiMC","description":"Simple and easy to use Minecraft microsoft authentication library (Java and Bedrock)","archived":false,"fork":false,"pushed_at":"2024-03-23T12:28:13.000Z","size":481,"stargazers_count":35,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-03-23T13:39:19.268Z","etag":null,"topics":["authentication","microsoft-authentication","minecraft","minecraft-account","minecraft-authentication","minecraft-bedrock","minecraft-java","minecraft-login","xbox-live-api","xbox-live-oauth"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"lgpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/RaphiMC.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null},"funding":{"ko_fi":"rk_01"}},"created_at":"2023-01-04T22:13:12.000Z","updated_at":"2024-03-23T13:39:27.483Z","dependencies_parsed_at":"2023-10-15T10:57:27.028Z","dependency_job_id":"4ab988cd-16f3-4581-aa50-31b9c38bb924","html_url":"https://github.com/RaphiMC/MinecraftAuth","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaphiMC%2FMinecraftAuth","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaphiMC%2FMinecraftAuth/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaphiMC%2FMinecraftAuth/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/RaphiMC%2FMinecraftAuth/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/RaphiMC","download_url":"https://codeload.github.com/RaphiMC/MinecraftAuth/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244097197,"owners_count":20397562,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["authentication","microsoft-authentication","minecraft","minecraft-account","minecraft-authentication","minecraft-bedrock","minecraft-java","minecraft-login","xbox-live-api","xbox-live-oauth"],"created_at":"2024-10-11T03:16:59.592Z","updated_at":"2025-03-21T01:32:01.127Z","avatar_url":"https://github.com/RaphiMC.png","language":"Java","readme":"# MinecraftAuth\nSimple and easy to use Minecraft microsoft authentication library (Java and Bedrock).\n\n## Features\n- Full support for Minecraft: Java Edition and Minecraft: Bedrock Edition\n- Basic support for Minecraft: Education Edition\n- Login using device code, credentials, a JavaFX WebView window or a local webserver\n- Refreshing and validating token chains\n- Serializing and deserializing token chains to and from json\n- Customizable login flows (Client ID, scopes, ...)\n- Basic implementation of the Minecraft Realms API (Allows listing and joining realms)\n\n## Releases\n### Gradle/Maven\nTo use MinecraftAuth with Gradle/Maven you can get it from [Maven Central](https://mvnrepository.com/artifact/net.raphimc/MinecraftAuth), [Lenni0451's Maven](https://maven.lenni0451.net/#/releases/net/raphimc/MinecraftAuth) or [Jitpack](https://jitpack.io/#RaphiMC/MinecraftAuth).\nYou can also find instructions how to implement it into your build script there.\n\n### Jar File\nIf you just want the latest jar file you can download it from [GitHub Actions](https://github.com/RaphiMC/MinecraftAuth/actions/workflows/build.yml) or [Lenni0451's Jenkins](https://build.lenni0451.net/job/MinecraftAuth/).\n\n## Usage\nMinecraftAuth provides most of its functionality through the ``MinecraftAuth`` class.\nIt contains predefined login flows for Minecraft: Java Edition and Minecraft: Bedrock Edition using the official client ids and scopes.\n\nTo customize/configure a login flow in order to change application details (like client id, scope or client secret) or to use alternative login ways (like JavaFX WebView window or local webserver) you can use the ``MinecraftAuth.builder()`` method.\nFor examples, you can look at the predefined login flows in the ``MinecraftAuth`` class.\n\nHere is an example of how to manage a Minecraft: Java Edition account (For Minecraft: Bedrock Edition you can use pretty much the same code, but replace ``Java`` with ``Bedrock``):\n### Log in using device code (Recommended)\nThe device code auth flow blocks the thread until the user has logged in and throws an exception if the process times out.\nThe timeout is 120 seconds by default.\n```java\nHttpClient httpClient = MinecraftAuth.createHttpClient();\nStepFullJavaSession.FullJavaSession javaSession = MinecraftAuth.JAVA_DEVICE_CODE_LOGIN.getFromInput(httpClient, new StepMsaDeviceCode.MsaDeviceCodeCallback(msaDeviceCode -\u003e {\n    // Method to generate a verification URL and a code for the user to enter on that page\n    System.out.println(\"Go to \" + msaDeviceCode.getVerificationUri());\n    System.out.println(\"Enter code \" + msaDeviceCode.getUserCode());\n\n    // There is also a method to generate a direct URL without needing the user to enter a code\n    System.out.println(\"Go to \" + msaDeviceCode.getDirectVerificationUri());\n}));\nSystem.out.println(\"Username: \" + javaSession.getMcProfile().getName());\nSystem.out.println(\"Access token: \" + javaSession.getMcProfile().getMcToken().getAccessToken());\nSystem.out.println(\"Player certificates: \" + javaSession.getPlayerCertificates());\n```\n### Log in using credentials\nThe credentials auth flow does not handle 2FA and will throw an exception if the user has 2FA enabled. You should consider using the device code auth flow instead if you want to support 2FA.\n```java\nHttpClient httpClient = MinecraftAuth.createHttpClient();\nStepFullJavaSession.FullJavaSession javaSession = MinecraftAuth.JAVA_CREDENTIALS_LOGIN.getFromInput(httpClient, new StepCredentialsMsaCode.MsaCredentials(\"email@test.com\", \"P4ssw0rd\"));\nSystem.out.println(\"Username: \" + javaSession.getMcProfile().getName());\nSystem.out.println(\"Access token: \" + javaSession.getMcProfile().getMcToken().getAccessToken());\nSystem.out.println(\"Player certificates: \" + javaSession.getPlayerCertificates());\n```\n### Save the token chain to a json object\n```java\nJsonObject serializedSession = MinecraftAuth.JAVA_DEVICE_CODE_LOGIN.toJson(javaSession);\n```\n### Load the token chain from a json object\n```java\nStepFullJavaSession.FullJavaSession loadedSession = MinecraftAuth.JAVA_DEVICE_CODE_LOGIN.fromJson(serializedSession);\n```\n### Refresh the token chain\nMinecraftAuth implements a refresh method that only refreshes the tokens that are expired and reuses the valid ones.\nYou can call this everytime before you access/use the token chain to make sure it is valid. (Don't spam it though or else you will be rate limited by Microsoft)\nThis method will throw an exception if the refresh fails (The initial refresh token is no longer valid and the user has to login again).\n```java\nStepFullJavaSession.FullJavaSession readyToUseSession = MinecraftAuth.JAVA_DEVICE_CODE_LOGIN.refresh(httpClient, loadedSession);\n```\n### Minecraft Realms API\nMinecraftAuth provides a basic implementation of the Minecraft Realms API. It supports listing and joining the realms of an user.  \nThe Realms API requires you to provide the latest supported client version of your application.\nYou should hardcode this value instead of loading it from the Internet, as the Realms API will not work if your application can't handle the specified version.\n#### Java Edition\n```java\nJavaRealmsService javaRealmsService = new JavaRealmsService(httpClient, \"latestSupportedClientVersionHere\", javaSession.getMcProfile());\nboolean isAvailable = javaRealmsService.isAvailable().join();\nif (!isAvailable) {\n    System.out.println(\"The client version does not support Realms\");\n} else {\n    System.out.println(\"Your client supports Realms\");\n    List\u003cRealmsWorld\u003e realmsWorlds = javaRealmsService.getWorlds().join();\n    System.out.println(\"Realms worlds: \" + realmsWorlds);\n    try {\n        System.out.println(\"Connect to: \" + javaRealmsService.joinWorld(realmsWorlds.get(0)).join());\n    } catch (CompletionException e) {\n        if (e.getCause() instanceof RealmsRequestException) {\n            RealmsRequestException exception = (RealmsRequestException) e.getCause();\n            if (exception.getErrorCode() == RealmsRequestException.TOS_NOT_ACCEPTED) {\n                // The Java Edition Realms API requires users to accept the Minecraft Realms Terms of Service (https://aka.ms/MinecraftRealmsTerms)\n                // You should display the terms to the user and ask them to accept them:\n                javaRealmsService.acceptTos().join();\n                // If they accept, then you can try to join the world again\n            }\n        }\n    }\n}\n```\n#### Bedrock Edition\n**If you need Minecraft: Bedrock Edition Realms support, you have to make a custom auth flow with the realms boolean set to true when calling the buildMinecraftBedrockChainStep() method.**\n```java\nBedrockRealmsService bedrockRealmsService = new BedrockRealmsService(httpClient, \"latestSupportedClientVersionHere\", bedrockSession.getRealmsXsts());\nboolean isAvailable = bedrockRealmsService.isAvailable().join();\nif (!isAvailable) {\n    System.out.println(\"The client version does not support Realms\");\n} else {\n    System.out.println(\"Your client supports Realms\");\n    List\u003cRealmsWorld\u003e realmsWorlds = bedrockRealmsService.getWorlds().join();\n    System.out.println(\"Realms worlds: \" + realmsWorlds);\n    System.out.println(\"Connect to: \" + bedrockRealmsService.joinWorld(realmsWorlds.get(0)).join());\n}\n```\n[Here is an example implementation](https://github.com/ViaVersion/ViaProxy/blob/09e685fad9ee1b804a3b01a7eb308a444a48855f/src/main/java/net/raphimc/viaproxy/ui/impl/RealmsTab.java) which is using the Realms API of both Minecraft editions.\n\n### Logging\nMinecraftAuth by default uses SLF4J for logging.\nYou can however easily redirect the log messages to your own code by setting ``MinecraftAuth.LOGGER`` to your own ``ILogger``.\n\n## Contact\nIf you encounter any issues, please report them on the\n[issue tracker](https://github.com/RaphiMC/MinecraftAuth/issues).  \nIf you just want to talk or need help implementing MinecraftAuth feel free to join my\n[Discord](https://discord.gg/dCzT9XHEWu).\n","funding_links":["https://ko-fi.com/rk_01"],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphimc%2Fminecraftauth","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fraphimc%2Fminecraftauth","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fraphimc%2Fminecraftauth/lists"}