Authorization protocols

When using Xasu with an LRS it is possible to use three different authorization protocols: Basic, OAuth (v1) and OAuth2. Each of the protocols have different configurations and may support multiple flows for different use cases. Each of these protocols will manipulate the requests made by Xazu to include the appropiate parameters (headers, query parameters, signatures, etc.) in the request to authorize it.

For OAuth1 and some OAuth2 flows to work the game will prompt login windows and listen for the redirection at localhost:. However, in WebGL, the website containing the game will be redirected to the SSO (Single-Sign-On) when the tracker initialization is started. Make sure you initialize Xasu at the start of your game or that you save the game state before initializing Xasu to prevent losing the player unsaved progress in WebGL scenarios.

To continue the login process after the SSO returns back to the game just do the Initialization again and, if the SSO return parameters are detected, Xasu will continue with the rest of the process.

Details on each authorization protocol configuration can be found ahead.

Architecture of authorization protocols

To identify, create and configure the authorization protocols, Xasu uses the AuthorizationManager to initialize authorizations based on a key and a set of parameters. After being selected by its key name each protocol manages its own initialization asynchronously. Some protocols may need to redirect or to perform several requests to the authorization servers. For cases when the authorization protocol requires to listen for a response, the AuthUtility is used to listen for a callback by passing an object implementing IAuthListener class.

Once the authorization protocol is configured, the processors will use the UpdateParamsForAuth method to setup the headers and parameters required to authorize the request that is going to be performed.

No Authorization

Using the "none" auth protocol, Xasu will send the traces using no bearer at all. This mode can be used for testing purposes but it is discouraged in production.

    "auth_protocol": "none"

Basic Authorization

The Basic authorization provides HTTP Authorization using username and password. This information is encoded and added in the "Authorization" header of every request. Here's an example of the Basic protocol configuration:

    "auth_protocol": "basic",
    "auth_parameters": {
        "username": "<your-username>",
        "password": "<your-password>"
    }

To authenticate the user using credentials obtained from the user you will need to introduce these settings using the alternative configuration setup.

OAuth 1.0

The OAuth1.0 authorization is the other alternative recommended in the LRS specification. This protocol requires the user to introduce its credentials in a single-sign-on (SSO) website and forward the authorization to the game. Here's an example of the OAuth1.0 protocol configuration:

    "auth_protocol": "oauth",
    "auth_parameters": {
        "request_token_endpoint": "<request-token-endpoint>", // AKA "initiate" endpoint
        "authorize_endpoint": "<authorize-endpoint>",
        "access_token_endpoint": "<access-token-endpoint>",
        "oauth_consumer_key": "<your-consumer-key>",
        "oauth_consumer_secret": "<your-consumer-secret>",
        "oauth_signature_method": "RSA-SHA1"  // PLAINTEXT is also supported
    }

OAuth 2.0

Althought OAuth2.0 is not yet officially supported in the LRS specification, OAuth2.0 is the most secure and flexible authorization protocol and we encourage using it when available.

Xasu supports both "code" (AKA client) flow, "password" (AKA Resource Owned Password Credentials) flow, and the "refresh-token" flow.

Client "code" flow with PKCE

The "code" flow is the OAuth2.0 flow used in client applications, where the configuration is included inside of the final product. Although it is possible to use the client secret, we discourage it as it could be readed or decompiled from the final product. Xasu also supports (and encourages) the use of PKCE in the client flow to guarantee the authorization is safe.

Here's an example of the OAuth2.0 protocol configuration with PKCE enabled.

    "auth_protocol": "oauth2",
    "auth_parameters": {
        "grant_type": "code",
        "auth_endpoint": "<your-authorize-endpoint>", // AKA /auth
        "token_endpoint": "<your-token-endpoint>", // AKA /token
        "client_id": "<your-client-id>",
        "code_challenge_method": "S256" // PKCE code challenge
    },

Resource Owned Password Credentials "password" flow (ROPC)

The "password" flow is the OAuth2.0 flow used when the client can safely manipulate the user credentials. However, this method is discouraged and may be deprecated in the future. This method is appropiate for testing purposes. Since this authorizationmethod avoids prompting SSO pages it can be helpful when the web browser is not accessible.

    "auth_protocol": "oauth2",
    "auth_parameters": {
        "grant_type": "password",
        "token_endpoint": "<your-token-endpoint>", // AKA /token
        "client_id": "<your-client-id>",
        "username": "<your-username>",
        "password": "<your-password>"
    },

To authenticate the user using credentials obtained from the user (in gameplay time) you will need to introduce these settings using the alternative configuration setup.