OAuth 2.0

The Live SDK implements the OAuth 2.0 protocol to authenticate users. This topic describes both the authorization flows of services using Microsoft account, and the supported extension parameters.

In this article
Supported OAuth flows
Sign-in control flow
OAuth authorization request parameters
OAuth request and response parameters
Moving from OAuth WRAP to OAuth 2.0
Related topics

In this topic, we assume that you are familiar with OAuth 2.0 and OAuth terminology. If you're new to OAuth, we recommend that you check out the OAuth 2.0 spec first, or refer to it when you come across a term or idea that's unfamiliar to you.

Supported OAuth flows

The Live SDK supports the following authorization flows:

• Implicit grant flow

• Authorization code grant flow

• Sign-in control flow

Implicit grant flow

The implicit grant flow can be used by both web-based and desktop apps. In this flow, the client makes an authorization request to https://login.live.com/oauth20\_authorize.srf with request_type=token.

The following diagram illustrates how the implicit grant flow works.

1. The client starts the flow by directing the resource owner's user agent to the Live SDK authorization endpoint, by using a URL in the following format.

   https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=SCOPES&response_type=token&redirect_uri=REDIRECT_URI
   

   This URL contains the client ID, requested scopes, and a redirection Uniform Resource Identifier (URI) to which the authorization web service sends the user agent after access is granted or denied.

   Note

   Do not include the wl.offline_access scope if you're using the implicit grant flow (response_type=token).

2. The user is prompted for his or her sign-in credentials, and grants or denies the client's access request.

3. Assuming that the user has granted access, the Microsoft account authorization server redirects the user agent to the client by using the redirection URI that was provided in the initial request. The redirection URI includes an access token in the URI fragment. For example: http://contoso.com/Callback.htm\#access\_token=ACCESS\_TOKEN.

4. The user agent follows the redirection instructions by making a request to the Contoso web server. The user agent retains the URI fragment locally, but does not include it in the request to the server.

5. The Contoso server returns a web page (typically an HTML document that contains an embedded script) that is capable of accessing the full redirection URI, including the fragment that was retained by the user agent. The script can also extract the access token and other parameters that are contained in the fragment.

   The user-agent locally executes the script that was provided by the web server, to extract the access token and pass it to the client.

Authorization code grant flow

In the authorization code grant flow, the client makes authorization requests by using request_type=code.

The following diagram illustrates how the authorization code grant flow works.

1. The client starts the flow by directing the resource owner's user agent to the Microsoft account authorization endpoint, by using a URL in the following format.

   https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=SCOPES&response_type=code&redirect_uri=REDIRECT_URI
   

   This URL contains the client ID, requested scopes, and a redirection URI to which the authorization web service sends the user agent after access is granted or denied.

2. The authorization server authenticates the resource owner via the user agent, and establishes whether the resource owner grants or denies the client's access request.

3. Assuming that the resource owner has granted access, the Microsoft account authorization server redirects the user agent to the client by using the redirection URI that was provided in the initial request.

4. The user agent calls the client with the redirection URI, which includes an authorization code and any local state that was provided by the client. For example: http://contoso.com/Callback.htm?code=AUTHORIZATION\_CODE.

5. The client requests an access token from the authorization server's token endpoint by using its client credentials for authentication, and includes the authorization code that was received in the previous step. The client includes the redirection URI that was used to obtain the authorization code for verification. The request URL has the following format:

   POST https://login.live.com/oauth20_token.srf
   
   Content-type: application/x-www-form-urlencoded
   
   client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&grant_type=authorization_code
   

   The Microsoft account authorization server validates the client credentials and the authorization code, and ensures that the redirection URI that was received matches the URI that was used to redirect the client in step 3.

