Quickstart: Connecting to an online identity provider (HTML)

Article
08/31/2015

This topic will show you how to connect your Windows Store app to an online identity provider that uses internet authentication and authorization protocols like OpenID or OAuth

Windows Store apps use Web authentication broker to connect to online identity providers. An app calls the AuthenticateAsync 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 a complete example, see Web authentication broker sample. For more information about Web authentication broker, see Web authentication broker. For reference documentation, see Windows.Security.Authentication.Web

When you've finished with this topic, check out the following:

Prerequisites

You should be familiar with JavaScript.
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 for your app.

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, 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.

The request URI is sent as the requestUri parameter of the authenticateAsync method. It must be a secure address (it must start with https://)

The following example shows how to build the request URI.


        var startURL = "https://<providerendpoint>?client_id=<clientid>&scope=<scopes>&response_type=token"; 

        var startURI = new Windows.Foundation.Uri(startURL);

Connect to the online provider

You call the authenticateAsync 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.

authzInProgress = true; 
        Windows.Security.Authentication.Web.WebAuthenticationBroker.authenticateAsync( 
            Windows.Security.Authentication.Web.WebAuthenticationOptions.none, startURI,endURI) 
            .done(function (result) { 
                document.getElementById("AnyServiceReturnedToken").value = result.responseData; 
                document.getElementById("AnyServiceDebugArea").value += "Status returned by WebAuth broker: " + result.responseStatus + "\r\n"; 
                if (result.responseStatus === Windows.Security.Authentication.Web.WebAuthenticationStatus.errorHttp) { 
                    document.getElementById("AnyServiceDebugArea").value += "Error returned: " + result.responseErrorDetail + "\r\n"; 
                } 
                authzInProgress = false; 
            }, function (err) { 
                WinJS.log("Error returned by WebAuth broker: " + err, "Web Authentication SDK Sample", "error");         
                document.getElementById("AnyServiceDebugArea").value += " Error Message: " + err.message + "\r\n"; 
                authzInProgress = false; 
            });

Connect with single sign-on (SSO)

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 SSO, your online identity provider must have enabled SSO for Web authentication broker, and your app must call the overload of authenticateAsync 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 Store developer page for your app, or by calling the getCurrentApplicationCallbackUri method.

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

var redirectURL = Windows.Security.Authentication.Web.WebAuthenticationBroker.getCurrentApplicationCallbackUri().absoluteUri;
        var startURL = "https://<providerendpoint>?client_id=<clientid>&redirect_uri=" + encodeURIComponent(redirectURL) + "&scope=<scopes>&response_type=token"; 

        var startURI = new Windows.Foundation.Uri(startURL); 

        Windows.Security.Authentication.Web.WebAuthenticationBroker.authenticateAsync( 
            Windows.Security.Authentication.Web.WebAuthenticationOptions.none, startURI) 
            .done(function (result) { 
                if (result.responseStatus === Windows.Security.Authentication.Web.WebAuthenticationStatus.errorHttp) { 
                    document.getElementById("FacebookDebugArea").value += "Error returned: " + result.responseErrorDetail + "\r\n"; 
                } 

                // Parse out the OAuth token from result.responseData 

            }, function (err) { 
                WinJS.log("Error returned by WebAuth broker: " + err, "Web Authentication SDK Sample", "error"); 
            });

Preview your authenticated app state in Blend

If you are using authenitcateUserAsync to authenticate your app at run-time, you can use those same credentials to access the authenticated state of your app in Blend for Microsoft Visual Studio 2013. This means that you can open an authenticated version of your app, make changes to the appearance, and then preview the changes that you just made, all without leaving Blend.

In Blend, in the Design Time category in the Device panel, select Authentication.
Press F5 to build and run your app.
Use your credentials to sign into your app.
Return to Blend and reload your app.
Return to the deployed app and press Alt+F4 to close it. Note Only one instance of the app package identity can run at a time. Because the authenticated view of app in Blend uses the same package identity as the deployed version of your app, your app can’t run in the background while it's also running in Blend.
Return to Blend to continue your work.