Authentication #

With Pragma Engine you can use your own identity provider to authenticate:

• players: end users joining your game
• operators: individuals with access to Operator Portal to perform administrative functions

Authenticated players and operators can then use your game client to make requests to Pragma Engine.

After a player logs in to your identity provider, the identity provider passes a session token to the Pragma Engine. The engine then exchanges the provider token for a Pragma session token. For more information about sessions, see Login and Session.

To try out setting up authentication, see the Unreal and Unity authentication tutorials.

Gateways #

Gateways are the endpoints your clients connect to. The following types of gateways each have a social gateway and game gateway:

• Player: End user clients connect to the Player gateways. 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: Clients connect to the Operator gateways which are protected by VPN. The web portal is the main way of interacting with the Operator gateway.

By default Pragma Engine enables three social gateways and three game gateways for each session type. The number of gateways is scalable to fit your game’s needs.

Player and Operator authentication #

Pragma Engine supports multiple identity providers for Player and Operator authentication. Below are the available identity providers and their respective values. For more information, see Identity Providers.

To add additional identity providers, see Custom Identity Providers.

You can use either the identity provider name or identity provider value on authenticateorcreatev2 for the providerId.

The following examples show the required authenticateorcreatev2 request body. authenticateorcreatev2 is designed for game logins using the Pragma SDK. If you don’t use the Pragma SDK to authenticate your users, see Authenticate with RPC.

{
  "providerId": "UNSAFE",
  "providerToken": "{\"accountId\":\"test01\",\"displayName\":\"test01\"}",
  "gameShardId": "00000000-0000-0000-0000-000000000001",
  "loginQueuePassToken": "test queue pass token"
}

{
  "providerId": "STEAM",
  "providerToken": "$SteamToken",
  "gameShardId": "00000000-0000-0000-0000-000000000001",
  "loginQueuePassToken": "test queue pass token"
}

{
  "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",
  "loginQueuePassToken": "test queue pass token"
}

{
  "providerId": "DISCORD",
  "providerToken": "$DiscordToken",
  "gameShardId": "00000000-0000-0000-0000-000000000001",
  "loginQueuePassToken": "test queue pass token"
}

Authenticate with RPC #

When authenticating with Pragma, we recommend you use the Pragma SDK. The Pragma SDK completes all the following steps for you and reduces the possibility for errors. For more information about authentication using the Pragma SDK, see the Unreal Setup or Unity Setup guide.

To manually create an authentication workflow for your client, use the following steps.

1. Make a call to the getinqueue endpoint. The endpoint returns a JSON object with an encrypted loginQueuePassToken.
   1. Check the isAllowed field in the JSON object.
   2. If the isAllowed field is false continue to poll using the checkTicket endpoint until the JSON object returns with isAllowed set to true.
2. When the isAllowed field is set to true, make a call to the authenticateorcreatev2 endpoint with the loginQueuePassToken included in the authenticateorcreatev2 request body.

{
   "providerId":1,
   "providerToken": "{\"accountId\":\"test01\",\"displayName\":\"test01\"}",
   "gameShardId":"00000000-0000-0000-0000-000000000001",
   "loginQueuePassToken": "test queue pass token"
}

If you enable the devLoginQueueBypass configuration, skip the above steps. The authenticateorcreatev2 body won’t have the loginQueuePassToken. For more information, see Login queue testing and development.

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

Web portal sign in and sign up #

Pragma Engine offers two endpoints for players signing in and signing up on a web portal:

• /v1/accounts/authenticatev1
• /v1/accounts/createaccountv1

This authentication flow is optimized for web portal sign in and sign up, and only provides social tokens. Since players will be prompted in the web portal when creating an account, this flow prevents accidental account creation.

We recommend using these endpoints only for web portals since they are not subject to login queue. Login queue is integral for managing server load in multiplayer games. These endpoints are for social login only.

Web portal authentication #

To authenticate a player’s Pragma Account call /v1/accounts/authenticatev1. There are two possible scenarios dependent on if a Pragma Account exists for the given identity provider account:

• If the account exists, it is authenticated and a social token is returned.
• If the account does not exist, the public endpoint returns HTTP 403 Forbidden and the platform returns an AccountService_NotFound error message.

Web portal account creation #

To create a Pragma Account for a player call /v1/accounts/createaccountv1. There are two possible scenarios dependent on if a Pragma Account exists for the given identity provider account:

• If there is an existing account, the public endpoint returns HTTP 409 Conflict and the platform returns an AccountService_AlreadyExists error message.
• If there is no existing account, a new Pragma Account is created. The newly created account is authenticated and a social token is returned.

Generate Partner tokens #

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

Use Operator Portal #

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

1. Access the Social Operator Portal through the 11200 port 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.

Use 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.

To generate unique partner tokens per game server, see the Fleet service task.