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:

  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 CodeError Message
403Invalid 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.

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  

Community Additions

ADD
Show: