Signing users in with REST

  • Article

We provide a REST implementation to sign your users in, so they can access their Microsoft OneDrive info.

In this article
Prerequisites
Register your app and configure its settings
Specify a redirect domain and get a client secret
Initiate the sign-in process
Get an access token and an authentication token
Sign the user out
Getting a new access token or refresh token
Summary

Prerequisites

We assume the following:

  • You are familiar with the Live SDK REST API.

  • You have an app to which you want to add sign-in to.

Register your app and configure its settings

  1. Go to the Microsoft account Developer Center.

  2. If prompted, sign in with your Microsoft account credentials.

  3. If you are not immediately prompted to provide the app's display name and primary language, click Create application.

  4. Type the app's display name and select the app's primary language.

  5. Read the Live Connect terms of use and the Privacy and Cookies statement, and then click I accept. A client ID is created and displayed in App Settings. It should look something like this: 00000000603E0BFE.

  6. To specify that your app is a mobile client app, in API Settings, click Yes under Mobile or desktop client app.

Specify a redirect domain and get a client secret

  1. In the Microsoft account Developer Center, select your app and click Edit settings > API Settings.

  2. Under Redirect URLs, type the redirect domain you will be redirecting users to

  3. Click App Settings. On the application summary page, the client secret is displayed. It should look something like this:

    qXipuPomaauItsIsmwtKZ2YacGZtCyXD

    Note

    To change your client secret, click App Settings > Create a new client secret > OK. Both the old and new client secrets will continue to work until you activate the new client secret from API Settings in the Microsoft account Developer Center.

Initiate the sign-in process

To use the REST API, your app must initiate the sign-in process by contacting the Live SDK authorization web service and getting an authorization code. To do this, make the following call from a web browser or a web-browser control.

  • Replace CLIENT_ID with your app's client ID.

  • Replace SCOPES with the scopes that you want the user to give you permission to access. Separate each requested scope with the URL escape code %20.

    Note

    If you want to obtain a refresh token in addition to an access token, you must also include the wl.offline_access scope in the scope query parameter. (A refresh token enables you to obtain a replacement access token to interact directly with the Live SDK REST API on behalf of a user, after the user ends his or her web browsing session.)

  • Replace REDIRECT_URI with the Uniform Resource Identifier (URI) of your callback webpage. The callback URI must use URL escape codes, such as %20 for spaces, %3A for colons, and %2F for forward slashes.

Note

Mobile apps should append &display=touch to the authorization service URL.

GET https://login.live.com/oauth20_authorize.srf?client_id=CLIENT_ID&scope=SCOPES&response_type=
    RESPONSE_TYPE&redirect_uri=REDIRECT_URL

For example, the following URL uses a client ID of 0000000603DB0F, the wl.signin and wl.basic scopes, and a redirect URI of http://www.contoso.com/callback.php.

https://login.live.com/oauth20_authorize.srf?client_id=0000000603DB0F&scope=wl.signin%20wl.basic&response_type=code&redirect_uri=http%3A%2F%2Fwww.contoso.com%2Fcallback.php

Optionally, you can also append the following query parameters to the preceding URL:

  • A display query parameter, which represents a request for the display mode of the consent page, can be set to popup, touch, or none.

  • A locale query parameter, which is used by the request for consent page to display localized UI text in the user's preferred language. This query parameter can be set to a market value, such as en. For details, see Supported locales.

  • A state query parameter, which represents any arbitrary text string that you may want to pass to the redirect URL for your own use.

When the URL is called from a webpage, the authorization web service checks to determine whether there is a signed-in user. If the user is not signed in, he or she is prompted to sign in to the service. After the user signs in, the authorization web service checks to see whether the user previously consented to the requested scopes. If the user has not consented previously, he or she is prompted to consent to the requested scopes. If the user consents, the authorization web service sends the authorization code to the redirect URI, with the authorization code appended as a query parameter named code, as shown in the following example.

http://www.contoso.com/callback.php?code=2bd12503-7e88-bfe7-c5c7-82274a740ff

http://www.contoso.com/callback.php?code=2bd12503-7e88-bfe7-c5c7-82274a740ff

Get an access token and an authentication token

After you have obtained an authorization code, you exchange it for an access token and an authentication token and a refresh token, if the user consented to a wl.offline_access scope request.

This section show how to use the Live SDK to obtain the tokens. If you add wl.offline_access to the list of requested scopes in the following examples, and the user consents to your request, the authorization web service sends to the callback URI an access token, an authentication token, and a refresh token. These tokens are represented as strings of characters, in the access_token, authentication_token, and refresh_token key/value pairs, inside a JavaScript Object Notation (JSON)-formatted object, as shown in the following example.

{
    "token_type":"bearer",   
    "expires_in":3600,
    "scope":"wl.offline_access wl.signin wl.basic",
    "access_token":"EwCo...//access token string shortened for example//...AA==",
    "refresh_token":"*LA9...//refresh token string shorted for example//...k%65",
    "authentication_token":"eyJh...//authentication token string shortened for example//...93G4"
}

Note

A typical refresh token string consists of well over 200 characters, so part of the refresh token string is omitted for brevity in the preceding example.

Retain this access token (and the refresh token, if you obtained one) to make other calls using the REST API.

Note

To use an authentication token, which is useful for single sign-on scenarios, see Single sign-on for apps and websites.

