Connect Interface

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

The Connect Interface provides access to the heart of the Epic Online Services (EOS) ecosystem, a user's identity within all the services provided. It is an abstraction of an external identity provider's account for use inside our services. Identity providers include Epic Games, Nintendo, Playstation Network, Steam, XBOX Live, and others. As that list expands, it will be possible to connect a user on any supported platform to their singular account within each individual application.

Each organization will have the ability to associate one or more external user accounts with a single account per application.

Managing Accounts

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

Because we do not control the access permissions of the external provider, this interface is not intended to implicitly refresh tokens or otherwise grant lengthy access. We simply verify the user is still valid with the external account provider and extend the time the user is able to access our services. The external account provider is also expected to have authority over access to the application.

Click to enlarge image.

Access to services available via this account will require account identification via the EOS_ProductUserId data structure. All interfaces will clearly indicate this usage and type safety should be assured. It is separate from EOS_EpicAccountId, which is associated with the authentication interface provided for Epic Games accounts. An Epic Games account is not required to work with this service.

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 the function. 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 External Account), or if they'd like to create a new account (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 will run whenever a local user's authentication status changes. This should only occur 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.

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 account/user 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 simply 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

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 set to 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 a 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.

If 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 choice 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 SDK's representation 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.