In previous releases, you were required to manually retrieve an authentication token and insert it into each HTTPS request header yourself. In this release, we provide support for automatic insertion of an authorization token and request signature into HTTPS requests. While manual insertion is still supported, we strongly recommend that your app use the automatic capability, as it substantially simplifies your code and your testing requirements. All you have to do for automatic insertion is to not insert any authentication token or signature into your HTTPS request before you call IXMLHTTPRequest2, and the proper token and signature will be inserted for you.
If you are manually constructing HTTPS requests rather than using the IXMLHTTPRequest2 class, you can use GetTokenAndSignatureAsync and related functions to retrieve token and signature and insert them manually into your request header.
This topic assumes that you have properly used Xbox Developer Portal (XDP) to configure your app and one or more development accounts. See Xbox Service Authorization for details.
User Enumeration
Use the User::Users property to retrieve a list of signed-in Users for the console, and enumerate the Users in that list to determine which one will request the token.
Token Retrieval
You retrieve a token and a signature for each call you make to a remote web service, using the appropriate signed-in User object and calling that object’s GetTokenAndSignatureAsync method. You pass the web service URL, the message headers, and the message body as arguments to the method, and when the asynchronous operation completes, it returns both the token and a digital signature of the message that includes the token, to be used to verify the message at the server.
In the example below, the call returns asyncOp, a pointer to an IAsyncOperation object. (Note that for purposes of illustration the code has been simplified. Your code would be more thorough—determining, for example, which User object represents the person whose token is being retrieved, rather than simply using the first User in the Users list.) Next, the example sets the value of the asyncOp->Completed property to point to code for handling the returned token. The example creates a lambda function that is called when the asynchronous operation completes.
Windows::Foundation::IAsyncOperation<Windows::Xbox::System::GetTokenAndSignatureResult^>^ asyncOp = user->GetTokenAndSignatureAsync("GET", url, headers, body);
asyncOp->Completed = ref new Windows::Foundation::AsyncOperationCompletedHandler<Platform::String^>
([=](Windows::Foundation::IAsyncOperation<Platform::String^>^ asyncInfo, Windows::Foundation::AsyncStatus asyncStatus) //set the Completed property
{
// store the returned token
Platform::String^ token = asyncInfo->GetResults()->Token;
// code that uses the returned token
...
});
The implementation of GetTokenAndSignatureAsync caches the tokens it retrieves for each combination of URL and HTTPS method, and returns the cached token on subsequent calls, updating the token as necessary when the cached token has expired. The caching is transparent to your title.
Calling Xbox services
The authorization token and request signature retrieved by calling GetTokenAndSignatureAsync must be provided in any HTTPS request sent to Xbox services, or to a relying party web service. Do this by putting the token string into the Authorization header of the request, as shown in the “Using Xbox LIVE Services URIs” article in the Getting Started section of the current Xbox LIVE Services documentation.
Authorization: XBL3.0 x=<userhash>;<token>
Note that the proper format for the header string passed as the headers parameter is that each message header consists of a name followed by a colon, and then the value of the header string, terminated by a carriage return - line feed pair. The following code sample demonstrates constructing a headers string from an IKeyValuePair<String^,String^> list, where the first string in the pair is the header name and the second string is the header value.
Platform::String^ requestHeaders;
for each (IKeyValuePair<String^, String=""^>^ kvp in headersToAdd)
{
Platform::String^ header = it->first + ": " + it->second + "\r\n";
requestHeaders += header;
}
Some Xbox LIVE services require that you provide an Xbox User ID (XUID) and the authorization token. A user’s XUID is the value of the XboxUserId property for their User object.
Request and response data is sent as JavaScript Object Notation (JSON) objects. See the Xbox LIVE Services documentation for more information about using JSON. Xbox One includes Windows.Data.Json, a WinRT implementation of a JSON parser. See Using JavaScript Object Notation (JSON) on MSDN for an overview on using the parser.
Calling relying third-party services
Each relying third-party service must have properly configured certificates from Microsoft. Contact your DAM for certificates and instructions for how to install them.
To configure your title to call your third party service, you must provide a NSAL file with the proper entries. Details of the NSAL file are the same, whether you are using automatic token insertion or you are inserting tokens manually.
You can exert the same control over the inclusion of user and actor claims in tokens you retrieve manually, as users of automatic token insertion exert by setting the “xbl-authz-actor-10” header value. When manually retrieving tokens, that control is inherent in which function you use to retrieve the token, as shown in the following table.
| API | Claims returned |
|---|---|
| User::GetTokenAndSignatureForAllUsersAsync | User claims for all signed-in users, no actor claims. Device and title claims. |
| User::GetTokenAndSignatureAsync | User claims for all signed-in users, actor claims for the user represented by the User object used to make the call. Device and title claims. |
| Console::GetTokenAndSignatureAsync | No user claims. Device and title claims, only. |