Partner Authentication

This Technical Concept is relevant to all services

Characteristic

Short description

Partner Authentication allows PTV xServer to be restricted for specific applications. It is based on the well-known Google Authenticator (which relies on RFC4226).

Use

Partner Authentication is used for other PTV Products where PTV xServer is supplied as a sub-component. But it can also be used in customer projects where it must be ensured that only authorized applications have access to PTV xServer.

Detailed Consideration

How it works

For Partner Authentication the client and PTV xServer share a secret key. The client uses the key and the current time to calculate a One-Time Password which is then added to the HTTP header 'PARTNER_AUTHENTICATION' of a request. PTV xServer verifies this password before it calculates the request. If the password is not valid the request is rejected with an exception. The algorithm requires that the clocks of the client and the server are roughly synchronized because the passwords change in 30-second intervals. The figure below illustrates these steps.

Set up Partner Authentication

Partner Authentication is set up by using a dedicated license. So please contact your PTV representative to obtain a license with activated Partner Authentication. With this license you will also receive the shared secret which is needed to authorize your client application.

Use Partner Authentication with C# clients

To calculate the current One-Time Password C# clients can use this NuGet library https://github.com/glacasa/TwoStepsAuthenticator:

using TwoStepsAuthenticator;
...
string secret = "TheSecretKey";
TimeAuthenticator authenticator = new TimeAuthenticator();
string code = authenticator.GetCode(secret);

Here's an example using xRoute....

var xRouteClient = new XRouteClient();
try
{
    using (new OperationContextScope(xRouteClient.InnerChannel))
    {
        TimeAuthenticator authenticator = new TimeAuthenticator();
        HttpRequestMessageProperty requestMessage = new HttpRequestMessageProperty();
        requestMessage.Headers["PARTNER_AUTHENTICATION"] = authenticator.GetCode("TheSecretKey");
                    
        OperationContext.Current.OutgoingMessageProperties[HttpRequestMessageProperty.Name] = requestMessage;
 
        var xRouteResult = xRouteClient.calculateRoute(new RouteRequest
        {
            waypoints = new[] {
                new OffRoadWaypoint { location = new OffRoadRouteLocation { offRoadCoordinate = new Coordinate { x = 6.1256572, y = 49.5983745 } } },
                new OffRoadWaypoint { location = new OffRoadRouteLocation { offRoadCoordinate = new Coordinate { x = 6.1256572, y = 49.4816576 } } }
            },
        });
 
        System.Console.WriteLine("Calculated route distance: " + xRouteResult.distance);
 
    }
}
catch (System.ServiceModel.FaultException<XServerFault> e)
{
    System.Console.WriteLine("Got exception: " + e.Message);
    System.Console.WriteLine("Hint: " + e.Detail.hint);
}

Use Partner Authentication with Java clients

Java developers can use the GoogleAuth library for calculating One-Time Passwords:

import com.warrenstrange.googleauth.GoogleAuthenticator;
...
String secret = "TheSecretKey";
GoogleAuthenticator googleAuthenticator = new GoogleAuthenticator();
String oneTimePassword = Integer.toString(googleAuthenticator.getTotpPassword(secret));

Here's an example for using GoogleAuth with xRoute...

// create a xroute client
XRoute_Service xRoute_Service = new XRoute_Service(new URL(XROUTE_WS_URL));
XRoute client = (XRoute) xRoute_Service.getXroute();

// create TOTP
GoogleAuthenticator googleAuthenticator = new GoogleAuthenticator();
String oneTimePassword = Integer.toString(googleAuthenticator.getTotpPassword(secret));

// set HTTP header
BindingProvider bindingProvider = (BindingProvider) client; 
Map<String, List<String>> requestHeaders = new HashMap<String, List<String>>();        
requestHeaders.put("PARTNER_AUTHENTICATION", Arrays.asList(oneTimePassword));
bindingProvider.getRequestContext().put(MessageContext.HTTP_REQUEST_HEADERS, requestHeaders);

// create a RouteReequest and set up 2 waypoints
RouteRequest request = new RouteRequest();
OffRoadWaypoint w1 = new OffRoadWaypoint();
OffRoadRouteLocation orl1 = new OffRoadRouteLocation();
Coordinate c1 = new Coordinate();
c1.setX(6.22029);
c1.setY(49.61513);
orl1.setOffRoadCoordinate(c1);
w1.setLocation(orl1);
OffRoadWaypoint w2 = new OffRoadWaypoint();
OffRoadRouteLocation orl2 = new OffRoadRouteLocation();
Coordinate c2 = new Coordinate();
c2.setX(6.06479);
c2.setY(49.62127);
orl2.setOffRoadCoordinate(c2);
w2.setLocation(orl2);
request.getWaypoints().add(w1);
request.getWaypoints().add(w2);

// run the request
RouteResponse response = client.calculateRoute(request);

Authentication in Raw Request Runner

You can use Google's Authenticator (available for Android and iOS) to create passwords for executing requests in the Raw Request Runner. Just add a new account in the Authenticator app and enter your xServer secret. Then open the Raw Request Runner and click the envelope icon to open up the HTTP header editor window. Then type in 'PARTNER_AUTHENTICATION:' and the current password from the authenticator app. Now you can execute the request!

Good to know

Use

xRuntime.*, xData.listHighPerformanceRoutingNetworks, xData.listContentSnapshots and xDima.listDistanceMatrices are not restricted by a partner license.

Developer's Guide	HTTP Requests