From b909ba7f1557572ebb53c63d316a4887e7c43d52 Mon Sep 17 00:00:00 2001 From: Lucino772 Date: Wed, 15 Sep 2021 19:09:14 +0200 Subject: [PATCH] Added documentation --- README.md | 6 ++-- docs/account/auth_api.md | 4 +++ docs/account/auth_connect.md | 3 ++ docs/account/auth_security.md | 3 ++ docs/account/microsoft/auth_api.md | 10 +++++++ docs/account/microsoft/connect.md | 24 +++++++++++++++ docs/index.md | 1 + mkdocs.yml | 7 +++-- mojang/account/auth/microsoft.py | 29 +++++++++++++----- mojang/account/ext/microsoft.py | 47 +++++++++++++++++++++++++++++- 10 files changed, 121 insertions(+), 13 deletions(-) create mode 100644 docs/account/microsoft/auth_api.md create mode 100644 docs/account/microsoft/connect.md diff --git a/README.md b/README.md index 10946f9f..106fe439 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ -[![Documentation Status](https://readthedocs.org/projects/pymojang/badge/?version=latest)](https://pymojang.readthedocs.io/en/latest/?badge=latest) -![PyPI - Downloads](https://img.shields.io/pypi/dm/pymojang) -![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pymojang) +![Read the Docs](https://img.shields.io/readthedocs/pymojang?style=flat-square) +![PyPI - Downloads](https://img.shields.io/pypi/dm/pymojang?style=flat-square) +![PyPI - Python Version](https://img.shields.io/pypi/pyversions/pymojang?style=flat-square) # Pymojang Pymojang is a full wrapper arround de [Mojang API](https://wiki.vg/Mojang_API) and [Mojang Authentication API](https://wiki.vg/Authentication). diff --git a/docs/account/auth_api.md b/docs/account/auth_api.md index 2f1f0d6a..795bed43 100644 --- a/docs/account/auth_api.md +++ b/docs/account/auth_api.md @@ -1,4 +1,8 @@ +!!! note "Only Mojang Accounts" + The following functions only works for Mojang accounts, for Microsoft accounts + views [this](./microsoft/auth_api.md) + ::: mojang.account.auth.yggdrasil handler: python rendering: diff --git a/docs/account/auth_connect.md b/docs/account/auth_connect.md index 6d6e11ed..3293f2f2 100644 --- a/docs/account/auth_connect.md +++ b/docs/account/auth_connect.md @@ -2,6 +2,9 @@ Getting a user profile is great, but you can also connect to your account and re Both [`connect`][mojang.account.ext.session.connect] and [`UserSession`][mojang.account.ext.session.UserSession] use more low-level functions, you can view them in the following sections: [`Auth API`](./auth_api.md), [`Security API`](./auth_security.md) and [`Session API`](./auth_session.md). +!!! note "Microsoft Users" + The following function works for Mojang account, for Microsoft accounts view + [this](./microsoft/connect.md) ::: mojang.account.ext.session handler: python diff --git a/docs/account/auth_security.md b/docs/account/auth_security.md index 45e636be..4e552af7 100644 --- a/docs/account/auth_security.md +++ b/docs/account/auth_security.md @@ -1,4 +1,7 @@ +!!! note "Only Mojang Accounts" + The following functions only works for Mojang accounts + ::: mojang.account.auth.security handler: python rendering: diff --git a/docs/account/microsoft/auth_api.md b/docs/account/microsoft/auth_api.md new file mode 100644 index 00000000..b5bedfc7 --- /dev/null +++ b/docs/account/microsoft/auth_api.md @@ -0,0 +1,10 @@ + +!!! note "Only Microsoft Accounts" + The following functions only works for Microsoft accounts, for Mojang accounts + views [this](../auth_api.md) + +::: mojang.account.auth.microsoft + handler: python + rendering: + show_source: false + show_root_toc_entry: false \ No newline at end of file diff --git a/docs/account/microsoft/connect.md b/docs/account/microsoft/connect.md new file mode 100644 index 00000000..c331fcb7 --- /dev/null +++ b/docs/account/microsoft/connect.md @@ -0,0 +1,24 @@ +If you have a migrated account, you can't use the [`connect`][mojang.account.ext.session.connect] function. You will need to use the [`OAuth flow provided by Microsoft`](https://docs.microsoft.com/en-us/azure/active-directory/develop/v2-oauth2-auth-code-flow). + +To do so you will first need to create an [`Microsoft Azure App`](https://docs.microsoft.com/en-us/azure/active-directory/develop/quickstart-register-app) to get your **client id** and **client secret**. Once you have those credentials, you can call the [`microsoft_app`][mojang.account.ext.microsoft.microsoft_app] function with your credentials and it will create a [`MicrosotApp`][mojang.account.ext.microsoft.MicrosoftApp] for you. + +Now to authenticate a user, he will need to visit the [`authorization_url`][mojang.account.ext.microsoft.MicrosoftApp.authorization_url] and grant access to your app, he will then be redirected to an url with a **code** parameter. The value of this parameter can the be used when calling the function [`authenticate`][mojang.account.ext.microsoft.MicrosoftApp.authenticate] that will return the same [`UserSession`][mojang.account.ext.session.UserSession] object as the [`connect`][mojang.account.ext.session.connect] function. + + +::: mojang.account.ext.microsoft + handler: python + rendering: + show_source: false + show_root_toc_entry: false + selection: + members: + - microsoft_app + +::: mojang.account.ext.microsoft + handler: python + rendering: + show_source: false + show_root_toc_entry: false + selection: + members: + - MicrosoftApp diff --git a/docs/index.md b/docs/index.md index fbbceefe..b21b19e7 100644 --- a/docs/index.md +++ b/docs/index.md @@ -1,4 +1,5 @@ PyMojang is a full wrapper of the [Mojang API](https://wiki.vg/Mojang_API) and [Mojang Authentication API](https://wiki.vg/Authentication). +It also support the [Microsoft Authentication Scheme](https://wiki.vg/Microsoft_Authentication_Scheme). You can retrieve basic user information such as their ***uuid***, ***skin***, ***cape***,... diff --git a/mkdocs.yml b/mkdocs.yml index 48e924bf..33c75094 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -49,9 +49,12 @@ nav: - Check Status: 'check_status.md' - Account: - Retrieve user information: 'account/retrieve_user_info.md' - - Authenticated User: - - Connect: 'account/auth_connect.md' + - Authenticate: + - Mojang Account: 'account/auth_connect.md' + - Microsoft Account: 'account/microsoft/connect.md' + - API: - Auth API: 'account/auth_api.md' + - Microsoft Auth API: 'account/microsoft/auth_api.md' - Security API: 'account/auth_security.md' - Session API: 'account/auth_session.md' - Minecraft: diff --git a/mojang/account/auth/microsoft.py b/mojang/account/auth/microsoft.py index 91f7d71e..7dac58ea 100644 --- a/mojang/account/auth/microsoft.py +++ b/mojang/account/auth/microsoft.py @@ -1,3 +1,4 @@ +from typing import Tuple import requests from mojang.exceptions import * @@ -9,11 +10,12 @@ } -def authenticate_xbl(auth_token: str) -> tuple: - """Authenticate with Xbox Live +def authenticate_xbl(auth_token: str) -> Tuple[str, str]: + """Authenticate with Xbox Live using the Microsoft access token + received after the OAuth authentication Args: - auth_token (str): The access token received from the authentication with Microsoft + auth_token (str): The access token Returns: A tuple containing the Xbox Live token and user hash @@ -36,8 +38,8 @@ def authenticate_xbl(auth_token: str) -> tuple: data = handle_response(response, XboxLiveAuthenticationError) return data['Token'], data['DisplayClaims']['xui'][0]['uhs'] -def authenticate_xsts(xbl_token: str) -> tuple: - """Retrieve the XSTS Token +def authenticate_xsts(xbl_token: str) -> Tuple[str, str]: + """Retrieve the XSTS Token using the Xbox Live token Args: xbl_token (str): The Xbox Live token @@ -62,8 +64,9 @@ def authenticate_xsts(xbl_token: str) -> tuple: data = handle_response(response, XboxLiveAuthenticationError) return data['Token'], data['DisplayClaims']['xui'][0]['uhs'] -def authenticate_minecraft(userhash: str, xsts_token: str): - """Login to minecraft using Xbox Live +def authenticate_minecraft(userhash: str, xsts_token: str) -> str: + """Retrieve the Minecraft access token loging in using Xbox Live + Args: user_hash (str): The user hash from Xbox Live xbl_token (str): The XSTS Token from Xbox Live @@ -74,6 +77,18 @@ def authenticate_minecraft(userhash: str, xsts_token: str): Raises: XboxLiveInvalidUserHash: If the user hash is invalid Unauthorized: If the XSTS token is invalid + + Example: + + ```python + from mojang.account.auth import microsoft + + ACCESS_TOKEN = '....' # Access token from Microsoft + + xbl_token, _ = microsoft.authenticate_xbl(ACCESS_TOKEN) + xsts_token, userhash = microsoft.authenticate_xsts(xbl_token) + mc_access_token = microsoft.authenticate_minecraft(userhash, xsts_token) + ``` """ data = {"identityToken": f"XBL3.0 x={userhash};{xsts_token}"} diff --git a/mojang/account/ext/microsoft.py b/mojang/account/ext/microsoft.py index 0d2884e9..fe1a05b3 100644 --- a/mojang/account/ext/microsoft.py +++ b/mojang/account/ext/microsoft.py @@ -5,21 +5,66 @@ _DEFAULT_SCOPES = ['XboxLive.signin'] -def microsoft_app(client_id: str, client_secret: str, redirect_uri: str = 'http://example.com'): +def microsoft_app(client_id: str, client_secret: str, redirect_uri: str = 'http://example.com') -> 'MicrosoftApp': + """It create an instance of [`MicrosoftApp`][mojang.account.ext.microsoft.MicrosoftApp] with the client id and client secret. + This app can then be used to get a [`UserSession`][mojang.account.ext.session.UserSession] like + [`connect`][mojang.account.ext.session.connect] for Microsoft users. + + Args: + client_id (str): Your Azure App client id + client_secret (str): Your Azure App client secret + redirect_uri (str, optional): The default redirect uri for your app + + Returns: + An instance of the MicrosoftApp + + Examples: + + ```python + import mojang + + CLIENT_ID = ... # Your Azure App client id + CLIENT_SECRET = ... # Your Azure App client secret + + app = mojang.microsoft_app(CLIENT_ID, CLIENT_SECRET) + + # To authenticate users, you first need them to visit the url + # returned by the function `app.authorization_url` + url = app.authorization_url() + + # Once they will have granted access to their account to your app, + # they will be redirect to the uri you choose with a `code` parameter + # http://example.com?code=... + # You can use this code to authenticate the user + code = ... + user = app.authenticate(code) + ``` + """ client = msal.ClientApplication(client_id, client_credential=client_secret, authority='https://login.microsoftonline.com/consumers') return MicrosoftApp(client, redirect_uri) class MicrosoftApp: + """This class allows you to authenticate Microsoft users to Minecraft""" def __init__(self, client: msal.ClientApplication, redirect_uri: str): self.__client = client self.__redirect_uri = redirect_uri def authorization_url(self, redirect_uri: str = None) -> str: + """Returns the authorization url for Microsfot OAuth""" return self.__client.get_authorization_request_url(scopes=_DEFAULT_SCOPES, redirect_uri=(redirect_uri or self.__redirect_uri)) def authenticate(self, auth_code: str, redirect_uri: str = None) -> 'UserSession': + """Authenticate a user with the auth code + + Args: + auth_code (str): The auth code from the redirect + redirect_uri (str, optional): The redirect uri for your app + + Returns: + An instance of UserSession + """ response = self.__client.acquire_token_by_authorization_code(auth_code, scopes=_DEFAULT_SCOPES, redirect_uri=(redirect_uri or self.__redirect_uri)) xbl_token, userhash = microsoft.authenticate_xbl(response['access_token']) xsts_token, userhash = microsoft.authenticate_xsts(xbl_token)