Connect Interface

The Connect Interface handles connections between users' accounts under different identity providers.

Connect Interface

The Connect Interface enables an external identity provider to integrate with and use the Epic Online Services (EOS) ecosystem.

The Connect Interface:

  • Provides access to the Epic Online Services (EOS) game services.

  • Generates a common unique user identifier within the cross-platform services.

  • Links external identity providers' accounts to our services.

A player can associate one or more external user accounts with their Product User ID (a unique player ID).

This Product User ID carries across all Products under the same Organization.

For more information about supported identity providers and configuration, see Identity Provider Management.

Managing Users

Users login using a set of external credentials. If the user already exists for this product, an access token is granted that lasts for a set period of time (currently one hour). The game is notified prior to the token expiration and is required to refresh the existing token, given a valid external credential at that time.

Epic Online Services interfaces cannot control the access permissions of the external provider. As such, Connect Interface

DOES:

  • Verify the user is still valid with the external account provider

  • Extend the time the user is able to access our services

DOES NOT:

  • Implicitly refresh tokens

  • Grant lengthy access

The external account provider is expected to have authoritative access to the application.

Access to services available via this user identifier requires external account identification via the EOS_ProductUserId data structure. All interfaces clearly indicate this usage and type safety should be assured. It is separate from EOS_EpicAccountId that is associated with the authentication interface provided for Epic Account Services.

Epic Games accounts are not required for using the Connect Interface that can be used with any of the supported external account types.

Logging In

To login, call EOS_Connect_Login with the EOS_Connect_LoginOptions containing external credentials from a supported platform.

In the case of Epic Games accounts, retrieving the current auth token from EOS_Auth_CopyUserAuthToken and setting the EOS_EExternalCredentialType to EOS_ECT_EPIC is sufficient.

Pass the EOS_HConnect handle, your EOS_Connect_LoginOptions structure, and your callback information to EOS_Connect_Login. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

If the result is successful, the application may proceed to access additional interfaces that require authentication. If the user does not exist, the login API will return a EOS_InvalidUser result. Additionally, a EOS_ContinuanceToken will be included. This token provides details about the login attempt and will be required during the next steps in the login flow.

At this juncture, a decision needs to be made. Ask the user if they have a secondary set of external credentials known to be registered with the service (see Linking an Account), or if they'd like to create a new user (see Creating a User).

Auth Token Refresh Notification

A callback function provided to EOS_Connect_AddNotifyAuthExpiration will run whenever an existing access token is about to expire. This should give the application enough time to acquire another external access token and provide it to the SDK via the EOS_Connect_Login function each time.

Use the EOS_Connect_RemoveNotifyAuthExpiration function to stop listening for these notifications.

Status Change Notification

To assure that your application knows whenever a user's authentication status has changed, the Connect Interface provides a callback for such notifications.

The callback function you provide to EOS_Connect_AddNotifyUserLoginStatusChanged runs whenever a local user's authentication status changes. This only occurs if the expiration notification is ignored, the external provider credentials are unable to refresh the access token, or the access was revoked explicitly by the backend service for some administrative reason. This callback fires only when other calls in the EOS ecosystem detect that this auth token is invalid; it does not automatically fire otherwise.

You must handle all the error messages in specific calls that may fail because of authentication. Recovery is often possible by calling EOS_Connect_Login then retrying the original call on success.

Use the EOS_Connect_RemoveNotifyUserLoginStatusChanged function to stop listening for notifications.

Checking Current Authentication Status

To check the player's current status on demand, use the EOS_Connect_GetLoginStatus function. This function determines authentication status based on the most recent communication with the online service, so the result is returned instantly and does not use a callback function.

Creating a User

Creating a user will generate a new Product User ID for the user given the external credentials used during login. It is almost always necessary to prompt the user and see if there is an alternate way to login before creating a new user. This will reduce confusion and user game progression merging issues in cross-platform situations.

If the application intends to create a new product user ID for the user, then simply call EOS_Connect_CreateUser with the EOS_Connect_CreateUserOptions containing the EOS_ContinuanceToken from the previous call to EOS_Connect_Login.

Pass the EOS_HConnect handle, your EOS_Connect_CreateUserOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Linking an External Account

If during the application login flow, it is determined that the user is able to login with a secondary set of external credentials, store the EOS_ContinuanceToken from the first login call, reattempt to login via EOS_Connect_Login, and once successfully logged in, immediately call EOS_Connect_LinkAccount. This will associate the two external accounts to the one product user ID. It is possible to link more than two accounts as the capabilities of our services grow.

If the intent of the application is to link a new external account with an existing product user ID, then call EOS_Connect_LinkAccount with the EOS_Connect_LinkAccountOptions containing the EOS_ContinuanceToken from the previous call to EOS_Connect_Login and the product user ID for the user logged in with a successful call to EOS_Connect_Login.

