Xbox Service Authorization

Your app uses Xbox service authorization to retrieve information from Xbox web services, as well as from other web services that accept Xbox authorization tokens as relying parties. Further, your app provides a cryptographic signature for each request, so that the receiving server can verify that the request has not been changed in transit. Authorization is provided in the form of a token and signature included in the HTTPS header of each request to the web service. The token supports identity claims on behalf of the user, title, and device, while the signature provides the ability to detect tampering.

The IXMLHTTPRequest2 support class provided by Xbox One automatically inserts an authorization token and signature into HTTPS requests to Xbox Live servers, and can be configured to perform automatic token and signature insertion for HTTPS requests to relying party servers, based on information retrieved from an Xbox Live service.

The user authorization API provides a way to get an encrypted authorization token and request signature for a signed-in Xbox service user so that you can insert the token and signature manually into HTTPS requests that are not using IXMLHTTPRequest2. While manual insertion is still supported in this release, manual insertion adds complexity and an increased test burden to your development efforts. We recommend that your app use automatic insertion of token and signature, which can be accomplished by simply not inserting any token or signature yourself.

Many Xbox service calls are supported with a local wrapper API that encapsulate the process of authorization and calling the web service. When such a wrapper API exists, you should use that API rather than calling the web service. This will simplify your code, making it easier to understand and maintain. Also, the wrapper implementation will be kept up-to-date with any later changes to the service or the authorization process.

To summarize, following are the methods for retrieving web service information, in order of preference and ease of use:

  1. Wrapper API
  2. HTTPS request with automatically inserted authorization token and signature
  3. (Deprecated) HTTPS request with manually inserted authorization token and signature

This topic has the following sections:

Configuring authorization during app development

In Xbox One, all of your app’s content is securely stored and maintained in a single production environment, both during development and after release. This change from earlier Xbox releases provides much greater predictability throughout the various stages of your product’s lifecycle. The ability to test in the production environment is made possible by content isolation—access to your app is limited strictly to authorized development accounts before release. Content isolation requires that every attempt to access data from the Xbox services must be verifiably coming from an account that is authorized to access the isolated data; this fact means that you or your Developer Account Manager (DAM) must configure some Xbox services through the Xbox Developer Portal (XDP) before your app can access Xbox services.

If your app uses Xbox services, or relying-party clients of Xbox services, you must use XDP to create the necessary configuration and sandbox information for your app, including the title ID, which you must include in your app’s manifest.

You must also use XDP to create development accounts and configure their permission to run your app and access resources from your app’s sandbox.

When you configure a new app in XDP, it generates a unique title ID for your app, which you must include in your app manifest. When your app makes an HTTP or HTTPS request to Xbox services or relying party client services by using IXMLHTTPRequest2, the title ID is retrieved from your app’s manifest, a security token is requested on behalf of the signed-in development account, and the received token is automatically inserted into the headers of the request. The inserted token contains a set of digitally signed authorization claims based on the permissions of the signed-in development account that initiated the request and the configuration settings for the app. A cryptographic signature is also added automatically to the request headers.

Tip

What is a relying party client?

A relying-party client is a web service that is not part of the Xbox services security domain, but it relies on the Xbox services security domain to provide credentials for Xbox service users. By relying on Xbox services for authorization, relying party web services can provide a single sign-on (SSO) experience. For more information about SSO, see Single Sign-On.

For relying-party clients that support SSO, you use three facilities provided by Microsoft:

  • An Xbox Security Token Service (XSTS).
    The app configuration you create for your app using XDP determines which services the token authorizes your app to use.
  • A client-side API that obtains the tokens of authenticated Xbox users.
    On Xbox One, this involves either automatic token insertion in HTTPS requests made with IXMLHTTPRequest2, or manual token retrieval with GetTokenAndSignatureAsync followed by manual insertion of the token into the HTTPS request header. Note that the manual method is available, but deprecated. Automatic insertion reduces the coding and testing requirements on your app.
  • The Xbox Live User authorization and Authorization for Relying Parties SDK (RPSDK).
    RPSDK is used by the service that receives requests to process the Xbox Live security tokens and request signature that are passed to it by the client. The RPSDK simplifies the process of authenticating the request and determining authorization and access control based on claims in the issued token. Contact your DAM for access to the RPSDK.

Creating development accounts

XDP is the online tool you use to manage many aspects of your app’s use of the Xbox services. Your organization’s administrators use XDP to create and manage development accounts for your organization. App developers and testers sign in to the dev kit with a development account in order to access the isolated content that is associated with their organization’s products.

Sign in with a development account

To sign in on your dev kit, start the Sign In app and enter the user name and password for a development account that was created previously through XDP.

After you have successfully signed in, the Sign In app reports the controller ID for the controller associated with the User object for your development account, and that User object will be included in the list of User objects returned by the User::Users property.

Making an HTTPS request

In this release, an authorization token and a signature are automatically inserted into all requests that you make to Xbox Live services or properly configured relying third-party services, as long as you don’t attempt to add any token or signature yourself.

While Xbox One provides the capability for you to acquire and manually insert a token and signature into your HTTP requests, we recommend using automatic token and signature insertion because it makes your code easier to understand and maintain. For more information about manual token and signature insertion, see Manual Insertion of Authorization Tokens.

Specifying an actor

In the context of authorization, an actor is the particular user who is responsible for the action being requested by the web service call. For example, if a marketplace service is called to make a purchase, the actor is the signed-in user who is making the purchase. The actor’s account will be charged for the purchase.

To set the actor in an HTTPS request, set the xbl-authz-actor-10 header, providing one of the following results:

In all three cases, device and title claims are included in the authorization token.

See also

Web Services Sample

Network Security Authorization List (NSAL)

RFC822: Standard for ARPA Internet Text Messages

RFC 2616: Hypertext Transfer Protocol – HTTP/1.1