Authentication

Summary

This tutorial demonstrates how to send authentication arguments to the server when you connect, how an OnAuthenticate handler can be registered on the server to authenticate connecting players, and how to send arbitrary data back to the client in the server's authentication response. In this tutorial a random number is sent to players when they pass authentication, and an error message is sent when they fail. Clients will pass or fail authentication depending on which button they press to connect.

Requirements

• Reactor Requirements

• Completion of Tutorial 1

Setup

Create a Room

1. Right click in the hierarachy window and create a 'Reactor/Room' game object.

2. Uncheck the 'Connect On Start' checkbox in the ksConnect inspector. This will prevent the script from connecting automatically when the scene is loaded. We will instead create a script to connect when a button is pressed.

Scripting

First we will create a client script to connect when a button is pressed, and handle authentication respones. Then we will create a* server room script to handle player authentication.

Create a ConnectHandler Monobehaviour

This script has event handlers for the ksConnect component's OnGetRooms and OnConnect events. It will attempt to connect to the server when the users presses one of the '0'-'2' keys, and disconnect when 'd' is pressed. The OnGetRooms event allows developers to control which room the client connects to and pass optional authentication arguments to the server. This version of the script connects to the first room available and passes a different argument depending on which number key was pressed. The OnConnect event is fired when a connection attempt completes, even if the connection was not successful, allowing you to handle connection errors. This script logs value of the first optional ksMultiType the server authentication handler returned in ksAuthenticationResult.Data if the connection was succesful, and otherwise logs a connection failure warning depending on the ksAuthenticationResult.Code returned by the authentication handler.

Just like RPCs, the Connect method can take any number of optional ksMultiType arguments. These arguments are passed to any Room.OnAuthenticate handler functions in server room scripts.

1. Create a new MonoBehaviour named 'ConnectHandler'.

2. Attach it to the 'Room' game object.

3. Edit the file to match the code below.

4. Select the ksConnect component on the room and add the 'ConnectHandler' 'OnGetRooms' method to the ksConnect 'OnGetRooms' event list.

   • Click the '+' button in ksConnect 'OnGetRooms' event list.

   • Drag the Room instance into the new object field.

   • Select 'ConnectHandler->OnGetRooms' in the function selector.

5. Add the 'ConnectHandler' 'OnConnect' method to the ksCOnnect 'OnConnect' event list.

ConnectHandler.cs

using UnityEngine;
using KS.Reactor.Client.Unity;
using KS.Reactor.Client;
using KS.Reactor;

public class ConnectHandler : MonoBehaviour
{
    private int m_connectArg;

    // Connect with a different authentication argument when 0-2 are pressed, and disconnect when D is pressed.
    private void Update()
    {
        if (Input.GetKeyDown(KeyCode.Alpha0))
        {
            Connect(0);
        }
        else if (Input.GetKeyDown(KeyCode.Alpha1))
        {
            Connect(1);
        }
        else if (Input.GetKeyDown(KeyCode.Alpha2))
        {
            Connect(2);
        }
        else if (Input.GetKeyDown(KeyCode.D))
        {
            // This will disconnect from all connected rooms.
            ksReactor.Service.Disconnect();
        }
    }

    private void Connect(int connectArg)
    {
        // Store the connect arg so we can connect with it from OnGetRooms.
        m_connectArg = connectArg;

        // Begin the connection process the ksConnect compone is configured for (local, online, or remote).
        GetComponent<ksConnect>().BeginConnect();
    }

    // Handler for ksConnect.OnGetRooms events.
    public void OnGetRooms(ksConnect.GetRoomsEvent e)
    {
        if (e.Status != ksBaseRoom.ConnectStatus.SUCCESS)
        {
            ksLog.Error(this, "Error fetching rooms: " + e.Error);
        }
        else if (e.Rooms == null || e.Rooms.Count == 0)
        {
            ksLog.Warning(this, "No rooms found.");
        }
        else
        {
            // The caller is the ksConnect script instance which invoked this event handler.
            // Connect with the connect arg, unless it is 0, then connect with no arguments.
            if (m_connectArg == 0)
            {
                e.Caller.Connect(e.Rooms[0]);
            }
            else
            {
                e.Caller.Connect(e.Rooms[0], m_connectArg);
            }
        }
    }

