Acquiring an Access Token

Acquiring an Access Token

Ff750952.note(en-us,MSDN.10).gifNote:
Current information about Live Connect is now available in the Windows Live Developer Center. The information in the following sections is provided for legacy purposes only.

After your application acquires a verification code, it can request an access token. An access token enables applications to acquire user information from a protected resource, such as Windows Live Messenger. When you first request an access token, you receive a date at which the token expires, and a refresh token that you can use to acquire a new access token. You can continue to request new access tokens until a user's consent has expired.

You must submit your request for an access token as a POST message. The following code illustrates how to use a verification code to request an access token.

private string GetAccessToken()
{
    NameValueCollection appSettings = WebConfigurationManager.AppSettings;

    string requestUrl = "https://consent.live.com/AccessToken.aspx";

    // Request the access token.
    string postData = string.Format(        "{0}?wrap_client_id={1}&wrap_client_secret={2}&wrap_callback={3}&wrap_verification_code={4}&idtype={5}",
            requestUrl,
            appSettings["wll_appid"],
            appSettings["wll_secret"],
            "http://www.fabrikam.com",
            verificationCode,
            "CID");
    byte[] postDataEncoded = System.Text.Encoding.UTF8.GetBytes(postData);

    WebRequest req = HttpWebRequest.Create(requestUrl);
    req.Method = "POST";
    req.ContentType = "application/x-www-form-urlencoded";
    req.ContentLength = postDataEncoded.Length;

    Stream requestStream = req.GetRequestStream();
    requestStream.Write(postDataEncoded, 0, postDataEncoded.Length);

    WebResponse res = req.GetResponse();

    string responseBody = null;

    using (StreamReader sr = new StreamReader(res.GetResponseStream(), Encoding.UTF8))
    {
        responseBody = sr.ReadToEnd();
    }

    // Process FORM POST.
    NameValueCollection responseCollection = System.Web.HttpUtility.ParseQueryString(responseBody);

    return responseCollection["wrap_access_token"];
}

The following table describes the request elements for an access token.

Element Description

URL endpoint

Provides the Windows Live endpoint that processes the request. In most cases, this endpoint is https://consent.live.com/AccessToken.aspx.

You must access this URL by using SSL.

wrap_client_id

Contains the client ID that identifies your application. If you do not have an client ID, you can learn how to get one in the section, Getting Started with Messenger Connect.

An example of a client ID is 00000000680240A2.

wrap_client_secret

Contains the secret key that you defined when you created your client ID.

wrap_callback

Provides the URL to which the Windows Live service sends the verification code. The value for this parameter must match the wrap_callback value used in the verification token request, including any querystring parameters.

An example of a callback URL is http://www.fabrikam.com/OAuth.aspx.

wrap_verification_code

Contains the verification code that you acquired when the user provided consent to your application.

An example of a verification code is 2fabb60c-eb3a-0c68-d5f1-21efe462e9c0.

idtype

Specifies the format in which you want to receive the user identifier. Windows Live supports two formats: CID and PWID. The default value is CID.

Ff750952.note(en-us,MSDN.10).gifNote:
You should use PWID only if the protected resource that is accessed by your application requests it.

To access a protected resource that contains user data, such as Hotmail or Windows Live Messenger actions, your application must request an access token from the Windows Live service. This request must be formatted as a POST message to ensure the security of the verification code included in the request.

Ff750952.note(en-us,MSDN.10).gifNote:
An initial request for an access token requires a verification code. For more information, see Acquiring a Verification Code.

A success response from the Windows Live service contains the following information.

Element Description

wrap_access_token

Contains the access token that your application can use to acquire user information from a protected resource.

wrap_access_token_expires_in

Indicates when the access token expires. The value in this parameter is the number of seconds from the creation of the access token. For example, if the protected resource that is accessed by your application defines the expiration time as one minute, the value of this parameter is 60. Note that different protected resources can have different time-to-live values for access tokens.

wrap_refresh_token

Contains the token you use to obtain a new access token after the previous one expires. You can continue to use the refresh token until the user's consent expires.

skey

A value that is specific to the Windows Live implementation of the OAuth WRAP protocol. The skey parameter is a secret key that is shared between the protected resource and your application. You do not need to use this value unless the protected resource that is accessed by your application requests it.

uid

A value that is specific to the Windows Live implementation of the OAuth WRAP protocol. The uid parameter contains a user identifier that is specific to the individual user who provided consent to your application.

After you acquire an access token, you have several options available. In most cases, we recommend storing the access token in a server session. However, some Windows Live services might require that you store the token in another manner. In these situations, information on how to store the token is available in the documentation pertaining to the Windows Live service.

We also recommend that you store the refresh token in a reliable location, such as a database. When your application detects that an access token has expired (either by tracking the current time against the expiration value returned from the Windows Live service or if the protected resource does not accept the access token), you use the refresh token to request a new access token. This process enables your application to access a user's information from a protected resource until the consent period specified by the user expires. See Refreshing an Access Token for more information.

Ff750952.note(en-us,MSDN.10).gifNote:
If a user revokes consent before the refresh token expires, the Windows Live service automatically invalidates the token so that it cannot be used. If your application currently has a valid access token, that token might remain valid until it expires, regardless of whether the user revokes consent.
Show:
© 2016 Microsoft