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 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
- Sign-in control flow
- OAuth authorization request parameters
- OAuth request and response parameters
- Moving from OAuth WRAP to OAuth 2.0
Supported OAuth flows
Live Connect supports the following authorization flows:
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. 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.
-
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.
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). -
The user is prompted for his or her sign-in credentials, and grants or denies the client's access request.
-
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=ACCESS_TOKEN. -
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.
-
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.
-
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.
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.
-
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.
-
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.
-
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. -
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 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.
-
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 Connect 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 Connect 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 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:
-
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://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.
-
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.
| Parameter | Notes |
|---|---|
|
client_id |
The app's client ID. |
|
display |
The display type to be used for the authorization page. Valid values are "popup", "touch", "page", or "none". |
|
locale |
Optional. A market string that determines how the consent UI is localized. If the value of this parameter is missing or is not valid, a market value is determined by using an internal algorithm. |
|
redirect_uri |
Equivalent to the endpoint that is described in the OAuth 2.0 spec. |
|
response_type |
The type of data to be returned in the response from the authorization server. Valid values are "code" or "token". |
|
scope |
Equivalent to the scope parameter that is described in the OAuth 2.0 spec. |
|
state |
Equivalent to the state parameter that is described in the OAuth 2.0 spec. |
OAuth request and response parameters
The following table lists the OAuth request and response parameters that are used by Live Connect.
| Parameter | Notes |
|---|---|
|
client_id |
The app's client ID. |
|
client secret |
The app's client secret. |
|
grant_type |
The authorization type that the server returns. Valid values are "authorization_code" or "refresh_token". |
|
locale |
Optional. A market string that determines how the consent UI is localized. If the value of this parameter is missing or is not valid, a market value is determined by using an internal algorithm. |
|
redirect_uri |
Equivalent to the endpoint that is described in the OAuth 2.0 spec. |
|
response_type |
The type of data to be returned in the response from the authorization server. Valid values are "code" or "token". |
|
scope |
Equivalent to the scope parameter that is described in the OAuth 2.0 spec. |
|
state |
Equivalent to the state parameter that is described in the OAuth 2.0 spec. |
|
display |
The display type to be used for the authorization page. Valid values are "popup", "touch", "page", or "none". |
The following table lists the OAuth response parameters that are used by Live Connect.
| Parameter | Notes |
|---|---|
|
access_token |
Equivalent to the access_token parameter that is described in the OAuth 2.0 spec. |
|
authentication_token |
The app's authentication token. |
|
code |
Equivalent to the code parameter that is described in the OAuth 2.0 spec. |
|
expires_in |
Equivalent to the expires_in parameter that is described in the OAuth 2.0 spec. |
|
refresh_token |
Equivalent to the refresh_token parameter that is described in the OAuth 2.0 spec. |
|
scope |
Equivalent to the scope parameter that is described in the OAuth 2.0 spec. |
|
state |
Equivalent to the state parameter that is described in the OAuth 2.0 spec. |
|
token_type |
The type of data to be returned in the response from the authorization server. |
Moving from OAuth WRAP to OAuth 2.0
Live Connect 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. Live Connect version 5 deprecates OAuth WRAP in favor of our implementation of OAuth 2.0. Also, we plan to turn off access to Live Connect 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 Live Connect version 4.1, your app can use that refresh token with Live Connect version 5 to get an access token that contains equivalent consented scopes in Live Connect version 5. This process allows your app to access a user's info in Live Connect version 5 without unnecessarily interrupting the user to provide consent again to scopes that he or she previously consented to in Live Connect version 4.1. For example, if a user previously consented to the WL_Photos.View scope in Live Connect version 4.1, and your app has a refresh token that contains this consented scope, your app can use that refresh token with Live Connect 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 Live Connect 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 Live Connect version 4.1 and the user has not explicitly revoked consent, you can use that refresh token with Live Connect version 5—even after Live Connect version 4.1 services are turned off.
- An app can't use Live Connect version 5 to request a user to consent to specific scopes that exist only in Live Connect version 4.1. For example, an app can't use Live Connect version 5 to ask a user to explicitly consent to the WL_Activities.Update scope, which doesn't exist in Live Connect version 5. In this example, we recommend that the app use Live Connect version 5 to ask the user to consent to the wl.share scope, which has equivalent functionality.
For more info, see Migrating your Live Connect v4.1 app to v5.0.
Build date: 2/5/2013