    // Handler for ksConnect.OnConnect events.
    public void OnConnect(ksConnect.ConnectEvent e)
    {
        if (e.Status == ksBaseRoom.ConnectStatus.SUCCESS)
        {
            // We connected successfully. Log the first value in Result.Data the server sent, if any.
            if (e.Result.Data.Length > 0)
            {
                ksLog.Info("Connected. Server sent result value " + e.Result.Data[0]);
            }
            else
            {
                ksLog.Info("Connected. Server did not send any result data.");
            }
        }
        // The first constructor parameter of ksAuthenticationResult can be accessed from e.Result.Code. If it is 1,
        // we log a warning that the number of authentication arguments was wrong.
        else if (e.Result.Code == 1)
        {
            ksLog.Warning(this, "Authentication failed: wrong number of authentication arguments.");
        }
        // We don't log other connection errors because the ksConnect component already logs connection errors.
    }
}

Create a Server Authentication Room Script

The server room script registers a Room.OnAuhthenticate handler that passes authentication if it was called with a single argument with the value 1. It sends a random number in the ksAuthenticationResult.Data to players who pass authentication. If the wrong number of arugments were sent, it fails authentication with ksAuthenticationResult.Code 1, and if any argument value other than 1 was sent, it fails with ksAuthenticationResult.Code 2 and sends an error message in the ksAuthenticationResult.Data.

Authentication handlers are async methods that return a Task, so you can await external asynchronous authentication calls. For more information, see here. Authentication handlers cannot be added or removed after the room is loaded and Initialize is called on the initial scripts.

The ksAsyncResult constructor takes a uint code parameter and an optional number of ksMultiTypes. Authentication fails if the uint code is non-zero. The ksAsyncResult is sent to the client and can be accessed in the Room.OnConnect event. The code and ksMultiTypes are logged by the ksConnect script when authentication fails. If there are multiple authentication handler functions and authentication fails, the ksAsyncResult sent to the client will be from the first authentication function that failed. If all authentication functions pass, the ksMultiType arguments from all authentication functions are combined into one array and sent to the client.

It is possible that OnPlayerJoin and OnPlayerLeave events may not fire for a player who passes authentication if they disconnect during the authentication process. You should not set any persistent state in an authentication handler such as user-login state tracking and rely on 'OnPlayerLeave' to clear that state.

1. Select the 'Room' object.

2. In the 'Add Component' menu, select 'Reactor->New Server Room Script'.

3. Name the script 'ServerAuthenticationRoom'.

ServerAuthenticationRoom.cs

using System.Threading;
using System.Threading.Tasks;
using KS.Reactor.Server;
using KS.Reactor;

public class ServerAuthenticatorRoom : ksServerRoomScript
{
    private ksRandom m_rand = new ksRandom();

    // Called after all other scripts on all entities are attached.
    public override void Initialize()
    {
        Room.OnAuthenticate += Authenticate;
    }
    
    // Called when the script is detached.
    public override void Detached()
    {
        Room.OnAuthenticate -= Authenticate;
    }
    
    
    // Authenticates a player. Return a non-zero result to fail authentication.
    private async Task<ksAuthenticationResult> Authenticate(ksIServerPlayer player, ksMultiType[] args, CancellationToken cancellationToken)
    {
        // args contains the arguments we passed to ksRoom.Connect().
        if (args.Length != 1)
        {
            return new ksAuthenticationResult(1);
        }
        if (args[0] == 1)
        {
            // Pass authentication immediately if the argument is 1, and return a random integer in the result data.
            return new ksAuthenticationResult(0, m_rand.Next());
        }
        // Fail authentication with an error message in the result data for all other argument values.
        // We await a completed Task to prevent a compiler warning that the async method never awaits anything and
        // will be completed synchronously.
        return await Task.FromResult(new ksAuthenticationResult(2, "Unknown auth arg: " + args[0]));
    }
}

Testing

1. Build your scene config (CTRL + F2).

2. Start a local server.

3. Enter play mode.

4. Press 1. You should see a message in the Unity logs "Connected. Server sent result value X" where X is a random number.

5. Press 2. You should get a ROOM_INITIALIZE_ERROR connection failure warning. This happens when you try to connect to the same room twice.

6. Press D to disconnect.

7. Press 2. You should get a connection failure warning with "AUTH_ERR_USER_DEFINED (code: 2, data: [Unknown auth arg: 2])"`.

8. Press 0. You should get a warning "Authentication failed: wrong number of authentication arguments."