How to authenticate with the Windows Push Notification Service (WNS) (Windows Runtime apps)

This topic explains how to authenticate your cloud server with Windows Push Notification Services (WNS) and receive an access token in return.

Prerequisites

• A Windows Store developer account.
• A Windows Store app to register.
• A working knowledge of tile and notification terms and concepts, as well as XML.
• Familiarity with push notification and WNS concepts, requirements, and operation.

Instructions

Step 1: Register your app with the Dashboard

Before you can send notifications through WNS, you must register your app. Do so through the Dashboard, the developer portal that enables you to submit, certify, and manage your Windows Store apps. When you register your app through the Dashboard, you are given credentials—a Package security identifier (SID) and a secret key—which your cloud service uses to authenticate itself with WNS.

To register:

1. Go to the Windows Store apps page of the Windows Dev Center and sign in with your Microsoft account.

2. Once you have signed in, click the Dashboard link.

3. On the Dashboard, select Submit an app.

   

4. On the Submit an app page, select App name.

   

5. Provide a unique name for your app. Enter the name and click the Reserve name button. If the name is available, it is reserved for your app. Once you have successfully reserved a name for your app, the other details become available to modify should you choose to do so at this time.

Step 2: Obtain the identity values for your app

When you reserved a name for your app, the Windows Store created your associated credentials. It also assigned associated identity values—name and publisher— that must be present in your app's manifest file (package.appxmanifest). If you have already uploaded your app to the Windows Store, these values will have automatically been added to your manifest. If you have not uploaded your app, you will need to add the identity values to your manifest manually.

1. Select the Services link.

   

2. On the Services page, select the Live Services link found under the Microsoft Azure Mobile Services section.

   

3. On the Push notifications and Live Connect services info page, select Identifying your app.

   

4. The Identifying your app page gives you an identity element to include in your app's manifest. Open your manifest in a text editor and add that element as the page instructs.

   

Step 3: Obtain the credentials for your app

1. Click the Authenticating your service link at the bottom of that same Identifying your app page.

   

2. The Authenticating your service page provides your security identifier and client secret. To send push notifications to this app, your cloud service must use these credentials exactly. You cannot use the credentials of another cloud service to send notifications to this app and you cannot use these credentials to send notifications to another app.

   Note  This page can also be used to generate new credentials.

    

   

3. Upload the SID and client secret to your cloud server.

   Important  The SID and client secret should be securely stored and accessed by your cloud service. Disclosure or theft of this information could enable an attacker to send notifications to your users without your permission or knowledge.

    

Step 4: Send the cloud server's credentials to WNS

The cloud service presents its credentials (SID and client secret) through an HTTPS authentication request that uses the "application/x-www-for-urlencoded" format.

This example shows a sample HTTPS authentication request. It includes a Package SID and secret key in the grant_type. Be sure to substitute your own Package SID in the "client_id" field and your own secret key in the "client_secret" field if you copy this code. See Push notification service request and response headers for syntax information.

POST /accesstoken.srf HTTP/1.1
Content-Type: application/x-www-form-urlencoded
Host: https://login.live.com
Content-Length: 211
 
grant_type=client_credentials&client_id=ms-app%3a%2f%2fS-1-15-2-2972962901-2322836549-3722629029-1345238579-3987825745-2155616079-650196962&client_secret=Vex8L9WOFZuj95euaLrvSH7XyoDhLJc7&scope=notify.windows.com

WNS sends your server a response to the authentication request. If the response code is "200 OK", the authentication was successful and the response includes an access token that your cloud server must save and use in any notifications it sends until that access token expires.

An example of a WNS reply to a successful authentication is shown here.

HTTP/1.1 200 OK   
Cache-Control: no-store
Content-Length: 422
Content-Type: application/json
 
{
    "access_token":"EgAcAQMAAAAALYAAY/c+Huwi3Fv4Ck10UrKNmtxRO6Njk2MgA=", 
    "token_type":"bearer"
}

The following example supplies the code you need to send the authentication request and receive the reply. You can copy this example directly into your own cloud server code as long as you include these directives:

using System.Runtime.Serialization.Json;

using System.Runtime.Serialization;

using System.IO;

[DataContract]
public class OAuthToken
{
    [DataMember(Name = "access_token")]
    public string AccessToken { get; set; }
    [DataMember(Name = "token_type")]
    public string TokenType { get; set; }
}

private OAuthToken GetOAuthTokenFromJson(string jsonString)
{
    using (var ms = new MemoryStream(Encoding.Unicode.GetBytes(jsonString)))
    {
        var ser = new DataContractJsonSerializer(typeof(OAuthToken));
        var oAuthToken = (OAuthToken)ser.ReadObject(ms);
        return oAuthToken;
    }
}

protected OAuthToken GetAccessToken(string secret, string sid)
{
    var urlEncodedSecret = HttpUtility.UrlEncode(secret);
    var urlEncodedSid = HttpUtility.UrlEncode(sid);

    var body =
      String.Format("grant_type=client_credentials&client_id={0}&client_secret={1}&scope=notify.windows.com", urlEncodedSid, urlEncodedSecret);

    string response;
    using (var client = new WebClient())
    {
        client.Headers.Add("Content-Type", "application/x-www-form-urlencoded");
        response = client.UploadString("https://login.live.com/accesstoken.srf", body);
    }
    return GetOAuthTokenFromJson(response);
}

Related topics

Push notifications overview

Push notification service request and response headers

Push and periodic notifications sample

Quickstart: Sending a push notification

How to request, create, and save a notification channel