Set up Xbox as an identity provider

Last updated on October 3, 2023

Overview​

This guide helps verified Xbox developers connect Xbox accounts with AccelByte Gaming Services (AGS). You may need to set up additional features not listed here within Xbox services. For full information about setting up Xbox services, we recommend contacting your Xbox representative and reviewing Xbox documentation.

You can request confidential guide materials from your AccelByte Technical Producer.

Goals​

Enable the Xbox authentication method for your game with the AGS SDK, and your publisher website with the AGS Player Portal.

Prerequisites​

Web login integration​

You will need the following for web login integration:

  • Access to Microsoft Azure Active Directory and the permission to create the app registration.
  • An AGS Admin Portal account to set up authentication and manage permissions.
  • If you haven't done so already, set up a publisher namespace for your player portal and launcher.
  • A player portal.

In-game login integration​

You will need the following for in-game login integration:

  • A Microsoft partner account in order to generate the Business Partner Certificate. To register, go to the Microsoft Partner website.
  • If you are using Unreal Engine, you need:
  • If you are using Unity, you need:
    • Windows 10 or 11.
    • Visual Studio 2019 & Visual C++ Build Tools.
    • Windows 10SDL 10.0.19041.0.
    • A (Unity Engine Pro License).
    • The Unity Xbox Add-On for your version of Unity.
    • Xbox GDK Microsoft June 2022 Update GDKX (10.0.22000.4429) & Latest Microsoft Console Recovery.
    • Unity Game Core Support Module.
    • The latest version of the AGS Unity SDK.
    • A Unity game project with an imported AGS SDK..
  • An AGS Admin Portal account to set up authentication and manage permissions.
  • A game namespace.
  • Familiarity with AGS IAM clients.

Set up Xbox Live web login integration​

Azure Active Directory app registration​

Follow the guide for registering an application with the Microsoft identity platform. Under "Who can use this application or access this API", select the option Accounts in any organizational directory (Any Azure AD directory - Multitenant) and personal Microsoft accounts (e.g. Skype, Xbox). Under "Redirect URI (optional)", select Web in the dropdown and then add these URIs:

  • https://<Base-URL>/
  • https://<Base-URL>/player/account/linked-accounts
  • https://<Base-URL>/account/linked-accounts
  • https://<Base-URL>/iam/v3/platforms/xblweb/authenticate
注記

BaseURL is your domain address. Example: https://development.accelbyte.io

Set up Xbox in-game login integration​

Configure web service and relying party on Partner Center​

Configure the web service, certificate, and relying party at the Microsoft Partner Center. Please follow the guide for setting up web services at Partner Center. When Configuring Relying Party, Make sure you include these claims on the token:

  1. Xbox user ID (xid). We recommend you to include xid on token claims. Partner Xbox user ID (ptx) is suitable for account linking, but most GDK and service-to-service (S2S) functions that call to Xbox services (e.g., session, friends, achievements, etc.) require xid. If you have already added xid, don’t add ptx to the claims.
注記

xid is not available by default. You must submit an exception request to Xbox to make it available for token claims.

  1. Gamertag (gtg) or Modern Gamer Tag (mgt). Depending on the implementation for your game, you can choose between gtg or mgt to display your Xbox player name.
  2. Sandbox ID (sbx).
  3. Delegation token (dlt).
  4. Device Pairwise ID (dpi).
  5. Device type (dty).
注記

Please contact your AccelByte Technical Producer for help if you have trouble setting up the web service and relying party on Microsoft Partner Center.

Configure a sandbox​

To configure a sandbox, please follow the setting up sandboxes guide.

Configure a test account​

A test account is useful for your development and testing phases. To configure a test account, follow the creating test account guide.

Configure single sign-on (SSO)​

Please follow the guide for configuring SSO in Partner Center.

Get your title ID and SCID​

Please follow the guide on getting your IDs.

Create an RSA private key for AGS​

  1. Create an RSA Private Key by converting the relying party certificate .pvk into .pem file by executing this command:

    openssl rsa -inform PVK -outform PEM -in <pvk file> -out <pem file>

You need to enter the pass phrase from your xbox.pvk file.

  1. Open the PKCS#1.pem file with any text editor. Your .pem file should begin with "-----BEGIN RSA PRIVATE KEY-----" and end with "-----END RSA PRIVATE KEY-----". Make sure there is no new line after the end tag.

Set up Xbox login method​

Web login​

