Added documentation

Author: Lucino772

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).

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:

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

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:

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

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

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***,...
 

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:

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}"}

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)