6. If the credentials are valid, the authorization server responds by returning an access token. If the wl.offline_access scope was requested, then a refresh token is also returned. To refresh the access token, the client must make a request to the following URL.

   POST https://login.live.com/oauth20_token.srf
   
   Content-type: application/x-www-form-urlencoded
   
   client_id=CLIENT_ID&client_secret=CLIENT_SECRET&redirect_uri=REDIRECT_URI&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
   

   To make things easier for developers of desktop and mobile apps, the Live SDK OAuth 2.0 implementation provides the following special redirect URL: https://login.live.com/oauth20\_desktop.srf. This enables apps that can host a web browser control (such as a Java app, Cocoa app, or .NET app) to handle redirects after the user has provided consent, by listening for when the user is redirected to https://login.live.com/oauth20\_desktop.srf\#access\_token=ACCESS\_TOKEN, and then retrieving the access token from the end of the URL using whatever mechanisms are available in the chosen client platform. Because apps must also refresh access tokens, the Live SDK app management site allows apps to be marked as mobile client apps. When this marker is specified and the special redirect URL (https://login.live.com/oauth20\_desktop.srf) is used, the client secret is not required to refresh the access token. In that case, the URL for refreshing the access token looks like this.

   POST https://login.live.com/oauth20_token.srf
   
   Content-type: application/x-www-form-urlencoded
   
   client_id=CLIENT_ID&redirect_uri=https://login.live.com/oauth20_desktop.srf&grant_type=refresh_token&refresh_token=REFRESH_TOKEN
   

Sign-in control flow

The sign-in control flow is unique to services using Microsoft account. It uses the Microsoft account sign-in control to simplify sign-in and consent for apps. Intended for use by browser-based apps, it does not require the app to use any server-side logic. You start the flow by using the JavaScript API (the WL.login method) or by embedding an HTML control (by calling the WL.ui method), rather than by calling the consent service directly by using an HTTP request. The sign-in control flow is the only web flow that supports seamless, single sign-in across services using Microsoft account and non-Microsoft web apps. Single sign-in is when a user who is already signed in to their Microsoft account can go to a different website and be automatically signed in to that site, based on the account sign-in settings. The user has control over this sign-in behavior on each website, on an opt-in basis.

The sign-in control flow is a variation of the implicit grant flow. The key difference between the two is that the sign-in control flow is implemented by using an invisible HTMLiframe element that is embedded in the client web page, and the implicit grant flow must be implemented by the client app.

The sign-in control flow works as follows:

1. The client starts the flow by directing the resource owner's user agent to the Microsoft account authorization endpoint, by using a URL with the following format: https://login.live.com/oauth20\_authorize.srf?client\_id=CLIENT\_ID&? scope=SCOPES&response_type=code&redirect_uri=REDIRECT_URI.

   This URL contains the client ID, requested scopes, local state, and a redirection URI to which the authorization web service sends the user agent after access is granted or denied.

2. The user is prompted for his or her credentials, and grants or denies the client's access request.

OAuth authorization request parameters

The following table lists the OAuth authorization request parameters that are used by the Live SDK.

OAuth request and response parameters

The following table lists the OAuth request and response parameters that are used by the Live SDK.

Moving from OAuth WRAP to OAuth 2.0

The Live SDK version 4.1 uses our implementation of OAuth Web Resource Authorization Protocol (WRAP) for user authentication and consent and for managing access tokens and refresh tokens. The Live SDK version 5 deprecates OAuth WRAP in favor of our implementation of OAuth 2.0. Also, we turned off access to the Live SDK version 4.1 services on 25 June 2012. To move an app from using OAuth WRAP to OAuth 2.0, you'll need to know the following info:

• If your app has a refresh token that contains one or more scopes that a user has consented to and that are specific to the Live SDK version 4.1, your app can use that refresh token with the Live SDK version 5 to get an access token that contains equivalent consented scopes in the Live SDK version 5. This process allows your app to access a user's info in the Live SDK version 5 without unnecessarily interrupting the user to provide consent again to scopes that he or she previously consented to in the Live SDK version 4.1. For example, if a user previously consented to the WL_Photos.View scope in the Live SDK version 4.1, and your app has a refresh token that contains this consented scope, your app can use that refresh token with the Live SDK version 5 to get an access token that contains a scope with functionality equivalent to the WL_Photos.View scope. Your app can then use that access token with the Live SDK version 5 to access photo albums and videos that the consenting user has uploaded, along with associated tags and comments. As long as your app has a valid refresh token that is specific to the Live SDK version 4.1 and the user has not explicitly revoked consent, you can use that refresh token with the Live SDK version 5 even after the Live SDK version 4.1 services are turned off.

• An app can't use the Live SDK version 5 to request a user to consent to specific scopes that exist only in the Live SDK version 4.1.

Related topics

• Scopes and permissions

• Live SDK REST API