Was this page helpful?
Your feedback about this content is important. Let us know what you think.
Additional feedback?
1500 characters remaining
How to: Handle Authentication Requests
Collapse the table of content
Expand the table of content

How to: Handle Authentication Requests

Updated: October 9, 2012

Applies To: Windows Server 2012 Essentials

This section describes the handling of logon and logoff requests.

Handling Logon Requests

To call a web service, the client must perform these steps:

  1. Add the caller's credential in an HTTP header field. The caller's credential is encoded text that is based on the user name and the password.

  2. Add Appname, Apppublisher, and Appversion values in HTTP header fields. These values are also required to log on.

  3. Call the logon method to retrieve the authenticated user canary token that is issued by the server.

  4. Send subsequent web service requests with the user canary token in the request header.

Sample Logon Request

The client requests an Authorization header field that contains the authentication type (Basic), a space, and a base-64 string that encodes the user name/password combination, with a colon (:) between the user name and password. In this case, the string User:Password! is encoded into base-64 format.

GET https://www.contoso.com/services/builtin/session.svc/login HTTP/1.1
Accept: application/xml
Host: servername
Authorization: Basic VXNlcjpQYXNzd29yZCE=
Appname: Sample App Name
Apppublisher: publisher
Appversion: 1.0

Sample Logon Response

The server responds to this request with a user canary token in the cookie highlighted below. If no subsequent calls are made in the session, the session identifier and the user canary token expire in 30 minutes.

HTTP/1.1 200 OK
Cache-Control: private
Server: Microsoft-IIS/8.0
Set-Cookie: ASP.NET_SessionId=gemffw0zn3ybci4ccqervley; path=/; HttpOnly
Canary: 60094f67-7cbf-6af1-b5fb-1944397c51e2
X-AspNet-Version: 4.0.30319
X-Powered-By: ASP.NET
X-Content-Type-Options: nosniff
Date: Tue, 11 Oct 2011 08:19:09 GMT
Content-Length: 0

Sample Subsequent Request

For subsequent calls, the client needs to include the canary header in the request headers and ASP.NET_SessionId header fields in the request cookie

GET https://www.contoso.com/services/builtin/sessionservice.svc/login HTTP/1.1
Accept: application/xml
Cookie: ASP.NET_SessionId= gemffw0zn3ybci4ccqervley
Canary: 60094f67-7cbf-6af1-b5fb-1944397c51e2

Error Codes

If the request fails to provide credentials or the user canary token, the server returns an error code and an error message:


Error Code Error Message


Invalid user name or password.

Handling Logoff Requests

To invalidate the session and the user token, you can call the logoff method explicitly. To prevent cookie spoofing, the caller should log off when the application exits.

Sample Logoff Request

GET https://www.contoso.com/services/builtin/Session.svc/logout HTTP/1.1
Accept: application/xml
Cookie: ASP.NET_SessionId= gemffw0zn3ybci4ccqervley
Canary: 60094f67-7cbf-6af1-b5fb-1944397c51e2
Host: servername

Sample Logoff Response

HTTP/1.1 200 OK

© 2015 Microsoft