Single Sign-On

By relying on Xbox services for authorization, relying party web services can provide a single sign-on (SSO) experience—after a user has signed in to Xbox, he or she is able to access information from the relying-party web services without being required to provide additional user IDs or passwords. As a game developer, you might implement a relying party web service to maintain a player’s customization data in your own system.

The Relying Party SDK and the Xbox One Simple Web Server, a sample, are available for download on the Xbox Game Developer (XGD) site at Xbox One XDK Software Downloads.

Additionally, two white papers available for download from XGD, “Xbox One Title, XSTS Tokens, and Web Services” and “Understanding Security Tokens for Xbox One,” provide detailed information on Xbox Secure Token Service (XSTS) tokens.

To implement SSO

  1. From your web site, expose an SSO endpoint that processes JSON Web Tokens (JWT) by doing one of the following:
    • Reuse an existing Xbox 360 SSO endpoint: If you have an existing Xbox 360 SSO endpoint, you can use the same endpoint for Xbox One SSO. To do so, you must replace the 1,024-bit Xbox 360 partner encryption certificate with a 2,048-bit Xbox One encryption certificate. The advantage of this method is that you will need to handle only one certificate on the backend for both Xbox One and Xbox 360. However, the backend change will prop a new STS definition, which will likely create a temporary outage of the Xbox 360 SSO endpoint.
    • Create a new Xbox One SSO endpoint: You can create a new Xbox One SSO endpoint with a 2,048-bit encryption certificate. If you have an existing Xbox 360 SSO endpoint, you will need to handle two certificates on the backend. However, this method will not create an outage of the Xbox 360 SSO endpoint.
  2. Configure your Network Security Authorization List (NSAL). The SSO endpoint and security certification should be fully qualified (not contain a wildcard).
  3. From your app, use WinJS.xhr to call the SSO endpoint. Xbox One automatically inserts authorization tokens into the HTTP request.

Determining which users are currently signed on to SSO

User is a static user object—it does not represent actual users. However, you can listen for sign-in and sign-out events on the User object to detect user changes. The arguments for these events contain the User object that was signed in or out. You can also get the collection of current users through the User.Users property. You can get the user that is using a specified gamepad through the Gamepad.Gamepads property.

Testing in the publisher sandbox

Xbox One utilizes separate sandboxes for publisher testing, certification testing, and retail.

Sandbox isolation

Publisher sandboxes are currently enabled for user-based security only. In order to make a successful call on the publisher sandbox, a user, not a guest, must be signed in. The behavior of publisher sandboxes is different than certification and retail sandboxes. Certification and retail sandboxes use device-based security. The reason for this is that at the point of being certified and going into retail, an app is public and there is no need for that extra security. User-based security is necessary for publisher sandboxes to keep their app private and secure. Allowing only specific dev accounts to access the app ensures this security.

NSAL.json

NSAL.json allows a guest user to launch an app and make http calls. It is a good practice to test your app with a signed in user before installing NSAL.json. NSAL.json will override the configuration in Xbox Developer Portal (XDP). Test with a signed in user to confirm that the XDP config is properly set up. If the app receives tokens and web calls succeed then you can move on to testing with NSAL.json.

Once you have tested a signed in user, it is possible to test without a user signed in by using the NSAL.json file. When creating the NSAL.json file, be sure that it matches exactly the configuration in XDP. For example, if the Relying Party URI has a ‘/’ at the end, the NSAL.json file must match that. The file must contain the exact configuration that is set up in XDP or else it will override the XDP NSAL.

After setting up the NSAL.json file, deploy it to your dev kit’s drive (xbcp xs:\nsal.json). This will let a guest user launch the app and make http calls.

MSA configuration

Configuring the Microsoft Security Account (MSA) is crucial to implementing SSO. If the account has not been properly set up, then token calls will not work. The MSA ties the identity element in the manifest to the SSO configuration in XDP. The MSA account puts you in charge of the password that locks down the key used to generate the PWID and Device PWID. After you have configured the MSA, the Identity Name and Publisher need to be updated and accurately entered into the app manifest.

SSO best practices

SSO is the only means of user authentication allowed on the Xbox One. It pairs the subscriber’s identity with the Xbox Live identity. When the user signs-in with Xbox Live, the JSON Web Token (JWT) is sent to the publisher’s authentication web service, the token is mapped to the user’s subscription account, and the user is authorized. This removes the need for the user to re-enter their subscription username and password every time the app is launched by the user.

Creating an SSO Mapping

  1. The subscriber launches an app
  2. The app should obtain an XSTS token and send it to the publisher’s authorization service
  3. When the publisher’s authorization service receives the token, it should parses the token, take the user pairwise ID claim (PWID), and do a lookup in their identity database to find a mapped subscription account.
    • If a valid subscription is found, then the user is authorized. The authentication service should return a SESSION cookie (that is, a non-persisted cookie) to the app. The app should use the session cookie to authorize subsequent web calls.

      Note We that apps authorize all calls with SSO tokens, but session cookies are allowed as an alternative. Persisted cookies are not allowed.

    • If a valid subscription is not mapped to the Xbox Live account, a new entry in the backend identity database should be created. A generated code and the PWID are both stored in the new identity database record. The code should be returned in the app UI and the user should be directed to go to the publisher website and enter the code or sign-in to their subscription account on Xbox One and map that account. When the user signs-in to their subscription account and enters their code, the publisher backend should do a look up based on the code in the publisher’s Identity database and map the subscriber account to the Xbox Live identity. When the mapping has been completed, the authentication service should return a session cookie to the app. The app should use the session cookie to authorize subsequent web calls.

Additional resources

For more information about implementing single sign-on (SSO) in your app, see the following resources available for download or viewing on the Xbox Game Developer (XGD) site. We recommend viewing them in the order shown here:

See also

Xbox Service Authorization

Network Security Authorization List (NSAL)

How to use Fiddler with Xbox One