Setup with Passport

This guide will walk you through setting up Immutable Passport in your Unreal game.

Prerequisites

Before you start, make sure you have:

• Unreal Engine installed (see engine compatibility below)
• An Immutable Hub account
• Git LFS installed (required for .uasset and .umap files)

Installation

⚠️Warning

Please make sure your project is properly configured in the Immutable Hub before attempting to log in to Passport, especially if you're developing your game in Unreal Engine 4.26, 4.27, or 5.0. Pay special attention when configuring Web Origins URLs.

💡BLUI Plugin

More on why we use BLUI plugin can be found in the FAQ

⚠️Plugin Compatibility

The Xsolla plugin is not compatible with the Immutable plugin. For more information, please refer to the FAQ

1. Since .uasset and .umap files are stored on Git Large File Storage, you must download and install git-lfs from here before cloning the respository
2. Clone the unreal-immutable-sdk repository or download the zip/tarball from one of the versions here
3. Copy the cloned repo into your project's Plugins folder, e.g.: MyGame/Plugins/unreal-immutable-sdk
4. Restart your project (Unreal Editor & Jetbrains Rider IDE), upon restart it should load the unreal-sdk-plugin and should be good to use

💡Unreal Engine 4 and 5.0 additional requirements

• For Unreal Engine 4.26, 4.27, and 5.0, we use BLUI plugin instead of WebBrowserWidget plugin.
• Please disable WebBrowserWidget plugin in the immutable.uplugin file, which can be found at the root of the unreal-immutable-sdk folder, e.g. MyGame/Plugins/unreal-immutable-sdk/immutable.uplugin, and restart your UE4 editor.

  {
    "Plugins": [
    {
     "Name": "WebBrowserWidget"
     "Enabled": false
    }
   ]
  }

• Download or clone BLUI from https://github.com/immutable/immutable-BLUI to your project's Plugins folder. Then rename the folder immutable-BLUI folder to BLUI. Your projects plugin directory should look like

  MyGame/
  |__Plugins/
    |__BLUI/
    |__unreal-immutable-sdk/
  

Artefacts

💡Info

If you encounter compilation errors or any issues integrating with the Immutable plugin, you can report them directly through the issues section in our GitHub repository.

Registering Your Game

Authentication methods

There are two methods to authenticate and authorise players into Passport:

⚠️Warning

Android and iOS are not officially supported.

💡Recommendation

Whenever possible, use the PKCE flow as it is the most secure and seamless method for authentication.

1. Authorisation Code Flow with Proof Key for Code Exchange (PKCE) provides a seamless and secure authentication experience by opening a pop-up window on desktop or an in-app browser on mobile devices. Players are automatically redirected back to the game once authenticated, eliminating manual switching.

2. Device Code Authorisation opens the player's default browser and guides them through the authentication flow.

Configure your application in Immutable Hub

To configure your application, follow these steps: head to the Immutable Hub and proceed with the following:

1. Go to the Immutable Hub and create a new project along with a testnet environment.
2. Register your application as an OAuth 2.0 Native client
3. Go to the Passport configuration screen and create a Passport client for the testnet environment you just set up. Refer to the table below for guidance.

PKCE (Recommended)

Property	Field Required	Description
Application Type	Yes	You must register your application as an OAuth 2.0 Native client.
Client Name	Yes	The name you wish to use to identify your application.
Logout URLs	Yes	The deep link where the browser will redirect to after logout is complete. It can be mygame://logout. Note: replace mygame with your application name.
Redirect URLs	Yes	The deep link where the browser will redirect to after login is complete. It can be mygame://callback. Note: replace mygame with your application name.
Web Origin URLs	Depends	- For Unreal Engine versions 4.26 - 5.0 (inclusive). Add file://* to the list of Web Origins URLs. This is required to work with BLUI browser. - For Unreal Engine 5.1 and above you may leave it blank.

Device Code Authorisation

Property	Field Required	Description
Application Type	Yes	You must register your application as an OAuth 2.0 Native client.
Client Name	Yes	The name you wish to use to identify your application.
Logout URLs	Yes	The http link where the browser will redirect to after logout is complete. It can be a link to your website, https://localhost:3000, or the same as Redirect URLs.
Redirect URLs	Yes	The http link where the browser will redirect to after login is complete. This field is not used, but is required. It can be a link to your website, https://localhost:3000 or Logout URLs
Web Origin URLs	Depends	- For Unreal Engine versions 4.26 - 5.0 (inclusive). Add file://* to the list of Web Origins URLs. This is required to work with BLUI browser. - For Unreal Engine 5.1 and above you may leave it blank.

5. If you're using PKCE, you'll need to follow additional platform-specific steps. Please refer to the collapsible sections corresponding to your platform.

   ⚠️Warning

   Android and iOS are not officially supported.
   💡Tip

   See the Sample Game for an example of how to set up Device Code Authorisation Flow on Windows and macOS.
   Android

   1. Create an Unreal Plugin Language XML file (e.g. Source/MyGame/MyGame_UPL_Android.xml) and add the following code:

   <?xml version="1.0" encoding="utf-8"?>
   <root xmlns:android="http://schemas.android.com/apk/res/android">
       <androidManifestUpdates>
           <addElements tag="application">
               <activity
                       android:name="com.immutable.unreal.RedirectActivity"
                       android:exported="true" >
                   <intent-filter android:autoVerify="true">
                       <action android:name="android.intent.action.VIEW" />
                       <category android:name="android.intent.category.DEFAULT" />
                       <category android:name="android.intent.category.BROWSABLE" />
                       <data android:host="callback" android:scheme="mygame" />
                       <data android:host="logout" android:scheme="mygame" />
                   </intent-filter>
               </activity>
           </addElements>
       </androidManifestUpdates>
   </root>

   2. Open your game's build file (e.g. Source/MyGame/MyGame.Build.cs) and add:

   if (Target.Platform == UnrealTargetPlatform.Android)
   {
     string MyPath = Utils.MakePathRelativeTo(ModuleDirectory, Target.RelativeEnginePath);
     AdditionalPropertiesForReceipt.Add("AndroidPlugin", Path.Combine(MyPath, "MyGame_UPL_Android.xml"));
   }

   Your game will now open when the device processes any link that starts with mygame://callback or mygame://logout.

   iOS

   1. In Unreal Editor go to Project Settings -> iOS -> Extra PList Data
   2. Add the following code inside the Additional Plist Data field:

   <key>CFBundleURLTypes</key><array><dict><key>CFBundleURLSchemes</key><array><string>mygame</string></array></dict></array>

   After this set-up and the redirect URI you set in Initialize Passport, your game can log in using mygame://callback.

   macOS

   Since there is no way to add extra plist data like iOS from the Unreal Editor Project Settings, you will need to edit the Engine's default Info.plist.

   1. In your preferred IDE, open the engine's Info.plist file (e.g. Engine/Source/Runtime/Launch/Resources/Mac/Info.plist)
   2. Add the following code inside the root <dict>...</dict>:

   <key>CFBundleURLTypes</key>
   <array>
       <dict>
           <key>CFBundleURLSchemes</key>
           <array>
               <string>mygame</string>
           </array>
       </dict>
   </array>

   After setting up and specifying the redirect URI in Initialize Passport, the user will be automatically redirected back to the game through mygame://callback upon completing the login process.

Next Steps

Once you've completed the setup, you can proceed to login to start authenticating users with Passport.