Connecting to the APIs

Summary

  • Endpoint names and IPs: Use DNS names (i.e. https://api.telenor.io/) all the time, and never cache IP lookups beyond the "time to live" time: IPs may change on 60 seconds notice due to being hosted on Cloud-based load balancers.
  • Transport: HTTPS.
  • Authentication: HTTP Basic authentication.
  • Test that connectivity works using the actual software you'll be integrating with - all simple tools will happily talk to us given the protocols above, but your tool may have other constraints. See Testing connectivity.

Important: All partners that want to use the external Global Backend API should test connectivity from their integration software at an early stage in the integration.

Authentication

HTTP Basic Authentication over SSL is used for the Telenor Digital API. See RFC 2617 – HTTP Authentication: Basic and Digest Access Authentication for more information. The fact that Telenor Digital use REST-style APIs over HTTP and secure it using SSL, means that API traffic is equivalent to any other secure HTTPS traffic from a firewall and networking viewpoint. It's also easy to make manual invocations of the API using regular command line tools such as curl and wget, and simple GET calls can also be made using any browser.

DNS names and IP addresses

Our API endpoints are specified simply as https://api.telenor.io/ (see environments for a list of endpoint names). Use regular DNS resolution as provided by your OS/runtime platform to determine the IP addresses serving these at any time.

To provide high availability and good performance in our cloud environment we use a load balancing service as our internet-facing endpoint for both web front-ends and API front-ends. It provides SSL termination, and forwards all traffic to our front-end servers over a private network.

One of the quirks of the load balancer that it is operating in a dynamic environment where load is actively managed and continuously shifted around. In practice this means that when you resolve api.telenor.io or another of our endpoint names, the response will come back with a time-to-live of only 60 seconds. Yes, we only guarantee that our endpoints will have the same IP addresses for one minute. This is not just a formality either, we routinely see our resolved IP change, even several times within a ten-minute window.

The consequence of this is that DNS resolution cannot be cached beyond what is specified in the DNS response. If you do not want to actively manage this yourself, we recommend that you in your application always refer to the DNS name or complete URLs, and never store the resolved IP address. Do trust the local DNS servers of your datacenter to do caching for you, as they are likely to do it correctly, but do not bother with any caching on your own, as the cost/benefit ratio is high.

Firewalls

Telenor Digital cannot provide IPs which the BUs need to open firewalls for, as we use a load balancing service whose IPs change on a minute's notice as discussed above.

BU firewalls need to permit outgoing requests to port 443 for all of the Internet, or at least at least this list of IP ranges published by our cloud services provider: AWS IP Address Ranges

As these ranges encompass all of our cloud services providers address space, little security is gained from restricting access to only this range, as anyone can host an SSL service there simply by paying a few cents per hour, which is certainly within the reach of a determined attacker using HTTPS as a transport for attack payloads. However, excellent assurance that you're talking to Telenor Digital is provided by the use of SSL certificates, see below. If strict assurance that attackers that achieve limited access to an integration server cannot connect back out to retrieve attack payloads is required, we recommend deploying an application level security gateway in the DMZ to mediate between internal hosts not permitted to connect outside and Telenor Digital API services.

Certificates

  • Client side certificate is not used for the CONNECT API. If your integration software requires a client certificate, you can make a self-signed one. It will not be verified by the Telenor Digital endpoint.
  • The SSL certificates needs to be replaced periodically. New certificates will normally be announced to clients one month before they are replaced. However, if some event has caused a possibility that the certificates have been compromised, they may have to be changed on short notice. In this case clients may not be notified until after the certificates have been changed. We recommend that clients accept certificates from all commonly trusted root certificates to minimize risk for down time.

Testing connectivity

A simple and harmless way to verify connectivity to the API service is to perform a simple HTTP GET request with basic authentication to https://api.staging.telenor.io/id/users. This endpoint requires authentication in the exact same manner that all our other APIs do, but requires no special privileges beyond being provisioned as an API user. You will naturally be provided with an API account when integrating with Telenor Digital.

The HTTP response will look somewhat like this: HTTP 200, followed by headers indicating among other things what content is returned, and a small body containing JSON data. (The JSON data in this case provides pointers to REST API services for managing users.)

© 2017 Telenor Digital AS