Pass the EOS_HConnect handle, your EOS_Connect_LinkAccountOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

You can search EOS Connect users by their external account IDs or using the product user ID through the Accounts dashboard in the Developer Portal. As the keychain of a player's linked external accounts is managed at the Organization level, the Accounts dashboard can be found next to the Organization management menu items. Through the Accounts dashboard, you will be able to find players and your customer support will be able to help to remove account linkings by player requests. You can also use this dashboard to remove your EOS Connect user or any linked accounts during SDK integration testing. Along with this, we will provide web REST APIs for developers to integrate EOS user management into their existing internal dashboards.

Unlinking an External Account

During the first time user login flow, it is possible for the user to end up in a state where they inadvertently created a new product user ID for the logged in account (that is typically the local platform account), instead of reusing existing game progression that they may have from playing on another platform or using another external account credentials. The user may not be aware of the crossplay capabilities of the game.

In such a scenario, the user skips any early login dialogs and continues with their default platform account credentials (the logged in account) to create a new EOS_ProductUserId through the flow with EOS_Connect_Login and EOS_Connect_CreateUser APIs. As a consequence, their logged in account that is used with EOS_Connect_Login at game start is now tied with an unintended product user ID. To recover from this state, the user needs to be able to unlink the logged in account from the newly created keychain, so that they may enter the first time user login flow again.

Once they have unlinked the logged in account, they may login using another set of external account credentials linked with another existing keychain. On success, they then proceed to link the default logged in account with that desired existing keychain using the flow described in the Linking an External Account section above.

In another scenario, the user may simply want to disassociate the logged in account from its current keychain in order to separate game progressions between platforms or otherwise link it to another keychain.

To unlink an external account from a keychain that owns the product user ID currently logged in, call EOS_Connect_UnlinkAccount with the EOS_Connect_UnlinkAccountOptions, specifying LocalUserId as the EOS_ProductUserId that was returned by a previous call to EOS_Connect_Login. When the operation completes successfully, the external account will no longer have associations to any keychains. This means that the next attempt to login with EOS_Connect_Login using credentials associated with the same external account will return an EOS_InvalidUser result with an EOS_ContinuanceToken.

Similarly to the account linking creation operations, history of unlinking operations can be audited through the Accounts dashboard in the Developer Portal.

Account Unlinking Restrictions

In order to protect against account theft, unlinking accounts from a keychain is only possible for those accounts that the local user is currently logged in with. This prevents a malicious actor from gaining access to one of the linked accounts and using it to remove all other accounts linked with the keychain. It also prevents a malicious actor from replacing the unlinked account with their own corresponding account on the same platform, as the unlinking operation will ensure that any existing authentication session cannot be used to re-link and overwrite the entry without authenticating with one of the other linked accounts in the keychain.

These restrictions are in place to limit the potential attack surface related to account theft scenarios.

Using Device ID

This feature is relevant for Mobile personal devices and PC Desktop only. Device ID cannot be used with the Anti-Cheat Interfaces, which require an external account.

In cases where an application believes that users may not yet be invested enough to create a new account or link an existing account, an application may create a new persistent pseudo-account using the EOS Connect Device ID feature. This feature allows an application to create a persistent access credential for a local user without using any external login credentials. This allows the backend services to remember the current user on the local device across game sessions. The Device ID feature is used especially on mobile personal devices to allow automatically logging in a user without prompting for account credentials, as well as allowing to start playing the game without immediately requiring a user login to persist the game progression data.

However, as the Device ID is not tied to a real user account and can only be used to uniquely identify the local device, it is highly recommended to ask the user to link an external authentication method to their Device ID account once a user has progressed through some early progression milestone to prevent losing the credential and thus their account.

Without eventually linking the Device ID account with a real user identity, all progress and game data will be permanently lost should something happen to the device itself. The EOS SDK stores the Device ID credential locally in the keychain of the currently logged in user of the local device. If the local user profile is reset or otherwise lost, it is not possible to recover a lost Device ID after that.

To create a new Device ID, an application must call the EOS_Connect_CreateDeviceId function with a valid EOS_Connect_CreateDeviceIdOptions structure containing the user's DeviceModel. This call will eventually trigger a callback to the function bound to the EOS_Connect_OnCreateDeviceIdCallback. If a new Device ID was successfully created and stored in the keychain for the logged in user of the local device, the ResultCode parameter in the callback parameters will be set to EOS_EResult::EOS_Success. If an existing Device ID was already present, EOS_EResult::EOS_DuplicateNotAllowed is returned. Otherwise, the ResultCode parameter identifies the reason for the operation failure.

