Share via

MapPoint Web Service Authentication

  • Article

MapPoint Web Service Authentication

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 by 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. Microsoft 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 Access credentials if you are programming by using the Microsoft .NET Framework and Microsoft Visual Studio .NET:

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

In the preceding code, 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. You can set this value 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 will get an HTTP 401 error. You must authenticate each service before you use it, and then you can make as many method calls as you want 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. For more informatiom, 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.

  • You can reset your MapPoint Web Service password on the MapPoint Web Service Customer Services site (https://mappoint-css.live.com/CSCV3/). The new password becomes effective within two hours of your making the change. The original password expires immediately unless you specify otherwise. Please keep in mind that the password expiration may interrupt your access to MapPoint Web Service for up to two hours. If you do not want to cause any interruption, you can keep the original password as a secondary password for a maximum period of seven calendar days so that you can keep using the service while the password is reset. 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;