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.
Add
Appname,Apppublisher, andAppversionvalues 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.
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 |
|---|---|
| 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.
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