To login the local user with their unique Device ID, call the EOS_Connect_Login API with the EOS_EExternalCredentialType::EOS_ECT_DEVICEID_ACCESS_TOKEN external credential type. As the SDK manages the stored Device ID credential automatically, the Token parameter of the input EOS_Connect_Credentials struct must be null. However, as the Device ID is not tied to a real user identity, the EOS_Connect_UserLoginInfo input struct needs to be provided with a valid DisplayName for the user.

To link the local Device ID with a real external user account, first have the game login the local user normally using the Device ID credential type. Then, ask the user to login with a real identity and after EOS_Connect_Login returns back with an EOS_ContinuanceToken, link the external account using the EOS_Connect_Link API to associate the local device with the user's real account. This will allow logging in the user automatically each time the game is started, as the Device ID can still be used as intended to automatically login the user without prompting for external user account credentials.

You may also delete the Device ID for the current user profile of the local device by calling the EOS_Connect_DeleteDeviceId API. The deletion operation is a permanent and nonrecoverable operation. However, it is always possible to create a new Device ID and link it with an existing external user account to restore the automated login functionality.

Linking Device ID Based Game Progression With an Existing Linked Accounts Keychain

There is an edge-case scenario in which the common path to link a Device ID pseudo-account with a real external user account is not possible. In this scenario, the real user account that is logged in, already belongs to an existing keychain under the same EOS Organization. In such case, when the game first automatically logs in the user using the local Device ID login type and then the user logs in with real external user account credentials, the EOS_Connect_Login API will return an existing EOS_ProductUserId instead of an EOS_ContinuanceToken. To handle this specific scenario, the EOS_Connect_TransferDeviceIdAccount API is used.

The Device ID pseudo-account cannot be linked into the existing keychain, as the EOS_Connect_Link API requires the use of an EOS_ContinuanceToken. Additionally, as the player is now faced with two separate EOS_ProductUserIds, the player needs to be given a choice by the game on whether to discard one of the EOS_ProductUserIds (i.e. game profiles) as obsolete and continue to play with the other one. If the player chooses to discard one of the profiles, the game can link the local Device ID account into the existing keychain of linked accounts that is persistent on the backend.

To handle the scenario of two EOS_ProductUserIds, the game needs to recognize when it has logged in the local user using the Device ID login type and then the user, in the same game session, logs in using an external account and receives another EOS_ProductUserId session for it. When this happens, the game should attempt to automatically check whether one of the EOS_ProductUserIds does not have any meaningful game progression on the backend side. In this case, it should automatically discard it and link the local Device ID pseudo-account with the existing keychain of the real external user account.

In case the game is unable to determine this trivial case that can be automated on behalf of the user, it should prompt the user to make a choice on how to proceed. In this dialog, the player should be able to review the game progression as a comparison format for each EOS_ProductUserId and select which one to keep. It should be made very clear to the user that the discarded game progression will be lost forever and cannot be recovered afterwards. The game may also offer the user the option to not discard either profile, and to choose which one to continue playing with for the current game session.

If the user chooses to discard one of their game profiles and switch to another permanently, the game should call the EOS_Connect_TransferDeviceIdAccount API to transfer the local Device ID pseudo-account into the keychain that is linked with the real external user accounts. In the API, input struct EOS_Connect_TransferDeviceIdAccountOptions and set the ProductUserIdToPreserve parameter to point to the correct EOS_ProductUserId value to preserve in the Device ID transfer operation.

Retrieving External Account Mappings

Other interfaces will expect the EOS_ProductUserId for remote or otherwise external users; say a list of friends or players on the same server. It is possible to convert external user account identifiers to the EOS_ProductUserId via the mapping API.

EOS_Connect_QueryExternalAccountMappings is an asynchronous call that will convert external account IDs to the SDK representation. Simply set the EOS_EExternalAccountType and provide a contiguous list of external account IDs in string form.

Pass the EOS_HConnect handle, your EOS_Connect_QueryExternalAccountMappingsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Once the callback has successfully returned, it is possible to retrieve the mappings via EOS_Connect_GetExternalAccountMapping. This function takes the EOS_EExternalAccountType as before and returns a single EOS_ProductUserId for each call that provides an external account ID in string form.

Retrieving Product User ID Mappings

Just as one may retrieve the external mappings for a given product user ID, the converse is also true.

EOS_Connect_QueryProductUserIdMappings is an asynchronous call that will convert EOS_ProductUserIds to their external counterpart on a given platform, along with additional account data including the display name and the last login time. Simply provide a contiguous list of product user IDs.

Pass the EOS_HConnect handle, your EOS_Connect_QueryProductUserIdMappingsOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will execute when the operation finishes.

Once the callback has successfully returned, it is possible to retrieve the mappings via

EOS_Connect_GetProductUserIdMapping. This function takes the EOS_EExternalAccountType, an input buffer, and buffer length to fill with the external account ID. If the buffer is too small, the proper size of the buffer will be returned.

