# DDoS protection with Amazon GameLift Servers
<a name="ddos-protection-intro"></a>

Amazon GameLift Servers player gateway is a relay-based network that routes UDP traffic between game clients and game servers hosted on Amazon GameLift Servers. Player gateway provides proactive DDoS protection by validating traffic before it reaches game servers, rate limiting player traffic, hiding game server IP addresses from the public, and providing updated endpoints when relay endpoints become unhealthy. This feature helps protect your game servers from volumetric attacks with negligible added latency.

Player gateway requires game servers to run on Linux-based Amazon GameLift Servers Managed EC2 fleets or Container Fleets. You must enable player gateway during fleet creation and update your game client and game backend to use this feature.

## Key benefits
<a name="ddos-protection-intro-benefits"></a>

Player gateway provides the following security and operational benefits:
+ **Hide game server IP addresses** – Game clients connect through relay endpoints instead of directly to game servers, hiding your game server addresses from the public.
+ **Validate traffic** – All traffic through player gateway requires a player gateway token, allowing only traffic from authenticated players to reach your game servers.
+ **Dynamic endpoint replacement** – When relay endpoints become unhealthy, Amazon GameLift Servers quickly replaces the endpoints and provides updated healthy endpoints on the next call to refresh player connection details.
+ **Distribute player traffic** – Relay endpoints vary across players, reducing the impact of a single unhealthy relay endpoint to other players within the same game session.

# How player gateway works
<a name="ddos-protection-howitworks"></a>

Player gateway uses a relay network to route UDP traffic between game clients and game servers. This protects against DDoS attacks by validating traffic before it reaches game servers, rate limiting player traffic, hiding game server IP addresses from the public, and providing updated endpoints when relay endpoints become unhealthy.

## Traffic flow
<a name="ddos-protection-howitworks-traffic-flow"></a>

When a player connects to a game session, your game backend retrieves relay endpoints and a player gateway token from the `GetPlayerConnectionDetails` API and sends them to the game client. The game client prepends the player gateway token to UDP packets and sends the packets to a relay endpoint. The relay network validates the token and routes legitimate traffic to the game server. Before delivery, the relay network strips the player gateway token so that game servers receive the raw game client payload and should not require code changes. Communication from the game server back to the game client returns through the relay network without modification.

