API Keys - AtlasOfLivingAustralia/documentation Wiki

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

Work in progress

Introduction

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

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:

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:

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.

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 as well as the non ALA API keys in order to integrate all LA modules and external services correctly.