Login and Session #

You can use the Account service to manage your players’ and operators’ login and session experience. A player or operator can use your game client and identity provider to connect to your game and social services. This connection creates a user session.

When setting up your client login and session management, consider these approaches:

• [Recommended] Maintain a long-lived WebSocket. A long-lived WebSocket allows your platform and client to communicate without polling patterns.
• Use messaging through client HTTP requests. HTTP is useful for testing and web functionality but is not designed for production scenarios.

Login #

Login queue #

The login queue routes your players through a queue when they attempt to log in using your authentication services. With the login queue:

• You can rate limit logins to help manage larger than normal requests to your game, such as on launch days
• You can use authentication servers with lower hardware requirements without the risk of server overload
• You can provide more information to your players on the login screen

The logic for bans and limited access mode occurs when authenticateorcreatev2 is called. For a detailed diagram see the Example: Bans and limited access mode dropdown below.

Login queue flow

Below we’ll go through an example of how the Pragma SDK flows through login:

1. A player client calls logIn function in the SDK.
2. The SDK then calls /v1/loginqueue/getinqueuev1.
3. The response is a login queue ticket.
4. The SDK opens up the login queue ticket which includes the following information:
   • isAllowedIn: boolean to determine whether the SDK should move on to the authentication flow
   • Token: string sent with the request to authenticateorcreatev2 to validate the player is moved on to the authentication flow
   • PollNextDuration: long used to determine the delay time before calling checkticket
   • Eta: long used to show the estimated time until the player will be moved on to the authentication flow
   • PositionInQueue: int used to show the player’s current number in queue
5. There are two possible scenarios dependent on isAllowedIn:
   • If isAllowedIn is true, call authenticateorcreatev2 with the provided token. The flow for login queue is complete and the player is moved on to the authentication flow.
   • If isAllowedIn is false, continue to step 6.
6. Wait the PollNextDuration time.
7. The /v1/loginqueue/checkticketv1 endpoint is called and issues a new login queue ticket with updated values for the player client.
8. Repeat from step 5.

Authentication flow

Below we’ll go through an example of how the Pragma SDK and server flows through the authentication process:

1. The SDK makes a request to the authenticateorcreatev2 endpoint.
2. Pragma validates if the identity provider in the request is enabled.
   • If true, continue through the flow.
   • If false, an exception is thrown and no token is returned.
3. Pragma checks with the provider whether the token is valid.
   • If true, continue through the flow.
   • If false, an exception is thrown and no token is returned.
4. Pragma checks if this is for a new account.
   • If true, execute AccountPlugin::OnAccountCreate, create a Pragma Account, and then execute AccountPlugin::OnAccountCreated.
   • If false, continue through the flow.
5. Pragma checks if the user has access to this game shard.
   • If true, continue through the flow.
   • If false, NotFoundApplicationError is thrown.
6. Pragma checks whether the player’s account has any active bans.
   • If true, AccountBannedApplicationError is thrown.
   • If false, continue through the flow.
7. Pragma checks if Limited Access Mode is enabled.
   • If true, Pragma checks if this user has access to the specified game shard.
     • If true, continue through the flow.
     • If false, GameShardAccessDeniedApplicationError is thrown.
   • If false, continue through the flow.
8. Pragma executes AccountPlugin::OnAccountLogin.
9. Pragma returns game and social tokens, and the player should now have full access.

You can pause the authentication flow or add custom logic at the points where Pragma executes your plugin code (steps 4 and 8). For instance, you could add a player to a player group or grant them a login bonus.

Login queue configuration #

The login queue configuration is set with some initial values to get you started. You can view these values and tune them in the LoginQueueServiceConfig.

game:
  serviceConfigs:
    LoginQueueServiceConfig:
      targetLoginRatePerSecond: 50
      targetCcuLimit: 10000
      estimatedSecondsToLogin: 10
      maxCheckTicketPollTimeSeconds: 300

