Authentication #

Pragma Engine provides dedicated gateways for different session types.

Each gateway supports its own authentication endpoint. An identity provider token is passed to Pragma Engine, then the provider token is validated and exchanged for a Pragma session token.

The session tokens are signed by a jwtPrivateKey that is configured in the TokenSignerConfig object. The pragmaGameToken can be used to connect to a game server with matching gameShardId (embedded in the JWT A standard for securely transmitting information as a JSON object. payload and configured on the game server) and the pragmaSocialToken can be used to connect to a social server.

Complete authentication tutorials are available for both Unreal and Unity.

Gateways #

Player - Game clients connect to the Player gateway. This is facilitated by the Pragma SDK embedded in your game project.

Partner - This is a trusted endpoint that enables server-to-server communication for partner services such as dedicated game servers.

Operator - This is a trusted endpoint protected by VPN. This powers APIs for the web portal and other admin capabilities.

Quick Guides #

Authenticating and logging in with the social platform #

You have several options for authenticating and logging in with your game project. Sending these authenticateOrCreateV2 requests and adding the relevant code to your project will result in pragmaTokens.

Data contained in pragmaGameToken JSON Web Token:

{
  "sub": "19b5982a-f4d6-4ea3-a108-bad4afd852c7",
  "backendType": "GAME",
  "displayName": "test01",
  "pragmaSocialId": "d861f6e8-b63d-4582-a6c4-d515b2d8adbb",
  "iss": "pragma",
  "refreshInMillis": "2617000",
  "discriminator": "8704",
  "refreshAtMs": "1666139349326",
  "sessionType": "PLAYER",
  "exp": 1666223132,
  "gameShardId": "00000000-0000-0000-0000-000000000001",
  "iat": 1666136732,
  "pragmaPlayerId": "19b5982a-f4d6-4ea3-a108-bad4afd852c7",
  "jti": "409a1a94-e0d4-41af-aee6-b9e11f353a36"
}

Data contained in pragmaSocialTokenJSON Web Token:

{
  "sub": "d861f6e8-b63d-4582-a6c4-d515b2d8adbb",
  "refreshAtMs": "1666139469340",
  "backendType": "SOCIAL",
  "displayName": "test01",
  "pragmaSocialId": "d861f6e8-b63d-4582-a6c4-d515b2d8adbb",
  "iss": "pragma",
  "refreshInMillis": "2737000",
  "sessionType": "PLAYER",
  "exp": 1666223132,
  "iat": 1666136732,
  "jti": "0b58d376-f52f-44ee-85d3-c3cedda2d81b",
  "discriminator": "8704"
}

Using Unsafe Provider #

Send authenticateOrCreateV2 with providerId UNSAFE:

{
  "providerId": "UNSAFE",
  "providerToken": "{\"accountId\":\"test01\",\"displayName\":\"test01\"}",
  "gameShardId": "00000000-0000-0000-0000-000000000001"
}

Using Discord #

Send authenticateOrCreateV2 with providerId DISCORD:

{
  "providerId": "DISCORD",
  "providerToken": "$DiscordToken",
  "gameShardId": "00000000-0000-0000-0000-000000000001"
}

Using Steam #

Pragma Engine supports authentication to Steam either via Session Tickets or the Steamworks Web API. See the Steam auth docs for more information about Session Tickets or the Steamworks Web API. Both authentication tokens use the same provider, and Pragma Engine will interpret and validate them both correctly.

Send authenticateOrCreateV2 with providerId STEAM using Session Tickets or the Steamworks Web API:

Session Tickets
{
  "providerId": "STEAM",
  "providerToken": "$SteamToken",
  "gameShardId": "00000000-0000-0000-0000-000000000001"
}
Steamworks Web API
{
  "providerId": "STEAM",
  "providerToken": "{
    \"claimedId\": \"claimed_id\",
    \"ns\": \"ns\",
    \"mode\": \"mode\",
    \"opEndpoint\": \"op_endpoint\",
    \"identity\": \"identity\",
    \"returnTo\": \"return_to\",
    \"responseNonce\": \"response_nonce\",
    \"assocHandle\": \"assoc_handle\",
    \"signed\": \"signed\",
    \"sig\": \"sig\"
  }",
  "gameShardId": "00000000-0000-0000-0000-000000000001"
}
All fields from this provider token are provided by Steamworks when a user is redirected back to Pragma Engine after the initial OAuth login.

Generating Partner tokens #

Once you have successfully authenticated into Pragma Engine as an Operator, you can generate trusted Partner tokens.

Using Portal #

Partner tokens can be generated for both production and test environments using Portal.

  1. Access the Game Portal by opening the 10200 port for your game and log in. Use the Pragma Unsafe login for test environments, and one of the verified identity provider logins for production environments.
  2. Open the Services section, and select the Game Server Management page.
  3. Use the Select a Game Shard dropdown to select the game shard to associate it with the generated Partner token.
  4. On the Partner Tokens tab, click + Create Tokens to generate Partner tokens for both Game and Social.

Using Postman #

Partner tokens can only be generated for test environments using Postman, because the authentication step uses the Unsafe Provider.

  1. Send authenticateOrCreateV2 as an Operator.
  2. Send createPartnerTokenV1 with the correct gameShardId to receive a payload with Partner tokens for both Game and Social.
Game tokens are valid per game shard, and social tokens are valid across the entire Social gateway.