To obtain an access token and an authorization token (and, optionally, a refresh token), make an HTTP POST call to the authorization web service by using the following URL.

POST https://login.live.com/oauth20_token.srf

The Content-Type header should have the value "application/x-www-form-urlencoded". Construct the request body as shown in the following example, and replace these elements:

  • Replace CLIENT_ID with your app's client ID.

  • Replace REDIRECT_URI with the URI to your callback webpage. This URI must be the same as the URI that you specified when you requested an authorization code. The URI must use URL escape codes, such as %20 for spaces, %3A for colons, and %2F for forward slashes.

  • Replace CLIENT_SECRET with your app's client secret. The client secret must use URL escape codes, such as %2B for the plus sign.

  • Replace AUTHORIZATION_CODE with the authorization code that you obtained earlier.

Note

For web apps, the domain portion of the redirect URI must match the domain portion of the redirect URI that you specified in the Microsoft account Developer Center.

client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&client_secret=CLIENT_SECRET&code=AUTHORIZATION_CODE&grant_type=authorization_code

For example, the following request body uses a client ID of 0000000603DB0F, a redirect URI of http://www.contoso.com/callback.php, a client secret of LWILlT555GicSrIATma5qgyBXebRI, and an authorization code of 2bd12503-7e88-bfe7-c5c7-82274a740ff.

POST https://login.live.com/oauth20_token.srf
Content-type: application/x-www-form-urlencoded
client_id=0000000603DB0F&redirect_uri=http://www.contoso.com/callback.php&client_secret=LWILlT555GicSrIATma5qgyBXebRI&code=2bd12503-7e88-bfe7-c5c7-82274a740ff&grant_type=authorization_code

If the call is successful, the response for the HTTP POST request contains an access token and an authentication token. These tokens are each represented as a string of characters, in an access_token and an authentication_token key/value pair inside a JSON-formatted object, as shown in the following example.

Note

The access token doesn't include the beginning and ending quotation marks. The access token is valid for only the number of seconds that is specified in the expires_in structure.

{
    "token_type":"bearer"
    "expires_in":3600,
    "scope":"wl.signin wl.basic",
    "access_token":"EwCo...//access token string shortened for example//...AA==",
    "authentication_token":"eyJh...//authentication token string shortened for example//...93G4"
}

Note

A typical token string consists of well over 550 characters, so part of each token string is omitted for brevity in the preceding example.

Sign the user out

To sign a user out, make a call to the authorization web service at the following URL.

Within the larger URL, CLIENT_ID is the corresponding client ID, and REDIRECT_URL is the URL to redirect to after the authorization web service successfully signs the user out. The domain portion of this redirect URL must match the one that is specified in the Microsoft account Developer Center for the corresponding client ID.

In this URL example,

  • Replace CLIENT_ID with your app's client ID.

  • Replace REDIRECT_URI with the URI to redirect to after the Live Connect authorization web service successfully signs the user out. The domain portion of this redirect URL must match the one that is specified in the Live Connect app management site for your app's client ID.

https://login.live.com/oauth20_logout.srf?client_id=CLIENT_ID&redirect_uri=REDIRECT_URL

Getting a new access token or refresh token

If you have obtained a refresh token and the access token has expired, you can obtain a replacement access token and a replacement refresh token.

To obtain replacement tokens, make an HTTP POST call to the authorization web service at the following URL.

https://login.live.com/oauth20_token.srf

The Content-Type header should have the value "application/x-www-form-urlencoded". Construct the request body using the following template and replace these elements:

  • Replace CLIENT_ID with your app's client ID.

  • Replace REDIRECT_URI with the URI to your callback webpage. This URI must be the same as the URI that you specified when you requested an authorization code. The URI must use URL escape codes, such as %20 for spaces, %3A for colons, and %2F for forward slashes.

  • Replace CLIENT_SECRET with your app's client secret. The client secret must use URL escape codes, such as %2B for the plus sign.

  • Replace REFRESH_TOKEN with the refresh token that you obtained earlier.

client_id=CLIENT_ID&redirect_uri=REDIRECT_URI&client_secret=CLIENT_SECRET&refresh_token=REFRESH_TOKEN&grant_type=refresh_token

For example, the following request body uses a client ID of 0000000603DB0F, a redirect URI of http://www.contoso.com/callback.php, a client secret of LWILlT555GicSrIATma5qgyBXebRI, and a refresh token that starts with "*LA9" and that ends with "xRoX".

client_id=0000000603DB0F&redirect_uri=http%3A%2F%2Fwww.contoso.com%2Fcallback.php&client_secret=LWILlT555GicSrIATma5qgyBXebRI&refresh_token=*LA9...//refresh token string shortened for example//...xRoX&grant_type=refresh_token

If the call is successful, the authorization web service sends to the callback URI a replacement access token and a replacement refresh token. These tokens are represented as strings of characters, in the access_token and refresh_token key/value pairs, inside a JSON-formatted object, as shown in the following example.

{
    "token_type":"bearer",
    "expires_in": 3600,
    "scope": "wl.offline_access wl.signin wl.basic",
    "access_token":"FxDp...//access token string shortened for example//...BB==",
    "refresh_token":"Cla*...//refresh token string shorted for example//...pdeA",
    "authentication_token":"eyJh...//authentication token string shortened for example//...UWJE"
}

Summary

You have just signed a user in by using the Live SDK REST API. You can now use the Live SDK to request user info. For info on how to request user info, see Getting user data (REST).