Ahwoo.SessionTickets.Client 1.0.0

Ahwoo.SessionTickets.Client

Use this package to identify the Ahwoo account that a player of your game is signed in to.

The player signs in once in the Ahwoo desktop client, a separate Windows application. Your game asks that client for a session ticket, a short-lived signed assertion of the player's identity. Your game then sends the ticket to your game server, which verifies it with Ahwoo.SessionTickets.Server and reads the player's Ahwoo profile ID. Your game shows no sign-in screen of its own.

This package is the game side of that exchange. It has no third-party dependencies.

dotnet add package Ahwoo.SessionTickets.Client

How the exchange works

1. The player's game connects to your game server. Your game server generates a nonce, a single-use random challenge value, and sends it to the game.
2. Your game calls this package, which asks the Ahwoo desktop client on the player's computer to mint a ticket bound to that nonce.
3. The Ahwoo desktop client returns the ticket to your game. Your game sends the ticket to your game server over your game's own network connection. Ahwoo provides no transport for this step.
4. Your game server verifies the ticket with Ahwoo.SessionTickets.Server and reads the player's Ahwoo profile ID.

Minting a ticket

using Ahwoo.SessionTickets.Client;
using Ahwoo.SessionTickets.Client.Models;

// Create one minter per process and keep it for the lifetime of the process.
private readonly SessionTicketMinter _ahwoo = new();

// Call this per connection attempt, with the nonce your game server sent.
async Task JoinAsync(string nonce, CancellationToken cancellationToken)
{
    if (!_ahwoo.IsAhwooClientRunning)
    {
        ShowAhwooClientRequired();
        return;
    }

    SessionTicket ticket = await _ahwoo.MintAsync(nonce, cancellationToken);
    SendToServer(ticket.Token);
}

IsAhwooClientRunning reports whether the Ahwoo desktop client is running on the player's computer. Check this property before your game attempts to connect. Your game can then ask the player to start the Ahwoo desktop client, or fall back to another identity system.

A ticket expires about 120 seconds after your game mints it, and it is bound to one nonce. Mint a ticket for each connection attempt. Do not mint at startup, and do not cache a ticket.

When minting fails

The exceptions below live in Ahwoo.SessionTickets.Client.Exceptions and derive from SessionTicketException. Catch SessionTicketException to handle every minting failure the same way, such as to abandon the connection attempt.

Configuration

This package requires no configuration.

var minter = new SessionTicketMinter(new SessionTicketMinterOptions { Timeout = TimeSpan.FromSeconds(10) });

The constructor also accepts an HttpClient if your game manages its own. Use the ISessionTicketMinter interface to substitute the minter in your own tests.

How discovery works

The Ahwoo desktop client writes a discovery file while it runs, and deletes the file when it exits. The file names a loopback URL and a secret that the Ahwoo desktop client generates fresh on each run. The minter reads the file from the per-user local application data folder. On Windows, the default path is %LOCALAPPDATA%\Ahwoo\Client\broker.json. Set the DiscoveryFilePath option to read the file from another path.

The minter reads the discovery file on every mint. Your game therefore keeps working when the player restarts the Ahwoo desktop client or switches Ahwoo account. Neither case needs extra code in your game.

Trust boundary

The player's Ahwoo access token stays inside the Ahwoo desktop client and never enters your game process. Your game holds only a session ticket, which grants no access to Ahwoo's APIs.

Any process that runs as the desktop user can read the discovery file and mint a ticket. This is intentional. The operating system user account is the trust boundary, the same boundary that Steam and Discord use for their local inter-process channels. Such a process can already read the credentials that the Ahwoo desktop client stores. A session ticket lasts about 120 seconds and opens no Ahwoo API. It grants such a process no capability that the process does not already have.

Support

Email contact@ahwoo.com with questions or bug reports.