API Keys - AtlasOfLivingAustralia/documentation GitHub Wiki

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.