Skip to main content

User Authentication

Best practices​

We recommend creating a new game-instance based subsystem (e.g. ModioManagerSubsystem) that depends on ModioSubsystem, and is responsible for managing the full initialization and authentication flow for your game.

  • Create a subsystem to manage mod.io initialization and authentication.
  • Perform Online Subsystem (OSS) login in your subsystem's Initialize function to ensure you have a valid platform auth token ready when its time to authenticate to mod.io using single sign-on (SSO).
    • Log in with the online identity provider.
    • On success, get a linked account token for the current user.
    • On success, get an authentication token from the linked account or from the online identity.
  • Initialize the mod.io plugin with the required environment parameters for the current platform.
  • Display the mod.io Terms of Service. Ensure they are accepted by the user.
  • Authenticate the user using SSO.
note

If the Online Subsystem login fails at any point in the above process, fall back to simply initializing the plugin and offer email authentication as an alternative.

Terms & user consent​

Users must accept the mod.io Terms of Service before using any mod.io services. The Terms of Service can be fetched from mod.io using GetTermsOfUseAsync. Before attempting authentication, ensure these terms are displayed to and accepted by the user.

See our full Terms & User Consent documentation for further details.

When authenticating via SSO, the bUserHasAcceptedTerms parameter should be set to false by default. If the user has already accepted the latest terms, they will be authenticated automatically. If they haven't accepted the latest terms, an error 403 Forbidden (error_ref 11074) will be returned. When you receive this error, you must display the terms dialog to the user, and if they accept, resubmit the authentication flow with bUserHasAcceptedTerms set to true for that specific request only. All subsequent authentication attempts should revert to using false for this parameter.

Authentication methods​

The mod.io Unreal Engine plugin provides two ways for users to create an account to use the service: email authentication, and single sign-on (SSO) through an external authentication partner.

tip

For the best user experience, we recommend using SSO wherever possible.

Email authentication​

Users can authenticate to mod.io with just an email address. This involves:

  • Requesting a one-time authentication code be sent from mod.io to an email address provided by the user.
  • Submitting the received code to mod.io.

Requesting an authentication code​

Request a one-time authentication code by calling RequestEmailAuthCodeAsync. Pass in a user-provided email address as the first argument.

void UModioManagerSubsystem::RequestEmailAuthCode(const FString &EmailAddress)
{
   if (UModioSubsystem* Subsystem = GEngine->GetEngineSubsystem<UModioSubsystem>())
   {
   	Subsystem->RequestEmailAuthCodeAsync(FModioEmailAddress(*EmailAddress), FOnErrorOnlyDelegateFast::CreateUObject(this, &UModioManagerSubsystem::OnRequestEmailAuthCodeComplete));
   }
}

void UModioManagerSubsystem::OnRequestEmailAuthCodeComplete(FModioErrorCode ErrorCode)
{
   UE_LOG(LogModioGame, Log, TEXT("Email auth code request complete with result: %s"), *ErrorCode.GetErrorMessage());
}

When your callback is invoked, inspect the ModioErrorCode for a successful result. On success, prompt the user to check their emails and enter the authentication code they have received into your game.

Submitting an authentication code​

To finalize the user's authentication, submit the code they have entered to mod.io by calling AuthenticateUserEmailAsync. Pass the user's code in as the first argument.

authenticate_user_email

When your callback is invoked, inspect the ModioErrorCode for a successful result. On success, user authentication is complete.

Single sign-on authentication​

The mod.io Unreal Engine plugin features single sign-on (SSO) authentication from a number of external providers. These include:

note

OpenID is a premium feature. If you are interested in mod.io premium features, please contact developers@mod.io.

Each platform has their own requirements and prerequisites for performing SSO. Platform-specific authentication can be found in the respective platform documentation. SSO is performed by calling AuthenticateUserExternalAsync. This function takes a ModioAuthenticationParams containing provider-specific parameters, and a ModioAuthenticationProvider indicating the provider you're using.

Unreal Engine's Online Subsystem provides a convenient way to get a token for ModioAuthenticationParams.AuthToken. GetDefaultAuthProviderForCurrentPlatform can be used to get the default provider for the current platform.

note

The plugin will automatically URL encode parameters (such as the auth token) when making the request.

authenticate_user_email

Using the Unreal Online Subsystem​

Since Unreal Engine 5.2, most of the authentication methods supported by mod.io are abstracted by Unreal's Online Subsystem. Below are some code snippets demonstrating the flow to get a linked account token from Unreal's Online Subsystem.

  • Create a subsystem to manage mod.io initialization and authentication that depends on the ModioSubsystem. During your subsystem's initialization, perform an Online Subsystem (OSS) login. This guarantees you will have a valid platform auth token ready when needed for mod.io SSO authentication.
const IOnlineSubsystem* OnlineSubsystem = IOnlineSubsystem::GetByPlatform();
if (OnlineSubsystem != nullptr && OnlineSubsystem->GetIdentityInterface() != nullptr)
{
   // Get the Identity interface from our OnlineSubsystem and perform login
   const IOnlineIdentityPtr OnlineIdentity = OnlineSubsystem->GetIdentityInterface();
   OnlineIdentity->AddOnLoginCompleteDelegate_Handle(
   	0, FOnLoginCompleteDelegate::CreateLambda(
   		   [this](int32 LocalUserNum, bool bWasSuccessful, const FUniqueNetId& UserId, const FString& Error) {
   			   this->OnSubsystemLoginComplete(LocalUserNum, bWasSuccessful, UserId, Error);
   		   }));
   OnlineIdentity->Login(0, FOnlineAccountCredentials());
}
else
{
   // If we don't have a valid OnlineSubsystem, just initialize the mod.io plugin
   InitializeModio();
}
  • After a successful OSS login, request the linked account token.
void UModioManagerSubsystem::OnSubsystemLoginComplete(int32 LocalUserNum, bool bWasSuccessful, const FUniqueNetId& UserId, const FString& Error)
{
   if (bWasSuccessful)
   {
   	auto OnlineIdentity = IOnlineSubsystem::GetByPlatform()->GetIdentityInterface();
   	OnlineIdentity->GetLinkedAccountAuthToken(0, FString(), IOnlineIdentity::FOnGetLinkedAccountAuthTokenCompleteDelegate::CreateUObject(this, &UModioManagerSubsystem::OnGetLinkedAccountTokenComplete)); 
   }
}
  • On success, the callback received from GetLinkedAccountAuthToken will contain a token that you can use to perform SSO. This will contain either a byte array TokenData (e.g. for Steam SSO) or TokenString for a plaintext string. These need to be handled appropriately.
void UModioManagerSubsystem::OnGetLinkedAccountTokenComplete(int LocalUserNum, bool bWasSuccessful, const FExternalAuthToken& AuthToken)
{
   if (AuthToken.IsValid())
   {
   	if (AuthToken.HasTokenData())
   	{
   		AuthTokenString = FBase64::Encode(AuthToken.TokenData);		
   	} 
   	else if (AuthToken.HasTokenString())
   	{
   		AuthTokenString = AuthToken.TokenString;
   	}
   }
}

Token Lifetime & Re-Authentication​

By default, tokens issued via email token exchange have a lifetime of 1 year. You can verify that a user has been successfully authenticated with VerifyUserAuthenticationAsync.

If a user is not authenticated for any reason (e.g. their token has been invalidated by changing their password, or their profile data has been removed from their device) then you should prompt them to re-authenticate.