Quickstart: Connecting to an online identity provider (XAML)

Article
10/13/2015

[This article is for Windows 8.x and Windows Phone 8.x developers writing Windows Runtime apps. If you’re developing for Windows 10, see the latest documentation]

This topic will show you how to connect your app to an online identity provider (such as Facebook or Twitter) that uses internet authentication and authorization protocols like OpenID or OAuth.

Apps use Web authentication broker to connect to online identity providers. An app calls the AuthenticateAndContinue method, which sends a request to the online identity provider, and gets back an access token that describes the provider resources to which the app has access. For reference documentation, see Windows.Security.Authentication.Web.

Prerequisites

You should be familiar with developing apps with C#, Visual Basic, or C++.
You should be familiar with the authentication requirements of your online identity provider.

Register your app with your online provider

You must register your app with the online identity provider to which you want to connect. You can find out how to register your app from the identity provider. After registering, the online provider typically gives you an ID and/or secret key for your app.

Create an authentication class that implements IWebAuthenticationContinuable

You can give this class any name you like and place it anywhere in your project. However, it must implement the IWebAuthenticationContinuable interface. This interface contains a single method, ContinueWebAuthentication, that is critical to the authentication process. You'll learn more about how to use ContinueWebAuthentication later in this topic.

public class MyAuthenticationClass : IWebAuthenticationContinuable
{

}

Build the authentication request URI

The request URI consists of the address where you send the authentication request to your online provider appended with other required information, such as an app ID or secret key, a redirect URI where the user is sent after completing authentication, and the expected response type. You can find out from your provider what parameters are required.

public class MyAuthenticationClass : IWebAuthenticationContinuable
{
    public async void StartWebAuthentication()
    {
        string startUrl = "https://<providerendpoint>?client_id=<clientid>&" + 
            "scope=<scopes>&response_type=token";
        string endUrl = "http://<appendpoint>";

        System.Uri startUri = new System.Uri(startUrl);
        System.Uri endUri = new System.Uri(endUrl);
    }
}

Send the request to the provider

Call the AuthenticateAndContinue method to connect to the online identity provider and get an access token. The method takes the URI constructed in the previous step as the requestUri parameter, and a URI to which you want the user to be redirected as the callbackUri parameter.

The following example shows how to connect to an online identity provider.

public class MyAuthenticationClass : IWebAuthenticationContinuable
{
    public async void StartWebAuthentication()
    {
        string startUrl = "https://<providerendpoint>?client_id=<clientid>&" + 
            "scope=<scopes>&response_type=token";
        string endUrl = "http://<appendpoint>";

        System.Uri startUri = new System.Uri(startUrl);
        System.Uri endUri = new System.Uri(endUrl);
        
        WebAuthenticationBroker.AuthenticateAndContinue(startUri, endUri);
    }
}

By default, Web authentication broker does not allow cookies to persist. Because of this, even if the app user indicates that they want to stay logged in (for example, by selecting a check box in the provider's login dialog), they will have to login each time they want to access resources for that provider. To login with single sign-on (SSO), your online identity provider must have enabled SSO for Web authentication broker, and your app must call the overload of AuthenticateAndContinue that does not take a callbackUri parameter.

To support SSO, the online provider must allow you to register a redirect URI in the form ms-app://appSID, where appSID is the SID for your app. You can find your app's SID from the Windows Phone developer page for your app, or by calling the WebAuthenticationBroker.GetCurrentApplicationCallbackUri method.

The following example shows how to connect to an online identity provider with SSO.

public class MyAuthenticationClass : IWebAuthenticationContinuable
{
    public async void StartWebAuthentication()
    {
        string startUrl = "https://<providerendpoint>?client_id=<clientid>&" + 
            "scope=<scopes>&response_type=token";

        System.Uri startUri = new System.Uri(startUrl);
        
        WebAuthenticationBroker.AuthenticateAndContinue(startUri);
    }
}

Continue your app

Authentication on Windows Phone 8.1 is handled differently than it is on Windows 8.1. Because connecting to an online identity provider can be a memory-intensive process, the system suspends your app for the duration of the authentication operation. On lower-memory devices, your app might even be terminated. When the operation completes, your app is automatically reactivated and the authentication results returned as part of your app's Application.OnActivated event args.

In order to effectively suspend, reactivate, and continue your app after calling AuthenticateAndContinue, the use of two special helper classes —SuspensionManager and ContinuationManager— is required. To learn how to use these classes, see How to continue your Windows Phone Store app after calling an AndContinue method. Then proceed to the next step.

Create the ContinueWebAuthentication method to process the authentication results

Note

The following step assumes you have continued your app using the SuspensionManager and ContinuationManager helper classes described in the previous step. Be sure to read How to continue your Windows Phone Store app after calling an AndContinue method before proceeding.

After your app is continued by the ContinuationManager, call the ContinueWebAuthentication method required by the IWebAuthenticationContinuable interface to process the results of the authentication process. This method should be placed in the same class you called AuthenticateAndContinue from.

The following example shows how to use ContinueWebAuthentication to process results from the web authentication broker.

public class MyAuthenticationClass : IWebAuthenticationContinuable
{
    public async void StartWebAuthentication()
    {
        string startUrl = "https://<providerendpoint>?client_id=<clientid>&" + 
            "scope=<scopes>&response_type=token";

        System.Uri startUri = new System.Uri(startUrl);
        
        WebAuthenticationBroker.AuthenticateAndContinue(startUri);
    }
    
    public async void ContinueWebAuthentication(
        WebAuthenticationBrokerContinuationEventArgs args)
    {
        WebAuthenticationResult result = args.WebAuthenticationResult;
        string output; 
        
        // Process the authentication result    
        switch (result.ResponseStatus) 
        {
            case WebAuthenticationStatus.Success:           
                // Parse the token out of the authentication response
                output = result.ResponseData; 
                // Do something with the results token
                break;
            case WebAuthenticationStatus.UserCancel:
                // Handle user cancel
                break;
            case WebAuthenticationStatus.ErrorHttp:
                // Http error
                output = WebAuthenticationStatus.ResponseErrorDetail.ToString(); 
                break;
            default:
                break;
        }
    }
}

Summary

In this topic, we showed how to connect to an online identity provider.