Google Maps and other geo-service API Keys
What is this about?
To display IoT end devices or tracked assets on a map, thingsHub uses Google map services. In addition, other Google geocoding services are used to resolve geo-coordinates into addresses. For these functionalities, thingsHub requires API keys to the corresponding services within the Google Cloud.
Google cloud provides it´s services via API´s. These API´s are secured from unauthorised use by using proper authenticated API Keys.
This documents outlines the necessity of managing Google API Keys, the concept of restrictions for API keys, the various Google APIs necessary for a thingsHub On Premise Installation, and gives steps on how to set up the necessary API keys.
Managing Google API Keys
You will need a google cloud project to set up Google API keys and manage them. For instructions on setting up a Google Cloud project, you can consult the official documentation for this: https://developers.google.com/maps/documentation/geocoding/cloud-setup
Why manage your own API keys:
Customers with a on-premise thingsHub deployment should manage their own API Keys for the following reasons:
Security: When you create and manage your own API keys, you have full control over their usage and security parameters. This includes setting restrictions based on IP addresses, referrer URLs, or applications, which limits access to only authorized entities. By maintaining control over your keys, you can prevent unauthorized use and potential breaches that could compromise your systems.
Operational Efficiency: Centralized management of API keys allows for better monitoring, auditing, and troubleshooting. You can track identify anomalies and respond quickly to any suspicious activity or breaches. This ensures that your applications using Google APIs remain efficient and resilient.
Risk Mitigation: In the event of a security incident or key compromise, having your own API keys enables swift response measures. You can rotate keys promptly, limit exposure to affected services, hence minimizing the impact on your overall operations. This helps safeguard your on-premise infrastructure and sensitive data.
Flexibility: Managing your own API keys provides flexibility. You can adjust permissions, add new services, or revoke access as needed, without relying on external parties or shared credentials to do this.
Pricing and Offers
Google APIs use a pay-as-you-go pricing model, where you will only pay for what you use. Google also offers a no charge scheme, where you will not be charged for if your usage does not exceed $200 per month: https://mapsplatform.google.com/pricing/.
In standard on-premise scenarios, it can be assumed that there are no costs for Google Maps. The number of requests should be well below the limit of the $200 no cost plan.
To understand better how these APIs are billed and analyse the costs specifically to your use case, please consult the billing documentation for the respective APIs:
Google Maps JS API: https://developers.google.com/maps/documentation/javascript/usage-and-billing
Google Places API: https://developers.google.com/maps/documentation/places/web-service/usage-and-billing
Google Geocoding API: https://developers.google.com/maps/documentation/geocoding/usage-and-billing
Google Geolocation API: https://developers.google.com/maps/documentation/geolocation/usage-and-billing
However, if you still do not want to manage these API Keys yourself, they can be managed by Smartmakers on the ThingsHub cloud Google Cloud Project.
Restricting API Keys
API Keys can be restricted based on various criteria. These restrictions define the scopes where a specific API Key is valid to be used. If a restricted API Key is used outside its defined scope, the key will not be accepted (e.g. if the Google Geolocation API key is used to send requests to the Places API, the API will return Unauthorized). In Google cloud the following restrictions can be imposed on API keys:
Access Limiting:
Strict API key restrictions can be applied in order to limit access to authorised services and prevent misuse.
Key restrictions based on IP addresses, referrer URLs, or Applications can be enforced in GCP to control where and how keys are used.
Usage Scoping:
API keys can be scoped to specific Google APIs (e.g., Maps JavaScript API, Geocoding API) to align with application use-case requirements and minimise exposure.
Restricting these API keys are important for the following reasons:
Scoped API Keys reduce the attack scope:
Scoped API keys with narrowly defined permissions reduce attack surface in case of security attacks.
If one key is compromised, only the part of the system using this specific key is affected, and other parts are left intact.
Monitoring and Response:
Monitoring individual key usage provides insights into the use (and misuse) of each service.
In cases of security key leaks/breaches, scoping of keys to specific services, make response through key rotation much faster.
Isolation:
Isolating API keys based on their intended functions (e.g., Maps integration, Geolocation services) prevent cross-service contamination, and isolate these on the basis of services.
Domain-based Filtering
Domain-based filtering restricts API key usage to specific domains or web applications.
This enhances the application’s posture by limiting access only to trusted entities and reducing exposure to unauthorised use.
Best Practices for API Key Management:
Operators should set up API keys within a dedicated Google Cloud Project for centralised management and monitoring.
You will need to create a Google Cloud Project after you set up your google account to create and manage API Keys. The following resources will help you do this:Creating a GCP account: https://cloud.google.com/?hl=en
Setting up a Google Cloud Project: https://developers.google.com/maps/documentation/geocoding/cloud-setup
Setting up API Keys: https://support.google.com/googleapi/answer/6158862?hl=en
Creating separate keys for distinct services (e.g., Maps, Geolocation) to enforce granular access controls is highly recommended.
API Keys should be regularly reviewed and rotate keys to mitigate security risks.
API Keys should not be embedded in the code or application and should be store in environment variables or secrets.
Setting up the Google APIs used by ThingsHub
Google Maps JavaScript API and Places API (Mandatory)
The Google Maps JavaScript API embeds interactive maps into thingsHub and can be used to customise and style the default google map.
The Google Places API is used to get information about the location, geography, and places of interest in and around a location.
The Google Maps JavaScript API Key and the Google Maps Places API Key are used in both thingshub and trackinghub mode tenants, so it has to be set up for both thingshub and trackinghub mode tenants.
Setting up the API Key
The Google Maps and Places API Key can be set up in any Google Cloud Project by following the steps:
Enable the Google Maps JS API in Google Cloud Console: https://developers.google.com/maps/documentation/javascript/cloud-setup#enabling-apis
Enable the Google Places API in Google Cloud Console: https://developers.google.com/maps/documentation/javascript/places#enable_apis
Create an API Key for use with the Google Maps JS API and Places API https://support.google.com/googleapi/answer/6158862?hl=en
API Key Restrictions
The scope of the created API Key has to be restricted to the Google Maps JavaScript API and Google Places API.
We also highly recommend restricting this key by domain if thingsHub is running in a fixed address. This is so that it only accepts requests coming from specific addresses where these APIs are to be used.
For detailed instructions on how to restrict the API Key to a specific Google API and web addresses, consult the official Google docs on the topic: https://developers.google.com/maps/api-security-best-practices?hl=en#restricting-api-keys
Using the Key in the tenant configuration file
This API key has to be used in the iam.keys.map field in the iam block of the tenant configuration file.
The relevant snippet of the tenant config where this has to be added is as follows:
...
iam:
...
keys:
map:
key: GOOGLE_MAPS_JS_PLACES_API_KEY
id: fea2d474b8f48035
...
...The id field in the iam.keys.map block is the Google Map ID. This is the identifier for a specific google map styling or feature.
To create a map id and customise the map’s look and features, you can to go to: https://developers.google.com/maps/documentation/get-map-id and create a custom map there.
The default thingsHub Google Maps styling
If you want to use this default thingsHub Google Maps Style, you can set this id to the default value fea2d474b8f48035
Google Geocoding API
Not needed for regular thingsHub tenants. This API key is only required for tenants of mode “trackinghub”.
The Google Geocoding API is used by thingsHub to generate human readable addresses on thingsHub, a process known as reverse geocoding.
The Google Geocoding API Key is only used in tracking use cases. It does not have to be set up for any thingshub mode tenants.
Setting up the API Key
The Google GeoCoding API Key can be set up in any Google Cloud Project by following the steps:
Enable the Google Geocoding API in Google Cloud Console: https://developers.google.com/maps/documentation/javascript/geocoding#GetStarted
Create an API Key for use with the Google Geocoding API https://support.google.com/googleapi/answer/6158862?hl=en
API Key Restrictions
The scope of the created API Key has to be restricted to only the Geocoding API so that it works only with the Geocoding API and nothing else.
For the detailed instructions on how to restrict the API Key to a specific Google API, consult the official Google docs on the topic: https://developers.google.com/maps/api-security-best-practices?hl=en#restricting-api-keys
Using the Key in the tenant configuration file
This Geocoding API key has to be used in the trackinghub block of the tenant configuration file. The relevant snippet of the tenant config where this has to be implemented is mentioned below:
...
trackinghub:
enabled: true
...
gmaps:
enabled: true
access_token: GOOGLE_GEOCODING_API_KEY
...
...Google Geolocation API
Not needed for regular thingsHub tenants. This API key is only required for tenants of mode “trackinghub”.
The Google Geolocation API is used by thingsHub to resolve wifi access point data scanned by a device to the device’s geolocation.
The Google Geolocation API Key is used only in trackinghub mode, so it has to be set up only for trackinghub mode tenants.
Setting up the API Key
The Google Geolocation API Key can be set up in any Google Cloud Project by following the steps:
Enable the Google Geolocation API in Google Cloud Console: https://developers.google.com/maps/documentation/geolocation/cloud-setup#enabling-apis
Create an API Key for use with the Google Geolocation API https://support.google.com/googleapi/answer/6158862?hl=en
API Key Restrictions
The scope of the created API Key has to be restricted to the Google Geolocation API
For detailed instructions on how to restrict the API Key to a specific Google API and web addresses, consult the official Google docs on the topic: https://developers.google.com/maps/api-security-best-practices?hl=en#restricting-api-keys
Using the Key in the tenant configuration file
This Geocoding API key has to be used in the google_geolocation field in the trackinghub block of the tenant configuration file.
The relevant snippet of the tenant config where this has to be added is as follows:
...
trackinghub:
enabled: true
...
google_geolocation:
enabled: true
host: https://www.googleapis.com
api_key: GOOGLE_GEOLOCATION_API_KEY
...
...By adhering to these best practices and creating dedicated API keys mentioned above within a dedicated Google Cloud Project, you ensure a robust security posture tailored to your specific needs. This approach not only enhances security but also optimises the management and performance of Google APIs within ThingsHub.