OAuth 2.0

Live Connect implements the OAuth 2.0 protocol to authenticate users. This topic describes both the authorization flows that Live Connect uses and the supported extension parameters.

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 spec first, or refer to it when you come across a term or idea that's unfamiliar to you.

Supported OAuth flows

Live Connect 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://oauth.live.com/authorize/ with request_type=token. This is a standard OAuth 2.0 flow and is defined in detail in the Implicit Grant section of the OAuth 2.0 spec.

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 Connect authorization endpoint, by using a URL in the following format.

   Copy

   https://oauth.live.com/authorize?client_id=CLIENT_ID&scope=SCOPES&response_type=token&redirect_uri=REDIRECT_URL
   

   This URL contains the client ID, requested scopes, local state, and a redirection Uniform Resource Identifier (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 sign-in credentials, and grants or denies the client's access request.

3. Assuming that the user has granted access, the Live Connect 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=[accesstoken].

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 webpage (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. It is a standard OAuth 2.0 flow, and is defined in full detail in the Authorization Code Grant section of the OAuth 2.0 spec. For further details, see Server-side scenarios.

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 Live Connect authorization endpoint, by using a URL in the following format.

   Copy

   https://oauth.live.com/authorize?client_id=CLIENT_ID&scope=SCOPES&response_type=code&redirect_uri=REDIRECT_URL
   

   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 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 Live Connect 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=[authorizationcode].

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: https://oauth.live.com/token?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL& client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&grant_type=authorization_code.

6. The Live Connect 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.

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

   Copy

   https://oauth.live.com/token?client_id=[YOUR_CLIENT_ID]&client_secret=[YOUR_CLIENT_SECRET]&redirect_uri=REDIRECT_URL&grant_type=refresh_token&refresh_token=[REFRESH_TOKEN]
   

8. To make things easier for developers of desktop and mobile apps, the Live Connect OAuth 2.0 implementation provides a special redirect URL: https://oauth.live.com/desktop. This allows 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://oauth.live.com/desktop#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 Connect developer portal allows apps to be marked as mobile client apps. When this marker is specified and the special redirect URL(https://oauth.live.com/desktop) is used, the client secret is not required to refresh the access token. In this case, the URL for refreshing the access token would look like this.
   Copy

   https://oauth.live.com/token?client_id=[YOUR_CLIENT_ID]&redirect_uri=https://oauth.live.com/desktop&grant_type=refresh_token&refresh_token=[REFRESH_TOKEN]
   
   

Sign-in control flow

The sign-in control flow is unique to Live Connect. It uses the Live Connect 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 Live Connect and non-Microsoft web apps. Single sign-in is the mechanism by which a user who is already signed in to Live Connect can go to a different website and be automatically signed in to that site, based on the Live Connect account. 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 HTML iframe element that is embedded in the client webpage, and the implicit grant flow must be implemented by the client app.

Important  Because the sign-in control flow requires no server-side processing, apps can access user info only after the page has loaded.

The sign-in control flow works as follows:

1. The client starts the flow by directing the resource owner's user agent to the Live Connect authorization endpoint, by using a URL with the following format: https://oauth.live.com/authorize?client_id=CLIENT_ID&
 scope=SCOPES&response_type=code&redirect_uri=REDIRECT_URL.

   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 Live Connect.

OAuth request and response parameters

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

The following table lists the OAuth response parameters that are used by Live Connect.

Send comments about this topic to Microsoft

Build date: 12/5/2011