API Keys

Everything You Always Wanted to Know About ALA API Keys But Were Afraid to Ask

Work in progress

• Introduction
• Creating API keys
• Some API keys variables and usages
  • Creating API keys
    • Non ALA keys
    • ALA new keys
• Some configurable API keys variables and usages

Introduction

As far we know there are three types of API keys in ALA:

• External API keys: That is Google Maps, trove, bhl, maxmind, flickr, etc, keys
• Old ALA keys: Simple secrets strings configured in modules config/properties used to authorize some update operations by other modules and trusted components
• New ALA keys: The same but generated and validated in the apikey service, that is https://auth.l-a.site/apikey

New API keys usage is a work in progress, you can see a good summary in this issue.

One of the use of API keys is allow admins generate and configure API Keys in modules that later can used by these modules or apps for some web service calls (for instance, those that can update our data).

These keys are verified externally via /ws/check.

As a sample:

• in BIE this is used to allow a write call that updateImages (preferred ones) but not for the rest of calls.
• in Specieslist is used to allow create a new list via webservice.
• in Biocache many operations are performed if there are requested by a correct user or a correct API Key.
• Etcetera.

Creating API keys

Non ALA keys

You should request and configure (via, for instance, your ansible inventories) some API Keys from external services in order to ALA modules work properly:

• Google Map API Key (used by several services like Biocache or Spatial): https://developers.google.com/maps/documentation/javascript/get-api-key (set google_api_key and google_apikey in your inventories)
• Mapbox access token (used by collections: https://account.mapbox.com/auth/signup/) (mapbox_access_token ansible variable)
• Trove API Key (used by species): https://help.nla.gov.au/trove/building-with-trove/api (trove_api_key ansible variable)
• BHL API key (used also by species): https://www.biodiversitylibrary.org/getapikey.aspx (bhl_api_key variable)
• Maxmind (the company providing the geoip database): https://dev.maxmind.com/geoip/geoipupdate/ (maxmind_account_id and maxmind_license_key ansible variable). You need to create and account here and later your license key and also set geoip_enabled=true in your inventories to download it.
• JournalMap (used by spatial-service): https://www.journalmap.org/developer/documentation/1-0 (journalmap.api_key variable)
• Scistarter (used by ecodata): https://scistarter.org/API (scistarter_api_key variable)

CAS

If you want to use external authentication via CAS (like Google, Github, Facebook, etc authentication): you will need keys from the providers you want to use. Some examples are in the local-extras inventory template. See also the OAuth-OpenId-Authentication Documentation.

ALA new keys

For creating API keys you should be authenticated in you CAS system via https://auth.l-a.site/cas/login and have a ROLE_ADMIN. See Roles for more info. Then you will able to create keys in your https://auth.l-a.site/apikey.

In general it's better to use these generated new keys in old LA deployments instead of the dummy keys provided in the sample inventories.

Some configurable API keys variables and usages

Module / role	config variable	ansible variable	Description
collectory	security.apikey.checkEnabled	api_key_check_enabled	If enabled true Collectory Webservices authenticate POST, PUT and DELETE calls via valid new api keys. The IPT of data providers can be scanned also via a scan call authenticated with an API Key.
collectory	gbifEndorsingNodeKey	gbif_endorsing_node_key	GBIF connection info
collectory	gbifInstallationKey	gbif_installation_key	GBIF connection info
collectory	api_key	api_key	It seems and old type ALA key, and should match the registry_api_key used in other roles like biocache-properties and specieslists
biocache-hub	biocache.apiKey	biocache_api_key	Used to perform some update operations over biocache-service, like addAssertion, deleteAssertion, getRecords.
biocache-hub	bieApiKey	bie_index_api_key	It seems that is used by Preferred Species (FIXME: verify this in the code).
biocache-properties	registry.api.key	registry_api_key	This key should match collectory api_key
biocache-properties	imageservice.api.key	image_service_apiKey	Used by biocache-store to upload images to the Images service
biocache-properties	doi.service.apiKey	doi_service_apiKey	Used by biocache-service to updated the DOI service
species-list	registryApiKey	registry_api_key	This key should match collectory api_key
bie-hub	bieService.apiKey	bie_index_api_key	Used to mark preferred images
bie-hub	speciesList.apiKey	speciesList_api_key	FIXME It seems that is a variable added to ala-install but not yet in use.
spatial-hub	api_key	spatial_service_api_key	FIXME Used, for instance to send tasks to spatial-service, should match spatial-service serviceKey or be a valid new API key
spatial-service	api_key	spatial_service_api_key	FIXME: It seems to me that this is not used in spatial-service only serviceKey.
spatial-service	serviceKey	spatial_service_service_key	FIXME: It seeems that this is used to have several spatial-service slaves and authenticate tasks operations. Can be a valid new API key or simple match the spatial-hub api_key.
spatial-service	slaveKey	spatial_service_slave_key	FIXME: It seems that this is used to have several spatial-service slaves and authenticate tasks operations.

Mapbox collectory workaround

Since collectory 3.1.3 the mapbox access token should be configured, as the previous access token was hard coded and cannot be used. In this case, you should create a mapbox account and request an access token and configure it via the ansible variable mapbox_access_token.

But if you are still using an old version of ala-collectory or collectory, and you don't want to migrate still to collectory 3.1.3 you can workaround this with something like:

for i in `grep -r pk.eyJ1IjoibWFwYm94IiwiYSI6ImNpejY4NXVycTA2emYycXBndHRqcmZ3N3gifQ.rJcFIG214AriISLbB6B5aw /var/lib/tomcat9/ | cut -d":" -f 1`; do perl -p -i -e 's/pk.eyJ1IjoibWFwYm94IiwiYSI6ImNpejY4NXVycTA2emYycXBndHRqcmZ3N3gifQ.rJcFIG214AriISLbB6B5aw/SOMENEWACCESSTOKENHERE/g' $i; done

cd $(dirname `find /var/lib/tomcat9 -name 'map*js.gz'  | head -1 `)
for i in `ls application-map-*.js map.js`; do gzip -kf $i; done
service tomcat9 restart

Summary to new LA deployments

After CAS/userdetails/apikey deployment you should generate and configure in your inventories the above ansible variables for ALA API Keys (although if you are using the LA-Toolkit this is done automatically with the toolkit) as well as the non ALA API keys in order to integrate all LA modules and external services correctly.