Provide Single Sign-On (SSO) to Xbox Live users

In order for your web service to provide single-sign-on to Xbox Live users, it needs to be configured as a relying party of Xbox Live. When configured that way, users who are authenticated to Xbox Live will automatically be authenticated to your service without having to re-enter a different set of credentials.

For this to happen, a trust relationship must be established between the Xbox Security Token Service (XSTS) and your web service. Cryptographically, this is achieved by having the tokens issued by the XSTS be signed with a private key, and by having token signatures validated on your service by using the corresponding public key.

In addition, we require the following to ensure that token content can’t be read on the wire or on the client:

• All tokens must be sent exclusively over secure channels (by using HTTPS).
  
• All tokens are encrypted.
  

As part of your relying party configuration, a private key needs to be provided, which will be used by XSTS to encrypt tokens emitted for your web service. Your web service, when it receives such a token, will then decrypt that token by using the corresponding private key.

To enable single-sign-on (SSO)

1. Create a new web service and provide a friendly name for it.
   Don’t select Telemetry access unless you are going to use that same service to make calls to Xbox Live to retrieve game telemetry data.
   
2. Within that web service, add one or more of the following endpoints:

   Note You must click on the web service to highlight it before you can add endpoints to it.
   
   Host type
   Use a fully qualified domain name (FQDN) or a wildcard. Use an FQDN if you want to have an exact match on the host name; use a wildcard if you use subdomains, and the SSO configuration will apply to all subdomains.
   Protocol
   Use HTTPS.
   Hostname
   Specify the host name of your service, for example, “abc.com” (FQDN) or “*.abd.com” (Wildcard).
   Port
   If your service listens on the default port (443) for HTTPS, leave this empty; otherwise, specify the port that your service listens on.
   Path
   Optionally, you can specify the path for which the SSO configuration should apply, for example, “xboxlive” or “xboxlive/sso.svc.”
   

3. Select Requires Single Sign On token.
   Specify token type JWT. For the token definition, if you have previously defined a name and configuration for your relying party, select it in the list; otherwise, click Add New.
   To add a new token
   1. Specify a name in the form of a URI.
      The name doesn’t need to match the hostname of your service and must end with a forward slash, for example, http://myrelyingpartyname.com/.
      

      Note The token name has to be unique across all of Xbox Live. If the name was used before (even if deleted since) it will not be valid for a new token.

   2. Specify the lifetime.
      The lifetime of the token is 4 hours, by default. We recommend that you use the default value.
      
   3. Specify an encryption certificate.
      You must upload the encryption certificate-Public key only-that is going to be used by XSTS to encrypt tokens for this relying party. The key type must be RSA and the key length must be at least 2048. We recommend, though not required, to set an EKU of “encryption.” There are no requirements around the trust chain for the certificate.
      
   4. Specify claims.
      For claims, select the set of claims, which will be included in the token, that are necessary on your service for personalization of content and/or access control.
      

   5. Click Add token.
      

   6. Leave Signature Policy Set at the default value.
      
   7. In the rare case where your service’s SSL certificate chains to a root Certificate Authority (CA) that is not among the list of CAs trusted by Windows, you must ingest that SSL certificate in order for the console to successfully establish communication to your service. For that, under Service Certificate Chain (Optional), either select a previously ingested SSL certificate or add a new certificate. To add a new certificate, click Add New, and then use the following procedure.
      To add a new SSL certificate
      1. For Type, specify SSL.
         
      2. For Certificate file, upload a .p7b file that contains the full trust chain of your SSL certificate or a .p7b file that contains the full trust chain for the issuing CA of your SSL certificate. If your .p7b file contains the full trust chain for your SSL certificate, you must select Contains Leaf.
         
      3. Click Add Certificate Chain.
         
   8. Click Add endpoint.
      

At this point, your web service is configured and ready for use by clients. When a title developer selects your web service as part of their NSAL configuration and makes an IXMLHTTPRequest2 call to the endpoint(s) you specified in the configuration, an authorization token will automatically be added to the authorization header of the http request. Similarly, the title developer would be able to manually retrieve a token using the GetTokenAndSignatureAsync API followed by manual insertion of the token into the authorization request header of the HTTP request to your service.

For more info about how to implement and configure your web service to process tokens issued by Xbox Live, see the documentation for the Xbox Services and Relying Party SDK, available for download from Xbox One XDK Software Downloads on the Xbox Game Developer site.