Export (0) Print
Expand All

Requesting Consent

Cc287661.note(en-us,MSDN.10).gifNote:
This topic describes functionality that will be obsolete. This functionality is provided only to support legacy applications. Live Connect incorporates features that provide equivalent functionality.

You request consent for specific offers and actions from a resource provider by sending consent information to the consent-request URL for the Windows Live ID consent service. The consent service then displays the consent-request user interface (UI) to the Windows Live ID user, enabling him or her to grant or deny consent to the requested offers and actions. The consent service then returns a response to your Web site's return URL (which you specified in the RU parameter of the request).

The following syntax describes the consent-request URL for the Windows Live ID consent service.

https://consent.live.com/Delegation.aspx?RU=...&ps=...&pl=...[&app=...][&mkt=...][&appctx=...]

The consent-request URL takes the following parameters.

Parameter Name Full Name Description

RU

Return URL

The URL of the page on your Web site to which the consent service redirects users (along with the action, consent token, and application context) after they have successfully provided consent information.

You must create a page on your site corresponding to the return URL, to handle the response from the consent service.

The return URL must be a fully qualified Domain Name System (DNS) URL pointing to a page on your Web site, and it must not contain IP addresses or query-string parameters. For more information about registering applications, see Getting Your Client ID for Delegated Authentication.

ps

Permissions

Required. A comma-delimited list of permissions, describing the offers and actions provided by the resource provider to which you are requesting access.

Cc287661.note(en-us,MSDN.10).gifNote:
The Windows Live ID consent service displays information only about permissions for which you explicitly request consent.
For example, if your Web site requests access to the View and Update actions of the Contacts offer for a resource provider, the following value represents the permissions list.
Contacts.View,Contacts.Update

pl

Privacy policy URL

Required. The URL of the page on your Web site, called the privacy policy URL, to which the Windows Live ID consent service redirects users to view the privacy policy of your Web site.

You must create a page on your site corresponding to the return URL, to handle the response from the consent service.

app

Application verifier token

A token used to identify your application to Windows Live ID. An application verifier token consists of your client ID and a time stamp (and, optionally, the user's client IP address), signed with your secret key. Required only if the resource provider requires an application verifier; otherwise this value is optional.

Cc287661.note(en-us,MSDN.10).gifNote:
If a value is not supplied for this parameter, a value must be supplied for the RU parameter.

mkt

Market

Optional. The culture name of your Web site, according to the RFC 1766 standard format:

<languagecode2>-country/regioncode2>

where <languagecode2> is a lowercase, two-letter code derived from ISO 639-1 and <country/regioncode2> is an uppercase, two-letter code derived from ISO 3166. For example, the following value represents the culture name for English (United States):

en-US

For more information about using culture names to support localization and globalization in your Web site, see Design and Implementation Guidelines for Web Clients on MSDN.

appctx

Application context

Optional. A value representing context for your application. For example, if the user is on your page www.example.com/xyz.htm when you request consent, you can pass "xyz.htm" to the consent service as context. When the user is redirected back to your site, you can use the context parameter to send him or her back to xyz.htm to continue the previous activity.

Cc287661.note(en-us,MSDN.10).gifNote:
To help protect against script-injection attacks, there are limitations on the strings that may be specified for the context parameter. Script of any kind is strictly forbidden. The Windows Live ID consent service will convert unsafe characters to safe characters or may discard the value that you provide altogether.
Additionally, the total length of a URL in Internet Explorer 4.0 or later is limited to 2083 characters. The length of the value for this parameter must be less than that limit, minus the total length of the rest of the consent-request URL.
We recommend that you handle state in your application by using your own proprietary cookies.

ttype

Token type

Optional. Specifies the type of delegation token you want the Windows Live service to return after a user has granted consent. If the resource provider requires the delegation token to be in the standard Compact Ticket format, you do not need to use this parameter. The following table lists the values you can assign to this parameter.

Parameter Value Description
1Compact Ticket
2SAML
Cc287661.note(en-us,MSDN.10).gifNote:
If the resource provider requires the token in SAML format, you must supply this parameter in the following format: ttype=2.
Cc287661.note(en-us,MSDN.10).gifNote:
The function library included with this SDK provides methods that automatically construct a consent-request URL. If you want more details about how to build your consent request URL, we recommend that you review the library and associated sample files for your preferred programming language. For information about how to obtain the function library and sample files, see Samples for Delegated Authentication.

When the application provider passes the received consent information to the Windows Live ID consent service, along with additional information identifying the resource provider, the Windows Live ID consent service displays the consent request user interface.

Each offer and action identified by the resource provider is displayed on this page, along with a suggested expiration date.

If the resource provider specifies granular permissions for a given action, the user can click View and Change Details to display and either grant or deny consent for the additional granular permissions associated with that action.

If an error occurs while the user is granting or denying consent, or if your Web site does not have access to one or more requested offers or actions, an error is returned and an error page is displayed.

For more information about errors returned by the Windows Live ID service, see Error Codes.

The Windows Live ID consent service enables the user to control which resources your Web site can access from a resource provider, and it stores that consent information for later validation when your Web site uses the information contained in the consent token to invoke those resources. For more information about the contents of the consent token, see Consent Tokens.

After the user has granted or denied consent to the offers and actions requested by your Web site, the Windows Live ID consent service returns the consent information in an HTTP POST to the return URL you specified in your consent request. The POST body contains four parameters, described in the following table.

Parameter Description

ResponseCode

The response code, which represents the status of the consent request issued by your Web site. This parameter can contain one of the following response codes.

Value Description
0The consent request process was completed by the Windows Live ID user.
1The consent request process was canceled by the Windows Live ID user.

ConsentToken

The consent token, which represents the results of the consent request issued by your Web site. This value is returned only if the consent request was completed by the Windows Live ID user. For information about the structure and contents of this token, see Consent Tokens.

action

The action that the user is doing. The list of possible values is as follows:

  • delauth—The user has completed a successful consent-request process.

appctx

The context parameter that you passed when requesting consent. You can use this parameter to keep track of what page the user was on or other user-state information.

The Windows Live ID Delegated Authentication SDK includes two samples that demonstrate how to request, receive, parse, and use consent tokens. For more information about handling consent-request information, see Samples for Delegated Authentication.

The following is an example of a consent-request URL used by an application provider to request consent to view and update contact information.

https://consent.live.com/delegation.aspx?ru=http://mydomain.myapp.com/ReturnURL.htm&ps=Contacts.View,Contacts.Update&pl=http://mydomain.myapp.com/PrivacyPolicy.htm&app=appid%3d10000%26ts%3d1193445084%26ip%3d157.56.190.178%26sig%3d7HgcsIEheEVO30BuPAEJhJeB8Pz0xHBV%252f%252bQD27AOdmI%253d

Other Resources

Live Connect

Show:
© 2014 Microsoft