Client Credential and Client Policy Management

Managing client credentials within the EOS environment.

An EOS Client is any program accessing Epic Online Services (EOS) functionality for a product, including the local build of a game run by end-users on their systems, dedicated servers run by the product's owners, or any other program need visibility to backend services.

EOS uses OAuth Client Credentials to authorize access to these services. When created each EOS Client is automatically assigned a Client ID and a Client Secret (password) that you must use for authentication. You can use the Developer Portal to assign individual EOS Client Policies to EOS Clients. EOS Client Policies enable varying levels of access to different services such as GameClient, Peer2Peer, and TrustedServer.

Clients created before the introduction of Client Policies are automatically associated with a Client Policy matching the Client's originally-assigned rol and marked with the label Legacy.

We encourage you to review your use of Client Policies. If your game is not running dedicated servers, but allows clients to host peer2peer matches, consider updating your policy to the new Peer2Peer policy or an appropriate custom policy.

Configuring EOS Clients and Policies

Client policies are crucial to securing your game against unauthorized activity. You can view and manage EOS Clients and EOS Client Policies by navigating to Product Settings for your product and selecting the Clients tab.

Click image for full size.

Policy Types

Trusted vs Untrusted Clients

Untrusted clients are typically publicly-released applications, such as the game client itself. Servers released to be run by the community or peer2peer games acting as game servers should not be treated as trusted applications. Developers cannot assume all players run untampered versions of your released code when connecting to services with that policy.

Trusted applications are under the developer's control, such as dedicated servers in your datacenter, and are not released publicly. A trusted application can have more permissions because you can assume it is not modified and is running only on your environment.

Default Policy Types

GameClient

  • Policy for untrusted client applications

  • Requires an authenticated user

GameClient with UnlockAchievements

  • Like GameClient, but allows the client to unlock player achievements

  • Requires an authenticated user

Peer2Peer

  • Policy for untrusted client applications that want to host multiplayer matches

  • Requires an authenticated user

TrustedServer

  • Policy for dedicated servers or trusted applications

  • Includes the ability to create matchmaking sessions and ingest stats on behalf of players

  • Does not require an authenticated user

Custom

  • Creates a new policy that allows a customized set of actions for each service

Creating New Client Policies

Before creating a new Client, you need to create an EOS Client Policy determining the permissions an EOS Client has for different services. An EOS Client Policy can be created when creating a new Client or by scrolling down to the Client Policies section and clicking the Add New Client Policy button. Multiple Clients can associate with a single Client Policy.

For example, if an EOS Client is using a dedicated server, you can select the TrustedServer type. This creates a set of permissions suitable for a trusted backend.

You can also configure Custom Client Policies that allow to select the individual actions that are allowed.

Click image for full size.

Client Policy Permission Evaluation

All requests are denied by default. Only actions that are added in the Client Policy are allowed.

Creating New Clients

You can add a new EOS Client by clicking the New Client button. This opens a New Client sidebar where you fill in details about the Client.

A Client must be associated with a Client Policy. You can associate a single Client Policy with multiple Clients. You cannot save a created Client if you do not associate it with a Client Policy.

Usage with the EOS SDK

The EOS SDK requires a program to provide valid Client Credentials, including a Client ID and Client Secret. This information is passed in the the

[EOS_Platform_ClientCredentials](API/EOS/EOS/EOS_Platform_ClientCredentials)
structure, which is a parameter in the function
[EOS_Platform_Create](API/EOS/EOS/EOS_Platform_Create)
. This enables the SDK to recognize the program as a valid EOS Client, authorize the Client with EOS, and grant access to the features enabled in the corresponding Client Role.

When troubleshooting any errors, be sure to check the logs for more details about your issue.

For SDK versions 1.10 and older, any errors with this service return as EOS_Unexpected_Error.

For SDK versions after 1.10, the following table lists potential errors and their resolutions:

Error

Description

Resolution

EOS_NotConfigured

The client permission is not set up for this call.

Go to the Developer Portal and [configure a policy](#configuring-eos-clients-and-policies] for this client.

EOS_AcessDenied

The client permission is set up for this call, but the call fails a check (e.g. you used a correctly set-up client, but tried to access another user's private player data storage).

Check the logs for more details about your issue and contact support.

EOS_InvalidAuth

The client is configured to require a signed-in user, but the client's credentials are not allowed.

Check the logs for more details about your issue and contact support.

EOS_AccessDenied

The client policy forbids this client from calling. It is likely that the Developer Portal is configured to not allow your client access to the call.

Go to the Developer Portal and modify the client configuration. Or make a new policy that allows the given permission.