Share via

MapPoint Web Service Authentication

  • Article

MapPoint Web Service uses the HTTP Digest Access authentication protocol to authenticate the calls made to the SOAP APIs. The Digest Access authentication scheme is based on a simple challenge-response paradigm; the server challenges the client using a nonce value. A valid response from the client contains the MD5 checksum of the user name, the password, the given nonce value, the HTTP method, and the requested Uniform Resource Identifier (URI). In this way, the password is never sent in clear text.

The MapPoint Web Service server implements the server side of the protocol described in RFC 2617 (https://www.ietf.org/rfc/rfc2617.txt). Any client making SOAP requests to MapPoint Web Service needs to implement the client portion of the Digest Access authentication protocol. Most of the Microsoft HTTP client stacks implement the client portion if you are using a Microsoft API to send the SOAP requests. These APIs include Microsoft Win32 Internet functions, as well as the Managed Code HTTP classes. Using these APIs makes it easy to send authentication information along with the SOAP requests.

The following line of Microsoft Visual C# code is sufficient for sending Digest credentials if you are programming using Microsoft .NET Framework and Microsoft Visual Studio .NET:

  	myFindService.Credentials = new System.Net.NetworkCredential("123", "Password");

where "123" is your MapPoint Web Service customer ID and "Password" is your password.

To make authentication more efficient, we recommend that you set the Preauthentication property on your SOAP proxy. Setting this property eliminates extra round trips for authentication purposes. This value can be set by using the following line of C# code:

  	myFindService.PreAuthenticate = true;

Remarks

  • Your MapPoint Web Service ID (the decimal format of your customer ID as a string) and password (string) were sent in the customer information that you received when you enrolled in the service.

  • The credentials must be set before you call any of the methods of the FindServiceSoap, RenderServiceSoap, RouteServiceSoap, or CommonServiceSoap classes, otherwise, you'll get an HTTP 401 error. You must authenticate each service before you use it, and then make as many method calls as you like on that service object.

  • For security purposes, we recommend that you change your MapPoint Web Service password every 60 to 90 days. Also, we recommend that you store your credentials in a secure fashion, such as in an encrypted file on your server's hard disk. See the Cryptography (https://msdn.microsoft.com/library/en-us/security/security/cryptography_portal.asp) and Security (https://msdn.microsoft.com/library/default.asp?url=/nhp/default.asp?contentid=28001191) articles on MSDN for more information.

  • You can reset your MapPoint Web Service password on the MapPoint Web Service Customer Services Web site (https://mappoint-css.partners.extranet.microsoft.com/cscv3/). The new password becomes effective within 2 hours of making the change. The original password expires immediately unless otherwise specified. Please keep in mind that this may cause an interruption to access the MapPoint Web Service at least for two hours. If you don't want to cause any interruption you can keep the original password as a secondary password for a maximum period of seven calendar days, which allows you to keep using the service while the password reset is implemented. Passwords can be changed as often as needed.

    Note  For information on becoming a customer, visit the MapPoint Web Service Web site (https://www.microsoft.com/mappoint/webservice).

Example

 
[Visual Basic] 
' Initialize the credentials of the find service
' Use your customer ID and password for the UserID and Password parameters
Dim findService As New FindServiceSoap()
findService.Credentials = New System.Net.NetworkCredential("UserID", "Password")
findService.PreAuthenticate = True

 
[C#]
// Initialize the credentials of the find service
// Use your customer ID and password for the UserID and Password parameters
FindServiceSoap findService  = new FindServiceSoap();
findService.Credentials = new System.Net.NetworkCredential("UserID", "Password");
findService.PreAuthenticate = true;

 

See Also

Accessing the MapPoint Web Service SOAP API