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.
To call a web service, the client must perform these steps:
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.
Appversionvalues in HTTP header fields. These values are also required to log on.
Call the logon method to retrieve the authenticated user canary token that is issued by the server.
Send subsequent web service requests with the user canary token in the request header.
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
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
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
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|
|403||Invalid user name or password.|
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.
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
HTTP/1.1 200 OK