Login queue configurations apply to your entire deployed Pragma Engine instance. Review the following table to understand how to tune these values:

Get started with login queues #

1. Review the default values set in the LoginQueueServiceConfig and ensure they match your environment’s needs.
2. [Optional] Set up your game client to listen for the OnLoginQueueUpdate broadcast event. OnLoginQueueUpdate broadcasts the QueueUpdateData structure. The QueueUpdateData structure contains the following details that your game client can use to provide your users more details about their login experience.
   • Eta: The estimated amount of time in milliseconds until the user is logged in.
   • PositionInQueue: The user’s place in the login queue.

The login queue functionality is built into the Pragma SDK for Unreal and Unity. To manually implement authentication in your game client, see Authenticate with RPC.

The following examples can be found in the Pragma SDK test examples for Unreal and Unity.

1
2
3
4
5
6
7

Player->OnLoginQueueUpdate.AddLambda([this, &NewEta, 
    &NewPositionInQueue, &UpdateCalled](const FPragma_QueueUpdateData UpdateData)
{
    NewEta = UpdateData.Eta;
    NewPositionInQueue = UpdateData.PositionInQueue;
    // Update game client UI to display ETA and position
});

1
2
3
4
5
6

_accountService.OnLoginQueueUpdate += queueUpdateComplete =>
{
    newEta = queueUpdateComplete.Eta;
    newPositionInQueue = queueUpdateComplete.PositionInQueue;
    // Update game client UI to display ETA and position
};

Testing and development #

During development and testing you can bypass the login queue ticket validation to reduce testing and development time. To bypass the login queue enable the devLoginQueueBypass in the SocialPlayerGatewayConfig.

social:
  serviceConfigs:
    SocialPlayerGatewayConfig:
      devLoginQueueBypass: true

This is not recommended for production and live games or services. In addition, this does not turn off the login queue for the SDK. This only disables the login queue if you are developing against authenticateOrCreate directly. To fully disable login queue you’ll also need to set the LoginServiceConfig values to high values for targetCCU and targetLoginsPerSecond.

Login data plugin #

After your players or operators successfully authenticate with your game, you can use the login data plugin to customize the login experience. The login data plugin collects data from multiple sources and sends it to the client on player login.

The login data plugin defines dependent jobs that start when a player logs in. Authoring additional dependent jobs can handle new capabilities, such as granting players rewards on login. For more information, see Authoring dependent jobs.

Session #

Session tokens #

Your game client provides the Pragma session tokens during requests to Pragma Engine. The engine then uses these tokens to identify the player, route requests, and verify that the request came from a trusted source.

Session tokens are a type of JSON Web Token, JWT. The session tokens are signed by a RSA key pair that is configured in the TokenConfig object. Pragma uses two types of session tokens.

• Pragma game tokens (pragmaGameToken) - The pragmaGameToken can be used to connect to a game server with matching gameShardId.
• Pragma social tokens (pragmaSocialToken) - The pragmaSocialToken can be used to connect to a social server.

{
  "sub": "19b5982a-f4d6-4ea3-a108-bad4afd852c7",
  "backendType": "GAME",
  "displayName": "test01",
  "pragmaSocialId": "d861f6e8-b63d-4582-a6c4-d515b2d8adbb",
  "idProvider": "STEAM",
  "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"
}

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

Session timeout #

You can define how long a player’s session remains active. You can use an active session token for future logins within the defined time frame. You can change the expiration time in the TokenConfig.

After you’ve configured the length of time a token is valid, you can manually store tokens on a user’s machine. The SDKs support logging in with existing authentication tokens via an overload of LogIn on the Player session class.

These are the default values in the YAML configuration for the TokenConfig.

social:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "original-RSA-public-key"
        private: "original-RSA-private-key"
      partnerExpirationHours: 876000
      operatorExpirationMinutes: 2880
      emailTokenExpirationMinutes: 10080
      playerTokenExpirationMinutes: 1440
      playerTokenRefreshMinutes: 45
      playerTokenRefreshVarianceWindowMinutes: 5

