By Peter Gustafson
The Auth Interface handles account-related interactions with Epic Account Services (EAS) to authenticate you and obtain access tokens.
- Activate EAS in your Product page at the Developer Portal.
- Configure Client Credentials under your Product’s Client Management settings.
- You can initialize the EOS SDK and use it normally. However, any attempts to use the Auth Interface will fail if EAS has not been activated, or the EAS Application has not been configured with permissions or linked clients.
- Using EAS will also require configuring Brand Settings, including an Application name and logo.
Warning: the Auth Interface is restricted to members of your organization until a Brand Review has been completed.
Authentication Functions
To access the authentication functions, get your EOS_HAuth
handle by calling the Platform Interface function EOS_Platform_GetAuthInterface
.
Login
- Make a call to the
EOS_Auth_Login
withEOS_Auth_LoginOptions
containing your account credentials. - Whether the login attempt succeeds or fails, your callback of
EOS_Auth_OnLoginCallback
will get invoked upon completion. - The
EOS_Auth_LoginOptions
must be initialized with itsApiVersion
variable set toEOS_AUTH_LOGIN_API_LATEST
, and itsCredentials
variable using theEOS_Auth_Credentials
type. - Pass your
EOS_HAuth
, yourEOS_Auth_LoginOptions
, and your callback information to the function. - Provided the
EOS_HPlatform
handle is ticking, the callback will get automatically invoked when the operation completes, either successfully or with an error.
Multi-users
Multiple users can be logged in simultaneously on a single local device using the same shared EOS_HPlatform
instance.
Add the following parameters in your call to login multiple users:
Parameter | Description |
---|---|
ApiVersion | Set to EOS_AUTH_LOGIN_API_LATEST |
Id | Set to NULL except when logging in using the Developer Authentication Tool. |
Token | The authentication token exchange code or similar input parameter based on the EOS_ExternalCredentialType. |
Type | The type of credential this login attempt is using. See EOS_ExternalCredentialType for methods. |
SystemAuthCredentialsOptions | This field is for system specific options if 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. |
Automatic Login
To simplify login, the game should always attempt to first automatically login the previously seen local Epic account at game startup by calling EOS_Auth_Login
with the EOS_LCT_PersistentAuth
login type.
- When a local user has already logged in and played the game at an earlier time, a previously stored long-lived refresh token will be available and allow the user to automatically login without prompting them for their account credentials.
- If the automatic login attempt fails due to a missing refresh token or a rejected login attempt, the game can ask the user to login by calling
EOS_LCT_AccountPortal
with the login typeEOS_LCT_PersistentAuth
.- This will take the user to the Epic Account login flow after which on successful login the game will receive an authentication session for the user and the refresh token for
EOS_LCT_PersistentAuth
for the next game process session.
- This will take the user to the Epic Account login flow after which on successful login the game will receive an authentication session for the user and the refresh token for
- The game can also forget about the local user by calling the
EOS_Auth_DeletePersistentAuth
. - If
EOS_Auth_Login
fails for any reason, proceed with the default login method for the platform.
For further information and examples, visit the developer help forum.
PC & Mobile Device
PCs and mobile devices use a refresh_token
granted by the authentication backend, and specific to the device and user account.
- On these platforms, the SDK automatically stores, retrieves, and updates tokens.
- The
Id
andToken
input fields should be set toNULL
since the SDK manages therefresh_token
credentials. - The SDK checks for a
refresh_token
in the OS credential store of the local user. - Following a successful login, the SDK automatically updates the
refresh_token
in the local keychain. - If your login fails due to invalid
refresh_token
the SDK automatically deletes the token from the local keychain as obsolete. This can happen if the user changes their account password outside the game which will cause any existing cached sessions to be invalidated.
Console
When using the EOS_LCT_DeviceCode
Console login type, an additional callback is made by the EOS_Auth_Login
API at the beginning of the login flow.
- In the first callback, an
EOS_Auth_PinGrantInfo
data structure is returned. It contains the PIN codeUserCode
and the website URI the application needs to use a separate device, such as a mobile phone or PC. - In versions 1.5 and higher, a new field named
VerificationURIComplete
allows login directly. For example, it can be used in a hyperlink or be rendered as a QR code to be scanned by a mobile phone. - The
Id
field should beNULL
, but theToken
field should point to the refresh token string from a previous login. - Following a successful console login, the application calls
EOS_Auth_CopyUserAuthToken
to retrieve an updatedrefresh_token
and overwrite the previous one in the console’s storage device. - If login fails due to the refresh_token having become invalid, the game should forget about the cached
refresh_token
as obsolete. This happens when a user changes their account password outside of the game which causes any existing cached sessions to be invalidated.
Epic Games Launcher
When an application associated with the Epic Games Launcher starts, it provides a command line using parameters below:
Parameter | Description |
---|---|
AUTH_PASSWORD | Exchange Code field provided as a token during login. |
AUTH_TYPE | The type will read exchangecode indicating that EOS_Auth_LoginCredentials should use the EOS_LCT_ExchangeCode type. |
Example
AUTH_PASSWORD=<password>
AUTH_TYPE=exchangecode -epicapp=<appid>
epicenv=Prod -EpicPortal -epicusername=
<username> -epicuserid=<userid> -epiclocale=en-US
- The application parses this information and passes it to
EOS_Auth_Login
through theEOS_Auth_Credentials
structure. - The
EOS_Auth_Credentials
have three variables in the following table:
Variable | Value |
---|---|
Id | Leave Id blank. |
Token | Use the Exchange Code from the AUTH_PASSWORD parameter. |
Type | Set to EOS_LCT_ExchangeCode . |
Login Outside the Epic Games Launcher
Logging in outside of the Epic Games Launcher is useful for:
- Persisting login outside of the Epic Games Launcher.
- Supporting multiple logins on PC outside of the Epic Games Launcher.
- Assisting sample apps testing.
The EOS_LCT_AccountPortal
login type is used in conjunction with EOS_LCT_PersistentAuth
to support persistent login outside of the Epic Games Launcher.
The Id
and Token
input fields should be set to NULL
since the SDK manages the long-lived access credentials. Refresh token functionality is as follows:
- The SDK sets a
refresh_token
after you login to your Epic Account. - On PC and mobile platforms, the SDK automatically stores the
refresh_token
in the local keychain on your device. - On consoles, call the
EOS_Auth_CopyUserAuthToken
to retrieve the receivedrefresh_token
value.
It’s important to store the refresh_token
for logged-in users of the device and on a per-user basis.
Warning: if multiple users share the same local system, the application will not be able to distinguish between previously logged users and will only remember the last seen user.
Log Out
- To log out, make a call to
EOS_Auth_Logout
with anEOS_Auth_LogoutOptions
data structure. When the operation completes, your callbackEOS_Auth_OnLogoutCallback
will run. Initialize yourEOS_Auth_LogoutOptions
structure as follows:
Parameter | Description |
---|---|
ApiVersion | Set to EOS_AUTH_LOGOUT_API_LATEST . |
LocalUserId | Use EOS_EpicAccountId . |
Type | Set to EOS_LCT_ExchangeCode . |
- Pass your
EOS_HAuth
,EOS_Auth_LogoutOptions
structure, and your callback function toEOS_Auth_Logout
. - Provided the
EOS_HPlatform
handle is ticking, the callback will get automatically invoked when the operation completes, either successfully or with an error. - If the
EOS_LCT_PersistentAuth
login type has been used, call the functionEOS_Auth_DeletePersistentAuth
to revoke the cached authentication as well.
Warning: this permanently erases the local user login on PC Desktop and Mobile.
Failures
If EOS_Auth_Login
fails for any reason, proceed with the default login method for the platform.
PCs and mobile devices
Call EOS_Auth_DeletePersistentAuth
to remove any stored credentials for the local user. This will delete the refresh_token
from the OS credential store of the local user.
Consoles
- Start by revoking your
refresh_token
by making a call toEOS_Auth_DeletePersistentAuth
. - Delete the stored token from local storage.
- The application resets to the platform’s default login flow.
To disable the automatic login, make a call to EOS_Auth_Logout
to log out.
Auth Scopes
EOS_Auth_LoginOptions
contains a new field named ScopeFlags
, of type EOS_EAuthScopeFlags
.
- Scopes are sets of permissions required for your application to function properly.
- For example, if your application needs access to your friend’s list, you must request the
EOS_AS_FriendsList
scope consent. - When requesting consent, your request must match the scopes configured for the product in the Developer Portal.
Status Change Notifications
The EOS SDK periodically verifies your local user authentication status during the application’s lifetime. Below are details:
Function | Description |
---|---|
EOS_Auth_OnLoginStatusChangedCallback | The Auth Interface invokes this notification when a local user authentication status changes. |
EOS_Auth_AddNotifyLoginStatusChanged | Attach your own callback function to this process by using EOS_Auth_AddNotifyLoginStatusChanged . |
Connectivity
Connectivity loss during an application’s lifetime doesn’t mean a user is logged out. When a logout event takes place, the EOS backend notifies the Auth Interface. This is the only case when a user is officially considered offline.
Checking Current Authentication Status
To check a current player’s status, use the EOS_Auth_GetLoginStatus function.
Verifying Authentication
Some Epic users want to verify a remote user’s identity. For example, when a user attempts to join a dedicated server. Use the steps below:
- Call
EOS_Auth_VerifyUserAuth
with anEOS_Auth_VerifyUserAuthOptions
to verify the user’s authentication status. - Initialize your
EOS_Auth_VerifyUserAuthOptions
structure by using these parameters in your call:
Parameter | Description |
---|---|
ApiVersion | Set to EOS_AUTH_VERIFYUSERAUTH_API_LATEST . |
AuthToken | EOS_Auth_Token type used by the remote user. |
- Next, pass your
EOS_HAuth
, yourEOS_Auth_VerifyUserAuthOptions
data structure and your callback information to the function. Provided theEOS_HPlatform
handle is ticking, success or errors are the responses.
The EOS_Auth_OnVerifyUserAuthCallback
returns the user information with the EOS_Auth_VerifyUserAuthCallbackInfo
structure. If a failure occurs, remove the user from the server and try again.
External Account Authentication
To login with EOS_Auth_Login
using an external account:
- Set the Type in
EOS_Auth_Credentials
toEOS_LCT_ExternalAuth
. - Update the
ExternalType
to an external credential type. - Assign the Token to the external authentication token.
Steam Login
For Steam use EOS_ECT_STEAM_APP_TICKET
as the ExternalType
. Set the Token to Encrypted Steam App Ticket.
When an external account isn’t linked during authentication flow, the Account Portal enables authentication to continue after login. Once authenticated, the external account is linked to your Epic Account.
Tip: the Identity Providers settings in the Developer Portal must be enabled to link the providers using external account authentication. See Configuring Identity Providers for more information.
Integrate Game Launcher With Epic Games Store
If your game provides additional launch options, promotions, or other news, keep in mind your launcher must manage the login flow in the following steps:
- Initialize
EOS_Auth_LoginOptions
by setting theType
andToken
fields ofEOS_Auth_ClientCredentials
to theEOS_LCT_ExchangeCode
and the exchange code from the command line, respectively. - Launch a game by using the
EOS_Auth_CopyUserAuthToken
API to get a copy of the token details. - Copy the
refresh_token
from theEOS_Auth_Token
and then call theEOS_Auth_Token_Release
API to free the memory allocated by the SDK. - Pass the
refresh_token
to the game application by setting an environment variable that the game can read on startup. - When the game starts, login another player with the
EOS_Auth_Login
API. - Initialize
EOS_Auth_LoginOptions
by setting theType
andToken
fields of theEOS_Auth_ClientCredentials
toEOS_LCT_RefreshToken
and the refresh token from the environment variable, respectively.
For more help, visit the developer help forum.