Auth Interface

Interface to handle verification of user accounts, including login and logout functionality.

Auth Interface

The Auth interface allows logging in the local user with their Epic account. This enables access to the features provided by Epic Account Services (EAS), such as Friends, Presence, UserInfo and Ecom interfaces. The Auth Interface handles Epic account-related interactions with EOS, providing the ability to authenticate users and obtain access tokens.

To use the Auth Interface, your product must have Epic Account Services (EAS) active, and must obtain [user consent] to access Basic Profile data. You can activate EAS on the [Developer Portal], or learn more in [Epic's documentation]. Without EAS and user consent, you will still be able to initialize the EOS SDK and the Auth Interface, but all Auth Interface function calls to the back-end service will fail.

Authentication Functions

To access authentication functions, you need an EOS_HAuth handle, which you can acquire by calling the

[Platform Interface](Interfaces/Platform)
function, EOS_Platform_GetAuthInterface. Auth Interface functions require this handle to access user information.

Logging In

To begin interacting with EOS's online features, you must first log in with a valid user account. To do this, call the EOS_Auth_Login function with an EOS_Auth_LoginOptions structure containing a local player's account credentials. Whether the login attempt succeeds or fails, your callback function, of type EOS_Auth_OnLoginCallback, will run upon completion.

The EOS_Auth_LoginOptions must be initialized with its ApiVersion variable set to EOS_AUTH_LOGIN_API_LATEST, and its Credentials variable (of type EOS_Auth_Credentials) containing the following information:

Property

Value

ApiVersion

EOS_AUTH_CREDENTIALS_API_LATEST

Id

The identity of the user logging in. Unlike most other functions, this should be a user-readable identity, like an email address or display name.

Token

The user's login credentials or authentication token.

Type

The type of credential that this login attempt is using. [EOS_ELoginCredentialType] lists the available kinds of credentials.

SystemAuthCredentialsOptions

This field is for system specific options, if any are needed.

ExternalType

If Type is set to EOS_LCT_ExternalAuth, this field indicates which external authentication method to use. See [EOS_EExternalCredentialType] for a list of all available methods.

Pass the Auth Interface handle, your EOS_Auth_LoginOptions structure, and your callback information to the function. Provided that the EOS_HPlatform handle is ticking, the callback you provided will run when the operation finishes.

Preferred Login Types for Epic Account

As of SDK 1.5 version, the preferred login types by platform are as follows:

Platform

Login Type

Summary

Console

EOS_LCT_ExternalAuth

Platform access token used to automatically login the platform user to their associated Epic account.

PCs or Mobile Devices

EOS_LCT_AccountPortal with EOS_LCT_PersistentAuth

Web login flow with a locally stored long-lived access token.

Epic Games Launcher

EOS_LCT_ExchangeCode

Exchange code received from the launcher and used to automatically login the user.

Console

Your game retrieves an access token from the platform for the local user account. Using the EOS_LCT_ExternalAuth login type, the platform user is logged into their Epic account. See External Account Authentication for the detailed login flow, and the console specific documentation for the platform code integration.

PC or Mobile Device

PCs and mobile devices usually use persistent logins, enabled by long-lived refresh tokens granted by the authentication backend, and specific to the device and user account. On these platforms, the SDK automatically stores and retrieves these tokens as needed, and updates them following each login. See the section on [persistent logins] for more information.

Epic Games Launcher

When an application associated with the Epic Games Launcher starts, the launcher will provide a command line with several parameters, which will take this format:

-AUTH_LOGIN=unused -AUTH_PASSWORD=<password> -AUTH_TYPE=exchangecode -epicapp=<appid> -epicenv=Prod -EpicPortal  -epicusername=<username> -epicuserid=<userid> -epiclocale=en-US

The important fields of this command line are as follows:

Property

Value

AUTH_LOGIN

This field may be the user ID, but it is presently unused.

AUTH_PASSWORD

This field will be the Exchange Code itself, which should be provided as the Token during login.

AUTH_TYPE

The type will read "exchangecode", indicating that EOS_Auth_LoginCredentials should use the type EOS_LCT_ExchangeCode.

The application must parse this information and pass it into EOS_Auth_Login through the EOS_Auth_Credentials structure. EOS_Auth_Credentials has three variables: Id, Token, and Type. You may leave Id blank, as this login method does not require an ID. For Token, provide the Exchange Code from the AUTH_PASSWORD command line parameter. Finally, Type should be EOS_LCT_ExchangeCode.

Auth Scopes

As of EOS SDK version 1.5, EOS_Auth_LoginOptions contains a new field named ScopeFlags, of type EOS_EAuthScopeFlags (API LINK). Scopes are a set of permissions that are required for your application to function properly. For example, if your application needs to see the user's friends list, then you must request the EOS_AS_FriendsList scope, and the user will be asked to give consent for it during the login flow. If the user does not consent to one of the requested scopes, then the login will fail. When requesting consent, your request must exactly match the scopes configured for the product in the Developer Portal.

Multiple users can be logged in at the same time on a single local device and using the same shared EOS_HPlatform instance

Associating With the Epic Games Launcher

When an application associated with the Epic Games Launcher starts, the launcher will provide a command line with several parameters, which will take this format:

-AUTH_LOGIN=unused -AUTH_PASSWORD=<password> -AUTH_TYPE=exchangecode -epicapp=<appid> -epicenv=Prod -EpicPortal -epicusername=<username>-epicuserid<userid> -epiclocale=en-US

The important fields of this command line are as follows:This information must be parsed by the application and provided to the EOS_Auth_Login through the EOS_Auth_Credentials structure. EOS_Auth_Credentials has three variables: Id, Token, and Type. For the Type, use EOS_LCT_ExchangeCode.

You may leave Id blank, as this field is unused for this login type. Finally, provide the Exchange Code from AUTH_PASSWORD as the Token.

Persisting user login to Epic Account outside Epic Games Launcher

On PC and mobile platforms, to support persistent user login outside of the Epic Games Launcher, use the EOS_LCT_AccountPortal login type.

The SDK automatically receives a refresh token from the authentication backend after a successful login to the user's Epic Account and stores the refresh token in the local keychain of the locally logged-in user on the device. For the local keychain, the SDK uses the secure credentials store provided by the device's operating system.

When automatically logging in the local user, the game should first call EOS_Auth_Login with the EOS_LCT_PersistentAuth login type. The Id and Token input fields should be set to NULL since the SDK manages the long-lived access credentials. The SDK will check for a refresh token in the keychain of the local user, and will automatically use a token, if it finds one, to log the user into their Epic Account. Following a successful login on those platforms, the SDK will automatically update the refresh token in the local keychain.

If EOS_Auth_Login fails for any reason, proceed with the default login method for the platform. If EOS_Auth_Login found a refresh token but failed to log in because the server rejected the token — meaning the call failed for a reason other than not having a token, connection or service issues, or the operation canceling or waiting to retry — the application should delete the token, since it is obsolete and will continue to cause failures in all future sessions. Call EOS_Auth_DeletePersistentAuth to explicitly remove any stored credentials in the local keychain for the user. The application should then proceed to the platform's default login flow.

In the case that a logged-in user wants to disable automatic login, call EOS_Auth_Logout to log out, and EOS_Auth_DeletePersistentAuth to revoke the user's long-lived logon session on the authentication backend. This will also delete the long-lived refresh token from the keychain of the local user.

Logging Out

To log out, call the EOS_Auth_Logout function with an EOS_Auth_LogoutOptions data structure. When the operation completes, your callback function, of type EOS_Auth_OnLogoutCallback, will run. Initialize your EOS_Auth_LogoutOptions structure as follows:

Property

Value

ApiVersion

EOS_AUTH_LOGOUT_API_LATEST

LocalUserId

The EOS_EpicAccountId

Pass the Auth Interface handle, your EOS_Auth_LogoutOptions structure, and your callback function to EOS_Auth_Logout. Provided that the EOS_HPlatform handle is ticking, the callback you provided will run when the operation finishes.

If the EOS_LCT_PersistentAuth login type has been used, be sure to also call the function EOS_Auth_DeletePersistentAuth to revoke the long-lived logon session on the authentication backend. This will also permanently forget the local user login on the local device.

Status Change Notification

The EOS SDK periodically verifies local users' authentication status during the application's lifetime. This helps to make sure that the user hasn't signed in elsewhere or otherwise lost access for reasons external to the application itself. To assure that your application knows whenever a user's authentication status has changed, the Auth Interface invokes a callback of type EOS_Auth_OnLoginStatusChangedCallback upon any such change for any local player. You can attach your own callback function to this process with the EOS_Auth_AddNotifyLoginStatusChanged function.

The EOS_Auth_OnLoginStatusChangedCallback callback function you provide will run whenever a local user's authentication status changes. This includes explicitly logging in and out with the Auth Interface, meaning that you will receive both the callback for the log in (or log out) event as well as this callback.

Connectivity loss during an application's lifetime does not indicate that a user is logged out. The EOS backend will explicitly notify the Auth Interface when a logout event takes place, and this is the only case in which it is safe to assume that the user is officially considered offline. User connectivity problems such as service outages, or local hardware failure can cause various API features to fail. If the game can continue without these interactions, the recommended course of action is to continue playing with the assumption that connectivity may eventually resume without logging the user out.

Checking Current Authentication Status

To check the player's current status on demand, use the EOS_Auth_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.

External Account Authentication

To log in with EOS_Auth_Login using an external account, set Type in EOS_Auth_Credentials to EOS_LCT_ExternalAuth, set ExternalType to an external credential type (See [**EOS_EExternalCredentialType**] for a list of all available methods), and set Token to the external authentication token. For example, if you want to log in with Steam, you would use EOS_ECT_STEAM_APP_TICKET as the ExternalType, and the Token would be the Steam Encrypted Application Ticket.

EOS_InvalidUser will be returned when the external auth login fails due to an external account not being linked. An EOS_ContinuanceToken will be set in the EOS_Auth_LoginCallbackInfo data. EOS_Auth_LinkAccount should be called with the EOS_ContinuanceToken and LinkAccountFlags set to EOS_LA_NoFlags (for most cases where consent is required via the Account Portal or PIN Grant) to continue the external account login and link the external account. Afterwards, the external account will be linked to the user's Epic Account.

The Identity Providers on the Developer Portal will need to be configured for the Product to allow providers to be linked using external account authentication. See Configuring Identity Providers for more information.

![drawing](https://docs.google.com/drawings/d/12345/export/png)

Integrating a Game Launcher with Epic Games Store

If your game provides a launcher to include additional launch options, promotions or other news, then your launcher must manage the login flow. Exchange codes generated by the Epic Games Launcher expire after a short period of time, so care must be taken to prevent the exchange code from expiring. Use the following pattern when the Epic Games Launcher is not directly launching the game application:

  1. The Epic Games Launcher starts the third-party launcher, passing the exchange code on the command line as described above in the section Associating With the Epic Games Launcher

  2. The third-party launcher uses the Exchange Code to login the player by using the EOS_Auth_Login API. Initialize EOS_Auth_LoginOptions by setting the Type and Token fields of the EOS_Auth_ClientCredentials struct to EOS_LCT_ExchangeCode and the exchange code from the command line respectively.

  3. When the player chooses to launch the game, use the EOS_Auth_CopyUserAuthToken API to get a copy of the token details. Copy the RefreshToken from the EOS_Auth_Token and call the EOS_Auth_Token_Release API to free the memory allocated by the SDK.

  4. Pass the refresh token to the game application by setting an environment variable that the game can read on startup. Do not log the player out in the third-party launcher when it exits as this will invalidate the refresh token.

  5. When the game process starts up, the game can log the player in using the EOS_Auth_Login API. Initialize EOS_Auth_LoginOptions by setting the Type and Token fields of the EOS_Auth_ClientCredentials struct to EOS_LCT_RefreshToken and the refresh token from the environment variable respectively.

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 their account 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_Auth_CopyIdToken SDK API after the user has been logged in, passing in a EOS_Auth_CopyIdTokenOptions structure containing the EOS_EpicAccountId of the user.

The outputted EOS_Auth_IdToken structure contains the EOS_EpicAccountId of the user, and a JWT representing the ID Token data. Note, you must call EOS_Auth_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. An ID Token is always readily available for a logged in local user.

Validating ID Tokens on Game Server Using SDK

The JSON Web Key Set (JWKS) endpoint for EOS Auth ID Tokens is: https://api.epicgames.dev/epic/oauth/v1/.well-known/jwks.json.

Game servers can validate ID Tokens by calling the EOS_Auth_VerifyIdToken SDK API, and passing in a EOS_Auth_VerifyIdTokenOptions containing the EOS_Auth_IdToken. Note, game servers should use EOS_EpicAccountId_FromString to populate the EOS_EpicAccountId part of the EOS_Auth_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 Epic Account Services.

After successfully verifying the ID Token you can trust the Epic Account 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.

t

string

Token type. Always set to id_token.

Payload

Key

Type

Description

appid

string

EAS Application ID.

aud

string

Client ID used to authenticate the user with Epic Account Services.

dn

string

Epic Account display name.

exp

integer

Expiration time of the token, seconds since the epoch.

iat

integer

Issue time of the token, seconds since the epoch.

iss

string

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

pfdid

string

EOS Deployment ID.

pfpid

string

EOS Product ID.

pfsid

string

EOS Sandbox ID.

sub

string

Epic Account ID of the authenticated user.