Key rotation #

While the Pragma Platform is running, you can change the keys used for token signing and verification without disrupting a user’s existing sessions or forcing them to re-authenticate.

To rotate keys update the TokenConfig under both game and social as follows:

1. Replace the jwtCurrentKeys values with the new RSA key pair.
2. Add jwtRotatedPublicKeys.
3. Under jwtRotatedPublicKeys add the previous/old public key.
   • Keys in the jwtRotatedPublicKeys list will only be used for verification and won’t be included in the token signing process.

The public and private keys under jwtCurrentKeys must be a valid RSA key pair otherwise the user will not be able to log in or get a session.

Below we’ll go through what a TokenConfig would look like before and after rotating keys:

# Initial TokenConfig 
game:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "original-RSA-public-key"
        private: "original-RSA-private-key"
social:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "original-RSA-public-key"
        private: "original-RSA-private-key"

# After first rotation 
game:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys: 
        public: "new-RSA-public-key" 
        private: "new-RSA-private-key" 
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key" # previous public key
social:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "new-RSA-public-key"
        private: "new-RSA-private-key"
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key" # previous public key

# After second rotation
game:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "newest-RSA-public-key"
        private: "newest-RSA-private-key"
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key"
        2: "new-RSA-public-key"
social:
  serviceConfigs:
    TokenConfig:
      jwtCurrentKeys:
        public: "newest-RSA-public-key"
        private: "newest-RSA-private-key"
      jwtRotatedPublicKeys:
        1: "original-RSA-public-key"
        2: "new-RSA-public-key"

After rotating keys, we recommend cleaning up old keys that are not in use. For example, consider a scenario where you have a token that has a lifespan of eight hours and the current key in session is public key A. You switch to public key B and rotate public key A; public key A is now used only for validation. After eight hours, you can remove public key A because all tokens signed with it have expired. Removing rotated public keys before they’ve expired will immediately invalidate any remaining old tokens.

This affects all tokens and token related behaviors. Tokens such as email verification and login queue might have different expiratation times from player tokens. Partner tokens will need to be redistributed to trusted third parties before removing the relevant public key.

Remove and block players from their active session #

You can force the termination of a player’s session from the server and prevent them from reconnecting for a period of time. The following endpoints are available for removing and blocking a player’s session:

• PlayerSessionRpc.BlockPlayerSessionOperatorV1Request
• PlayerSessionRpc.BlockPlayerSessionPartnerV1Request
• PlayerSessionRpc.BlockPlayerSessionServiceV1Request

Players with an active session are forcefully disconnected from the game client and prevented from reconnecting for a set duration; the minimum duration of a block is 1 minute and the maximum duration is the length of a single session. See Session Timeout for more information.

After the block is removed, a player can reconnect with:

• their existing token if it has not timed out, or
• a new session created through AuthenticateOrCreate

If you want to prevent a player from creating a new session by logging in again, see our Bans feature.

Send BlockPlayerSession with a pragmaId (social ID on social or player ID on game) and a duration in milliseconds:

{
  "requestId": 1,
  "type": "PlayerSessionRpc.BlockPlayerSessionOperatorV1Request",
  "payload": {
      "pragmaId": "{{test01PragmaSocialId}}",
      "durationInMillis": 1000000
  }
}

The following endpoints are available to unblock a player’s session:

• PlayerSessionRpc.UnblockPlayerSessionOperatorV1Request
• PlayerSessionRpc.UnblockPlayerSessionPartnerV1Request
• PlayerSessionRpc.UnblockPlayerSessionPartnerServiceV1Request

Send UnblockPlayerSession:

{
  "requestId": 1,
  "type": "PlayerSessionRpc.UnblockPlayerSessionPlayerOperatorV1Request",
  "payload": {
      "pragmaId": "{{test01PragmaSocialId}}"
  }
}