Xbox Reconcile Lambda

On this page

When an Xbox identity provider is used to complete a federated login request, FusionAuth will use the configured linking strategy to reconcile the user. FusionAuth will attempt to match the user information returned from the Xbox identity provider to an existing user account or create a new one.

You may optionally utilize a lambda to customize the user and user registration during the authentication event.

When you create a new lambda using the FusionAuth Admin UI, you will be provided an empty function to implement.

Starting in version 1.65.0, you can use attribute mappings to map IdP claims directly to FusionAuth user and registration fields without writing a lambda. Reconcile lambdas and attribute mappings are mutually exclusive. Attempting to configure both on a given IdP results in a validation error.

Lambda Structure#

When you create the lambda with the API, give the function the following signature:

function reconcile(user, registration, userInfo, context) {
  // Lambda code goes here
}

This lambda must contain a function named reconcile that accepts the following parameters:

  • user: the FusionAuth User object. You can modify this object. However, you can't change the email or username attributes after FusionAuth links the user.
  • registration: the FusionAuth UserRegistration object. You can modify this object.
  • userInfo: the response from the Xbox Live XSTS token request. This object is read-only.
  • context: Available since 1.64.0 an object containing the context of the request, including access to secrets. This object is read-only.

The User API and Registration API documentation describe the user and registration objects.

The player claims live in DisplayClaims.xui[0]. The gtg claim holds the gamertag. FusionAuth uses the gamertag as the username. The xid claim holds the Xbox user Id. The agg claim holds the age group: Adult, Teen, or Child.

Example Lambda#

The following lambda stores the gamertag, Xbox user Id, and age group in user.data.xbox. The lambda gives a player in the Teen or Child age group the restricted role. The lambda recalculates the role on every login, so the role goes away when the player becomes an adult. Add the restricted role to your application before you use the lambda.

A lambda that assigns a role from the Xbox age group.
// stores the gamertag and gives players under 18 a restricted role
function reconcile(user, registration, userInfo, context) {
  var claims = userInfo.DisplayClaims.xui[0];
  user.data = user.data || {};
  user.data.xbox = {
    gamertag: claims.gtg,
    xuid: claims.xid,
    ageGroup: claims.agg
  };
  if (!registration) {
    return;
  }
  // recompute on every login so the role goes away once the player turns 18
  var roles = (registration.roles || []).filter(function (role) {
    return role !== 'restricted';
  });
  if (claims.agg !== 'Adult') {
    roles.push('restricted');
  }
  registration.roles = roles;
}

Assigning The Lambda#

Assign the lambda to the Xbox Identity Provider. Navigate to Settings -> Identity Providers , then edit your Xbox Identity Provider. If you haven't configured Xbox yet, click Add provider and select Xbox.