Use EOS_Connect_GetProductUserExternalAccountCount to retrieve the number of linked external accounts for a product user.

Use EOS_Connect_CopyProductUserExternalAccountByIndex to fetch information about an external account linked to a product user using the index.

Use EOS_Connect_CopyProductUserExternalAccountByAccountType to fetch information about an external account of a specific type linked to a product user.

Use EOS_Connect_CopyProductUserExternalAccountByAccountId to fetch information about an external account linked to a product user using the account ID.

Use EOS_Connect_CopyProductUserInfo to fetch information about a product user, using the external account that they most recently logged in with as the reference.

If the product user ID does not map to the given external platform, then the data will not be present in the results returned for the above. This means that the user has never connected that external account type to their product user ID.

User Verification Using an ID Token

ID Tokens are part of the OpenID Connect protocol and can be used to verify a user's identity on server-side. An ID Token is a JSON Web Token (JWT) that contains information about the authenticated user, such as the product user ID. This allows backend services and game servers to securely verify user identifiers it receives from clients.

ID Tokens can not be used to execute actions on behalf of a user. They are only intended for the use of user identity verification.

Retrieving an ID Token For User

Game clients can obtain ID Tokens for local users by calling the EOS_Connect_CopyIdToken SDK API after the user has been authenticated with EOS Connect, passing in a EOS_Connect_CopyIdTokenOptions structure containing the EOS_ProductUserId of the user.

The outputted EOS_Connect_IdToken structure contains the EOS_ProductUserId of the user, and a JWT representing the ID Token data. Note, you must call EOS_Connect_IdToken_Release to release the ID Token structure when you are done with it.

Once retrieved, the game client can then provide the ID Token to another party. A new ID Token is provided after each successful EOS_Connect_Login call.

The ID Token is valid for the lifetime of the local user's EOS Connect authentication session. When the game client refreshes the authentication session, it should expect any earlier used ID Token to expire soon after, and a new ID Token to be used if needed.

Validating ID Tokens on Game Server Using SDK

The JSON Web Key Set (JWKS) endpoint for EOS Connect ID Tokens is: https://api.epicgames.dev/auth/v1/oauth/jwks.

Game servers can validate ID Tokens by calling the EOS_Connect_VerifyIdToken SDK API, and passing in a EOS_Connect_VerifyIdTokenOptions containing the EOS_Connect_IdToken. Note, game servers should use EOS_ProductUserId_FromString to populate the EOS_ProductUserId part of the EOS_Connect_IdToken structure before calling verify, because the server's user handles will be different to the user handles on the client.

Validating ID Tokens on Backend Without SDK

Backend services can verify the validity of ID Tokens and extract the token claims using any of the publicly available standard JWT libraries. See https://jwt.io/ for a list of libraries for this purpose. The used library should allow automatic caching of the retrieved JWKS information for the best performance and to reduce networking overhead.

The EOS SDK and other support libraries take care of the needed steps for securely validating the ID Token before its containing claims can be securely trusted. The steps performed are as following:

  1. Verify that the token signature algorithm ("alg") is present and is not set to "none".

  2. Verify the JWT signature against the expected public certificate using the JWKS endpoint hosted by Epic Online Services.

  3. Verify that the token issuer ("iss") is present and starts with the base URL of https://api.epicgames.dev.

  4. Verify that the token issue time ("iat") is in the past.

  5. Verify that the token expiration time ("exp") is in the future.

  6. Verify that the Client ID ("aud") matches the Client ID that you are using to initialize the EOS SDK with game clients or otherwise to authenticate users with EOS Connect.

After successfully verifying the ID Token you can trust the Product User ID ("sub") value.

ID Token Structure

The ID Token contains the following JSON structures:

Header

Key

Type

Description

alg

string

Signature algorithm.

kid

string

Identifier for the key that was used to sign the token.

Payload

Key

Type

Description

aud

string

Client ID used to authenticate the user with EOS Connect.

exp

integer

Expiration time of the token, seconds since the epoch.

iat

integer

Issue time of the token, seconds since the epoc.

iss

string

Token issuer. Always starts with https://api.epicgames.dev.

sub

string

Product User ID of the authenticated user.

act

json object

Identifies the external account that was used to authenticate the connected user.

External account information (`act`)

Key

Type

Description

eat

string

Identifies the external account type. Possible values include: apple, discord, epicgames, gog, google, itchio, nintendo_id, nintentdo_nsa_id, oculus, openid, psn, steam, xbl

eaid

string

External account ID.

pltfm

string

Platform that the user is connected from. Possible values include: other, playstation, switch, xbox

dty

string

Device Type. Identifies the device that the user is connected from. Can be used to securely verify that the user is connected through a real Console device. Possible values include: PSVITA, PS3, PS4, PS5, Switch, Xbox360, XboxOne