![\[Architecture diagram showing game client connecting through relay network to game server\]](http://docs.aws.amazon.com/gameliftservers/latest/developerguide/images/player_gateway_architecture.png)


## Core concepts
<a name="ddos-protection-howitworks-components"></a>

### Relay endpoints
<a name="ddos-protection-howitworks-endpoints"></a>

Relay endpoints are IP address and port combinations that game clients use to send traffic through player gateway. Each player receives multiple endpoints that vary across players to distribute traffic and reduce the impact of attacks on other players in the same game session.

![\[Diagram showing multiple players receiving different relay endpoints for the same game sessions\]](http://docs.aws.amazon.com/gameliftservers/latest/developerguide/images/player_gateway_relay_endpoints.png)


### Player gateway tokens
<a name="ddos-protection-howitworks-tokens"></a>

Player gateway tokens are encrypted byte arrays that authorize a player to send traffic to a game session through player gateway. The `GetPlayerConnectionDetails` API returns tokens as base64-encoded strings. Game clients must prepend the player gateway token to every UDP packet. The relay network validates tokens and rejects packets with invalid or missing tokens.

**Important**  
Player gateway tokens must not be encrypted and must appear at the beginning of each UDP packet sent by the game client. If your game encrypts payloads, prepend the unmodified player gateway token after encrypting the game data.

Player gateway tokens remain valid for at least 3 minutes. We recommend refreshing tokens every 60 seconds to ensure players receive updated endpoints when relay endpoints become unhealthy.

### GetPlayerConnectionDetails API
<a name="ddos-protection-howitworks-api"></a>

Your game backend calls the `GetPlayerConnectionDetails` API to retrieve connection details for players in a game session. The API returns either relay endpoints and player gateway tokens, or falls back to the game server's IP address and port for direct connection. Your game client should be designed to handle both connection types. To receive updated endpoints when relay endpoints become unhealthy, call this API periodically throughout the game session (recommended every 60 seconds).

For more information, see [GetPlayerConnectionDetails API](ddos-protection-integrate.md#ddos-protection-integrate-backend-api).

## Monitoring player gateway
<a name="ddos-protection-howitworks-monitoring"></a>

Player gateway publishes metrics to Amazon CloudWatch to help you monitor network traffic patterns, identify potential DDoS attacks, and track relay performance. Metrics include packets and bytes in/out, throttled traffic, and player sessions. For the complete list of player gateway metrics, see [DDoS protection (player gateway) metrics](monitoring-cloudwatch.md#gamelift-metrics-fleet-playergateway).

## IPv4 and IPv6 compatibility
<a name="ddos-protection-howitworks-ipv4-ipv6"></a>

Game clients communicate using IPv4. Player gateway uses IPv6 to communicate with game servers. Amazon GameLift Servers automatically handles the translation between IPv4 and IPv6 based on your fleet configuration.

For more information on configuring player gateway on your fleet, see [CreateFleet](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_CreateFleet.html#gameliftservers-CreateFleet-request-PlayerGatewayMode) or [CreateContainerFleet](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_CreateContainerFleet.html#gameliftservers-CreateContainerFleet-request-PlayerGatewayMode). For more information about IPv4 and IPv6 support, see [IPv4 and IPv6 compatibility](ddos-protection-enable.md#ddos-protection-enable-ip-protocol).

# Enable player gateway on fleets
<a name="ddos-protection-enable"></a>

Enable player gateway when creating a fleet to route game traffic through relay endpoints that validate and rate limit incoming UDP traffic to your game servers.

## Prerequisites
<a name="ddos-protection-enable-prerequisites"></a>

Before enabling player gateway, verify the following requirements:
+ **Supported locations** – For a list of AWS locations that support player gateway, see [Amazon GameLift Servers service locations](gamelift-regions.md).
+ **Fleet type** – Player gateway supports Linux-based Managed EC2 fleets and Managed Container fleets.
+ **Server SDK** – Player gateway requires Amazon GameLift Servers Server SDK 5.0 or later.

## Player gateway modes
<a name="ddos-protection-enable-modes"></a>

Configure player gateway compatibility for your fleet using the `PlayerGatewayMode` property:

DISABLED (default)  
Fleet is not compatible with player gateway.

ENABLED  
Fleet is compatible with player gateway in locations where it is supported. Fleet locations that do not support the feature can still be added to the fleet but will not utilize player gateway, directly utilizing the game server IP address.

REQUIRED  
Fleet is compatible with player gateway. Fleet locations that do not support the feature cannot be added to the fleet.

## IPv4 and IPv6 compatibility
<a name="ddos-protection-enable-ip-protocol"></a>

Game clients must communicate with player gateway via IPv4. The player gateway relay network communicates with game servers using IPv6. Managed Container fleets automatically translate the IPv6 traffic to IPv4. For Managed EC2 fleets, configure how your fleet handles IPv6 traffic using the `GameServerIpProtocolSupported` property in `PlayerGatewayConfiguration`:

IPv4 (default)  
Your game server only accepts incoming IPv4 traffic. Lightweight IP translation software will be installed and executed on your instances to receive and transform the incoming IPv6 traffic to IPv4.

DUAL\$1STACK  
Your game server is compatible with incoming IPv6 traffic. IP translation software will not be installed or executed on your instances. Game servers that support IPv6 natively may have slightly higher performance.

# Integrate player gateway into a game
<a name="ddos-protection-integrate"></a>

After creating a player gateway-enabled fleet, you must update your game client and game backend to integrate with player gateway. Your game backend retrieves relay endpoints and player gateway tokens, then provides them to game clients. Game clients send all UDP traffic to these relay endpoints.

The integration follows this call path:

1. Your game backend calls the `GetPlayerConnectionDetails` API to retrieve relay endpoints and player gateway tokens for each player in a game session.

1. Your game backend sends the relay endpoints and player gateway tokens to the game client.

1. Your game client prepends the player gateway token to all outgoing UDP packets and sends the packets to the relay endpoints.

1. The relay network validates the player gateway token and routes the traffic to your game server.

1. Your game server sends traffic back to your game client through the same relay paths.

## Backend integration
<a name="ddos-protection-integrate-backend"></a>

Your game backend must call the `GetPlayerConnectionDetails` API to retrieve relay endpoints and player gateway tokens for players. The backend then provides this information to game clients.

### GetPlayerConnectionDetails API
<a name="ddos-protection-integrate-backend-api"></a>

The `GetPlayerConnectionDetails` API returns connection details for players in a game session:

Relay endpoints and tokens  
When player gateway is enabled and supported in the location, returns:  
+ **Relay endpoints** – Multiple relay endpoints (IP address and port) that vary across players
+ **Player gateway token** – Token that the client must prepend to all UDP packets (valid for at least 3 minutes)
+ **Expiration** – Player gateway token expiration timestamp

Direct connection  
When player gateway is not enabled or not supported in the location, returns the game server's IP address and port

Your game client should be designed to handle both connection types.

Example API call:

```
// C++ example using AWS SDK
Aws::GameLift::GameLiftClient client;
Aws::GameLift::Model::GetPlayerConnectionDetailsRequest request;
request.SetGameSessionId(gameSessionId);
request.SetPlayerIds(playerIds);  // Vector of player IDs

auto outcome = client.GetPlayerConnectionDetails(request);
if (outcome.IsSuccess()) {
    auto result = outcome.GetResult();
    auto connectionDetails = result.GetPlayerConnectionDetails();
    
    // Process each player's connection details
    for (const auto& detail : connectionDetails) {
        std::string playerId = detail.GetPlayerId();
        
        // Get relay endpoints (IP address and port)
        auto endpoints = detail.GetEndpoints();
        for (const auto& endpoint : endpoints) {
            std::string ipAddress = endpoint.GetIpAddress();
            int port = endpoint.GetPort();
        }
        
        // Get player gateway token
        auto token = detail.GetPlayerGatewayToken();
        
        // Get expiration time
        auto expiration = detail.GetExpiration();
        
        // Send endpoints and token to game client
    }
}
```

See [GetPlayerConnectionDetails](https://docs.aws.amazon.com/gameliftservers/latest/apireference/API_GetPlayerConnectionDetails.html) in the *Amazon GameLift Servers API Reference*.

### Refresh relay endpoints
<a name="ddos-protection-integrate-backend-refresh"></a>

Call `GetPlayerConnectionDetails` periodically to provide players with updated endpoints when relay endpoints become unhealthy. We recommend calling the API every 60 seconds for all players in a game session. To optimize API usage, batch multiple player IDs in a single API call.

**Important**  
Regular refresh calls are the primary mechanism for delivering updated endpoints to players. While player gateway tokens remain valid for at least 3 minutes, refreshing every 60 seconds ensures players receive updated endpoints regularly.

## Client integration
<a name="ddos-protection-integrate-client"></a>

Your game client must prepend player gateway tokens to all outgoing UDP packets and send the packets to the provided relay endpoints. The Amazon GameLift Servers client SDK for C\$1\$1 and Unreal Engine provides utilities to simplify this integration.

### Client requirements
<a name="ddos-protection-integrate-client-requirements"></a>

To route traffic through player gateway, your game client must:
+ **Prepend player gateway tokens** – Prepend the player gateway token to all outgoing UDP packets. Player gateway tokens must not be encrypted and must appear at the beginning of each packet. Packets without a valid player gateway token will be dropped.
+ **Send to relay endpoints** – Send all UDP packets to the provided relay endpoints.
+ **Maintain connection activity** – Ensure that either the game client sends a packet to the game server, or the game server sends a packet to the player, at least once every 30 seconds. This activity maintains the connection through the relay network.
+ **Handle endpoint updates** – Accept updated relay endpoints and player gateway tokens from your backend (recommended every 60 seconds) and transition to new endpoints without dropping the connection.

### Client SDK
<a name="ddos-protection-integrate-client-sdk"></a>

The Amazon GameLift Servers client SDK for C\$1\$1 and Unreal Engine provides utilities to simplify player gateway integration:
+ **Token management** – Prepends player gateway tokens to all outgoing UDP packets.
+ **Endpoint selection** – Routes traffic to relay endpoints using a configurable algorithm.
+ **Endpoint refresh** – Schedules periodic callbacks to retrieve updated relay endpoints and player gateway tokens from your backend.

### Endpoint selection algorithms
<a name="ddos-protection-integrate-client-algorithms"></a>

The client SDK provides two built-in algorithms for selecting which relay endpoint to use:

Fallback algorithm  
Uses one endpoint until it becomes unhealthy, then switches to another endpoint. Best for menus, lobbies, and turn-based games where brief interruptions are acceptable. During endpoint failover, packets may be lost for the configured timeout period (default: 2 seconds).

Predictive rotation algorithm  
Continuously rotates through all available endpoints and predicts failures before they occur. Best for real-time gameplay such as first-person shooters and racing games where consistent packet delivery is critical. Requires the game server to send messages at a consistent frequency.

You can also implement custom algorithms by extending the SDK's base algorithm class.

### Client SDK resources
<a name="ddos-protection-integrate-client-resources"></a>

For complete integration instructions and sample code, see the following resources:

C\$1\$1  
A client SDK for C\$1\$1 is available at [Amazon GameLift Servers client SDK for C\$1\$1](https://github.com/amazon-gamelift/amazon-gamelift-servers-client-sdk-for-cpp).

Unreal Engine  
A plugin for Unreal Engine is available at [Amazon GameLift Servers client SDK for Unreal Engine](https://github.com/amazon-gamelift-for-unreal/amazon-gamelift-servers-client-sdk-for-unreal). Access requires membership in the Epic Games organization on GitHub. See [Unreal Engine on GitHub](https://www.unrealengine.com/en-US/ue-on-github) for details.

## Test your integration
<a name="ddos-protection-integrate-testing"></a>

Before deploying to a fleet, test your player gateway integration locally using the player gateway testing tool. This tool simulates the player gateway UDP proxy infrastructure and helps you verify that your game client correctly prepends player gateway tokens, routes traffic through multiple endpoints, and handles network degradation.

For setup and usage instructions, see the [player gateway testing app](https://github.com/amazon-gamelift/amazon-gamelift-toolkit/tree/main/player-gateway-testing-app) on GitHub.

## Best practices
<a name="ddos-protection-integrate-best-practices"></a>

Follow these best practices when integrating player gateway:
+ **Refresh endpoints every 60 seconds** – Call `GetPlayerConnectionDetails` every 60 seconds to ensure players receive updated endpoints regularly.
+ **Batch API calls** – When calling `GetPlayerConnectionDetails` for multiple players in the same game session, batch the calls together to reduce API overhead.
+ **Maintain connection activity** – Ensure that traffic flows between the game client and game server at least once every 30 seconds. This can be either client-to-server or server-to-client traffic.
+ **Handle endpoint updates gracefully** – When your game client receives updated endpoints from the backend, transition to the new endpoints without dropping the player's connection.
+ **Choose the right algorithm** – Select the endpoint selection algorithm that best matches your game's requirements. Use the fallback algorithm for turn-based games and the predictive rotation algorithm for real-time games.