auth

Documentation

Overview

Package auth implements authentication to Microsoft accounts and XBOX Live accounts. It does so in a couple of steps, the first of which being authentication to the Live account to obtain a Live token, so that authentication to the XBOX Live account may be initiated.

The auth package currently does not handle 2FA accounts. Trying to authenticate to an account with 2FA enabled will result in undefined behaviour.

Index

• func RequestMinecraftChain(token *XSTSToken, key *ecdsa.PrivateKey) (string, error)
• type DeviceToken
• type TitleToken
• type TokenPair
  • func NewTokenPair(access, refresh string, expiryTime time.Duration) *TokenPair
  • func RequestLiveToken(login, password string) (*TokenPair, error)
  • func (token *TokenPair) AccessToken() string
  • func (token *TokenPair) Refresh() error
  • func (token *TokenPair) RefreshToken() string
  • func (token *TokenPair) Valid() bool
  • func (token *TokenPair) ValidOrRefresh() error
• type UserToken
• type XSTSToken
  • func RequestXSTSToken(liveToken *TokenPair) (*XSTSToken, error)
  • func RequestXSTSTokenUserOnly(liveToken *TokenPair) (*XSTSToken, error)

Functions

func RequestMinecraftChain

func RequestMinecraftChain(token *XSTSToken, key *ecdsa.PrivateKey) (string, error)

RequestMinecraftChain requests a fully processed Minecraft JWT chain using the XSTS token passed, and the ECDSA private key of the client. This key will later be used to initialise encryption, and must be saved for when packets need to be decrypted/encrypted.

Types

type DeviceToken

type DeviceToken struct {
	IssueInstant  string
	NotAfter      string
	Token         string
	DisplayClaims struct {
		XDI struct {
			DID string `json:"did"`
		} `json:"xdi"`
	}
}

DeviceToken is the token obtained by requesting a device token by posting to xblDeviceAuthURL. Its Token field may be used in a request to obtain the XSTS token.

type TitleToken

type TitleToken struct {
	IssueInstant  string
	NotAfter      string
	Token         string
	DisplayClaims struct {
		XTI struct {
			TID string `json:"tid"`
		} `json:"xti"`
	}
}

TitleToken is the token obtained by requesting a title token by posting to xblTitleAuthURL. Its Token field may be used in a request to obtain the XSTS token.

type TokenPair

type TokenPair struct {
	// contains filtered or unexported fields
}

TokenPair holds a pair of an access token and a refresh token, which may be used to refresh the access token. It also holds an expiry time to keep track of the time at which a new access token must be requested.

func NewTokenPair

func NewTokenPair(access, refresh string, expiryTime time.Duration) *TokenPair

NewTokenPair returns a new token pair using an access and refresh token, and their expiry time.

func RequestLiveToken

func RequestLiveToken(login, password string) (*TokenPair, error)

RequestLiveToken does a login request for Microsoft Live using the login and password passed. If successful, a token containing the access token, refresh token, expiry and user ID is returned.

func (*TokenPair) AccessToken

func (token *TokenPair) AccessToken() string

AccessToken returns the access token of the token pair.

func (*TokenPair) Refresh

func (token *TokenPair) Refresh() error

Refresh refreshes the access token of the pair, using the refresh token to refresh it. The access token is refreshed when calling this, regardless of the expiry time. If successful, the token pair's access and refresh tokens are updated.

func (*TokenPair) RefreshToken

func (token *TokenPair) RefreshToken() string

RefreshToken returns the refresh token of the token pair.

func (*TokenPair) Valid

func (token *TokenPair) Valid() bool

Valid checks if the access token is currently valid, meaning the expiry time has not yet passed.

func (*TokenPair) ValidOrRefresh

func (token *TokenPair) ValidOrRefresh() error

ValidOrRefresh checks if the token pair is currently valid, and if it isn't, refreshes it. It is equivalent to calling TokenPair.Valid() and TokenPair.Refresh() if it isn't.

type UserToken

type UserToken struct {
	IssueInstant  string
	NotAfter      string
	Token         string
	DisplayClaims struct {
		XUI []struct {
			UHS string `json:"uhs"`
		} `json:"xui"`
	}
}

UserToken is the token obtained by requesting a user token by posting to xblUserAuthURL. Its Token field must be used in a request to the XSTS token.

type XSTSToken

type XSTSToken struct {
	IssueInstant  string
	NotAfter      string
	Token         string
	DisplayClaims struct {
		XUI []struct {
			AgeGroup   string `json:"agg"`
			GamerTag   string `json:"gtg"`
			Privileges string `json:"prv"`
			XUID       string `json:"xid"`
			UserHash   string `json:"uhs"`
		} `json:"xui"`
	}
}

XSTSToken is the token obtained by requesting an XSTS token from xblAuthorizeURL. It may be obtained using any of the tokens above, and is required for authenticating with Minecraft. Its Token and UserHash field in particular are used.

func RequestXSTSToken

func RequestXSTSToken(liveToken *TokenPair) (*XSTSToken, error)

RequestXSTSToken requests an XSTS token using the passed Live token pair. The token pair must be valid when passed in. RequestXSTSToken will not attempt to refresh the token pair if it not valid. RequestXSTSToken obtains the XSTS token by using the UserToken, DeviceToken and TitleToken. It appears only one of these tokens is actually required to produce an XSTS token valid to authenticate with Minecraft.

func RequestXSTSTokenUserOnly

func RequestXSTSTokenUserOnly(liveToken *TokenPair) (*XSTSToken, error)

RequestXSTSTokenUserOnly requests an XSTS token using the Live token pair passed. RequestXSTSTokenUserOnly returns an error if the live token is no longer valid, and must be refreshed. RequestXSTSTokenUserOnly, unlike RequestXSTSToken, requests an XSTS token using only a User token obtained using the Live token pair.