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
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
Login queue configurations apply to your entire deployed Pragma Engine instance. Review the following table to understand how to tune these values:
Configuration | Description | Recommendation |
---|---|---|
targetLoginRatePerSecond | The target maximum number of users to log in per second. | Set this value lower than the maximum number of requests your authentication server can handle per second. |
targetCcuLimit | The target maximum number of concurrent users logged in. | Set this to a value lower than your game servers maximum concurrent players that does not overload your game servers. |
estimatedSecondsToLogin | How long you estimate it takes between a user login request and the user gaining access. | Set this to the predicted average amount of time it takes your system to log in a user. |
Get started with login queues #
- Review the default values set in the
LoginQueueServiceConfig
and ensure they match your environment’s needs. - [Optional] Set up your game client to listen for the
OnLoginQueueUpdate
broadcast event.OnLoginQueueUpdate
broadcasts theQueueUpdateData
structure. TheQueueUpdateData
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.
|
|
|
|
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
Note: This is not recommended for production and live games or services.
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, and by default collects a player’s inventory data. 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 matchinggameShardId
. - Pragma social tokens (pragmaSocialToken) - The
pragmaSocialToken
can be used to connect to a social server.
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:
- Replace the
jwtCurrentKeys
values with the new RSA key pair. - Add
jwtRotatedPublicKeys
. - 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.
- Keys in the
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 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.