Use the following steps to set up Xbox web logins in the player portal. This will allow your players to sign in to your player portal using their Xbox Live accounts.

  1. Log in to the AccelByte Admin portal, choose your Publisher Namespace, click Login Method below the User Management sidebar, and click the + Add New button on the right side. AGS Admin Portal - Login Methods list

  2. Click on Xbox Web. Select Xbox Web on login methods list

  3. Fill in Client ID, Client Secret, and Redirect URI.

    • Fill in Client ID with your application (client) ID. You can find it on the App Registrations page in your Azure Active Directory.
    • Fill in Client Secret with the secret value that you get from the Certificates & Secrets section in your app in your Azure Active Directory.
    • Fill in Redirect URI with Your Web Redirect URI: <baseURL> Please be aware not to add "/" at the end of the URL since it can break the implementation. (BaseURL is your domain address. e.g: https://development.accelbyte.io) Xbox Web Config window

  4. You will redirect to the details page. Activate it and it will be usable. Xbox Web activate

User login from Player Portal using Xbox Live account​

Make sure you already set up the Xbox Live Login Method on your Publisher Namespace.

  1. Go to the Player Portal and click Login. AGS player portal homepage

  2. If there’s no Xbox logo displayed, click More login options. AGS player portal login page

  3. Click on Login with Xbox Live. AGS player portal - more login options

  4. You will be redirected to the Microsoft/Live sign in page. Log in with your Xbox Live account. microsoft sign in page

注記

The system asks players to link their Xbox account with an existing or new AccelByte account. AccelByte is working on the ability to enable players to log in to the Player Portal with a headless account.

In-game login​

Use the following steps to set up Xbox in-game login. This will allow your players to sign in to your game using their Xbox accounts.

  1. Go to the Login Methods Menu in the AGS Admin Portal. Click the Add New button. Admin Portal for AGS - Login Methods list

  2. Click on Xbox. Xbox selected on login methods list

  3. Upload your .pem file from the "Create an RSA private key for AGS" section. create Xbox configuration window

  4. You will redirect to the detail page. Activate it and it will usable. Xbox activate in-game login

Create IAM clients​

An Identity and Access Management (IAM) client represents the game client that you want to release on the Xbox platform. With an IAM Client, your game client can request access to protected AGS resources using the appropriate permissions. Learn more about IAM clients by reading the documentation on managing access control for applications.

  1. Go to Platform Configurations, then IAM Clients.

    AGS Admin Portal - IAM clients

  2. Click Create New to create a new IAM client.

    IAM clients page - create a new IAM client

    a. Enter the Client Type. We recommend you use the Confidential client type, since you might need to add some permissions to this IAM Client later for accessing AGS resources. Adequate security is not available if you use the Public client type.

    b. In the Secret field, type the secret yourself or click Generate Client Secret to generate a secret key.

    危険

    The client secret isn't visible after this creation step. It is vital that you copy and save the value as you'll need it when you set up your game configuration.

    c. Fill in the Client Name. You can name it with specific name such as <game name> xbox build, since this IAM Client will be specific for the Xbox platform.

    d. Choose your game Namespace.

    e. For Scopes, you can leave the default value.

    f. For Redirect URI, enter http://127.0.0.1 as it's for the Game Client Build.

    g. You can leave Target Audience blank.

    h. You can also leave BASE URI blank.

    i. You can describe the IAM Client in the Description field.

    j. Platform Input in the SDK Configuration means the Target Platform for your game. In this case, set it to Xbox.

    k. Advanced Configuration consists of additional features, such as 2FA and override expiration time. Since this is for a Game Client build, you can leave these as default / disabled.

    top part of IAM configuration page

    注記

    The client ID will already be generated, so you can copy it. You can use the client ID in your SDK configuration for your game build later on.

    bottom part of IAM configuration page

  3. You will be redirected to the Client Detail page. Please set up the required permissions as you need. For more details about permissions, please refer to the IAM Client permission docs.

    game client IAM details page

    game client IAM permissions page

In-game login instructions​

The setup for each game engine is different. Please choose your game engine from the available tabs.

Unreal in-game login integration​

Preparation and configuration (Unreal)​

Adding dependency​

First, you need to add the public dependency modules called OnlineSubsystem and OnlineSubsystemGDK. These are all the dependencies needed for integrating your project to use the online subsystem for Xbox from within Unreal Engine.

public ABThirdPartyLogin(ReadOnlyTargetRules Target) : base(Target)
{
  PCHUsage = PCHUsageMode.UseExplicitOrSharedPCHs;

  PublicDependencyModuleNames.AddRange(new string[] { "Core", "CoreUObject", "Engine", "InputCore" , "AccelByteUe4Sdk", "Slate", "SlateCore" });

  PrivateDependencyModuleNames.AddRange(new string[] { "Json", "OnlineSubsystem", "OnlineSubsystemGDK", "HTTP" });

}

Add OnlineSubsystemGDK inside <YourProject>.Target.cs

public ABThirdPartyLoginTarget( TargetInfo Target) : base(Target)
{
  Type = TargetType.Editor;
  DefaultBuildSettings = BuildSettingsVersion.V2;
  ExtraModuleNames.AddRange( new string[] { "ABThirdPartyLogin", "OnlineSubsystem", "AccelByteUe4Sdk", "OnlineSubsystemGDK" } );
}

and <YourProjectEditor>.Target.cs

public ABThirdPartyLoginEditorTarget( TargetInfo Target) : base(Target)
{
  Type = TargetType.Editor;
  DefaultBuildSettings = BuildSettingsVersion.V2;
  ExtraModuleNames.AddRange( new string[] { "ABThirdPartyLogin", "OnlineSubsystem", "AccelByteUe4Sdk", "OnlineSubsystemGDK" } );
}

Also Add this to your <YourProject>.Build.cs file

PrivateDependencyModuleNames.AddRange( new string[]
{
    "OnlineSubsystem",
});

if (Target.Platform.Equals(UnrealTargetPlatform.XboxOneGDK))
{
    DynamicallyLoadedModuleNames.AddRange(new string[] { "OnlineSubsystemGDK" } );
}

Create a file on [ProjectPath]/Platforms/XboxOneGDK/Config/XboxOneGDKEngine.ini. Here is an example:

Unreal Engine project settings for Xbox​

Inside your XboxOneGDKEngine.ini file, you need to add several variables for Xbox configuration. You need this configuration to make certain that, when opening the project, Xbox will initiate automatically by default.

To tell Unreal Engine to use Online Subsystem Xbox / GDK, add the following setting:

[OnlineSubsystem]
NativePlatformService=GDK

Now that you've told Unreal Engine that you want your application to use the GDK Online Subsystem, you'll need to configure the OnlineSubsystemGDK module by adding the following settings:

[OnlineSubsystemGDK]
bEnabled=true
LoginXSTSEndpoint="https://example.com"

Note: LoginXSTSEndpoint is the URL you registered on Xbox Live SSO.

Add and fill the tittleId, PrimaryServiceConfigId and PublisherName values as shown below from Microsoft Partner Center.

[/Script/XboxOneGDKPlatformEditor.XboxOneGDKTargetSettings]
TitleId="YOUR TITLE ID"
PrimaryServiceConfigId="YOUR SCID"
PublisherName="CN=<YOUR PUBLISHER NAME>"

Unreal Engine project settings for AGS​

Change the DefaultPlatformService value and add the AccelByte credentials here on DefaultEngine.ini

[OnlineSubsystem]
DefaultPlatformService=GDK

[/Script/AccelByteUe4Sdk.AccelByteSettings]
ClientId=<Your IAM_Client_Id>
ClientSecret=<Your IAM_Client_Secret>
Namespace=<Your Namespace>
PublisherNamespace=<Your Publisher Namespace>
RedirectURI=
BaseUrl="https://demo.accelbyte.io"
IamServerUrl="https://demo.accelbyte.io/iam"
PlatformServerUrl="https://demo.accelbyte.io/platform"

Recommended Settings At the end of this brief guide, your application's DefaultEngine.ini and XboxOneGDKEngine.ini file should look like the following setting block.

DefaultEngine.ini

[OnlineSubsystem]
DefaultPlatformService=GDK

[/Script/AccelByteUe4Sdk.AccelByteSettings]
ClientId=<Your IAM_Client_Id>
ClientSecret=<Your IAM_Client_Secret>
Namespace=<Your Namespace>
PublisherNamespace=<Your Publisher Namespace>
RedirectURI=
BaseUrl="https://demo.accelbyte.io"
IamServerUrl="https://demo.accelbyte.io/iam"
PlatformServerUrl="https://demo.accelbyte.io/platform"

XboxOneGDKEngine.ini

[/Script/XboxOneGDKPlatformEditor.XboxOneGDKTargetSettings]
TitleId="YOUR TITLE ID"
PrimaryServiceConfigId="YOUR SCID"
PublisherName="CN=MY PUBLISHER"

[OnlineSubsystemGDK]
bEnabled=true
LoginXSTSEndpoint="https://example.com"

Sample code implementation (Unreal)​

Next step, we will show you how to implement the Xbox authentication method for your game with sample code below.

The IOnlineSubsystem reads the DefaultPlatformService value defined in DefaultEngine.ini. The IdentityInterface manages interactions with these services related to user accounts, enabling user authentication, and accessing token retrieval. Once the operation is successful, the LoginWithOtherPlatform function of the AccelByte SDK handles third-party platform login using the authentication token obtained from the Identity Interface.

FOnlineAccountCredentials Credentials;
Credentials.Type = TEXT("xsts");

UE_LOG(LogTemp, Warning, TEXT("%s"), TEXT("Begin Login"));
const IOnlineSubsystem* OnlineSubsystem = IOnlineSubsystem::Get();
if (OnlineSubsystem == nullptr) //will get active OSS Platform Service
{
  FString Message = TEXT("Cannot login with no online subsystem set!");
  UE_LOG(LogTemp, Warning, TEXT("%s"), *Message);
  OnActionInfoUpdated.Broadcast(Message);
  return;
}

const IOnlineIdentityPtr OnlineIdentity = OnlineSubsystem->GetIdentityInterface();
if (!OnlineIdentity.IsValid())
{
  FString Message = TEXT("Could not retrieve identity interface from native subsystem.");
  UE_LOG(LogTemp, Warning, TEXT("%s"), *Message);
  return;
}
APlayerController* MyPlayerController = UGameplayStatics::GetPlayerController(GetWorld(), 0);;

const ULocalPlayer* LocalPlayer = Cast<ULocalPlayer>(MyPlayerController->Player);
if (LocalPlayer == nullptr)
{
  FString Message = TEXT("Can only login with native platform for local players");
  UE_LOG(LogTemp, Warning, TEXT("%s"), *Message);
  return;
}
const FVoidHandler OnLoginSuccessDelegate = FVoidHandler::CreateLambda([=]() {
  FAccountUserData AccountUserData = FRegistry::Credentials.GetAccountUserData();

  FString AccountUserDataString;
  FJsonObjectConverter::UStructToJsonObjectString(AccountUserData, AccountUserDataString);

  FString Message = FString::Printf(TEXT("Login to AB Service Success : %s"), *AccountUserDataString);
});
const FCustomErrorHandler OnLoginErrorDelegate = FCustomErrorHandler::CreateLambda([=](int32 ErrorCode, const FString& ErrorMessage, const FJsonObject& ErrorObject) {
     FString Message = FString::Printf(TEXT("Error Login to AB Service : %s"), *ErrorMessage); //Failed Login to AB Service
});
const FOnLoginCompleteDelegate NativeLoginComplete = FOnLoginCompleteDelegate::CreateLambda([=]
(int32 LocalUserNum, bool bWasSuccessful, const FUniqueNetId& UserId, const FString& Error) {
  UE_LOG(LogTemp, Warning, TEXT("OnLoginComplete %s : %s"), bWasSuccessful ? TEXT("Success") : TEXT("Fail"), *Error);
  FString Message = FString::Printf(TEXT("OnLoginComplete %s : %s"), bWasSuccessful ? TEXT("Success") : TEXT("Fail"), *Error);
  OnActionInfoUpdated.Broadcast(Message);

  if (bWasSuccessful)
  {
     FString XboxToken= OSS->GetIdentityInterface()->GetAuthToken(0);
     UE_LOG(LogTemp, Warning, TEXT("PlatformToken : %s"), *PlatformToken);
     OnActionInfoUpdated.Broadcast(FString::Printf(TEXT("PlatformToken : %s"), *PlatformToken)); //Will Obtained Auth Ticket from OnlineIdentity

     FRegistry::User.LoginWithOtherPlatform(EAccelBytePlatformType::Live, XboxToken, OnLoginSuccessDelegate, OnLoginErrorDelegate);
     UE_LOG(LogTemp, Warning, TEXT("Request LoginWithOtherPlatform"));
     OnActionInfoUpdated.Broadcast(TEXT("Request LoginWithOtherPlatform"));
  } //this method will hitting the Accelbyte endpoint and will return value after success
});
OnlineIdentity->AddOnLoginCompleteDelegate_Handle(LocalPlayer->GetControllerId(), NativeLoginComplete);
const bool bWaitForDelegate = OnlineIdentity->Login(LocalPlayer->GetControllerId(), Credentials());
if (!bWaitForDelegate)
{
  FString Message = TEXT("The online subsystem couldn't login");
  UE_LOG(LogTemp, Warning, TEXT("%s"), *Message);
  OnActionInfoUpdated.Broadcast(Message);
}

FString Message = TEXT("Sending login request to native subsystem!");
UE_LOG(LogTemp, Warning, TEXT("%s"), *Message);
OnActionInfoUpdated.Broadcast(Message);

After adding this code to your project, compile your project, and then build and run it.

Project-packaging (Unreal)​

Compile the editor and run it. Click on the Platforms section and Select XB1. Then, click on Package Project.

Sample code testing (Unreal)​

Below we post a screenshot demonstrating that the code works and we are able to log in using an Xbox account on our test app. Unreal Engine Code Testing

に最終更新

On this page