Auth Interface

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 with EOS_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 its ApiVersion variable set to EOS_AUTH_LOGIN_API_LATEST, and its Credentials variable using the EOS_Auth_Credentials type.
Pass your EOS_HAuth, your EOS_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 type EOS_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.
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 and Token input fields should be set to NULL since the SDK manages the refresh_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 code UserCode 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 be NULL, but the Token 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 updated refresh_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 the EOS_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 received refresh_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 an EOS_Auth_LogoutOptions data structure. When the operation completes, your callback EOS_Auth_OnLogoutCallback will run. Initialize your EOS_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 to EOS_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 function EOS_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 to EOS_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 an EOS_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, your EOS_Auth_VerifyUserAuthOptions data structure and your callback information to the function. Provided the EOS_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 to EOS_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 the Type and Token fields of EOS_Auth_ClientCredentials to the EOS_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 the EOS_Auth_Token and then call the EOS_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 the Type and Token fields of the EOS_Auth_ClientCredentials to EOS_LCT_RefreshToken and the refresh token from the environment variable, respectively.

For more help, visit the developer help forum.