Securing DataSource connections with API keys

Using SSL encrypted datasource connections with certificate pinning, it has long been possible to ensure that only authorised peers can connect to a DataSource.

Platform 8 introduces more granular control over connection authorisation with API keys, to which you can assign one or more security roles.

Available from: Platform 8

Overview

With the introduction of powerful dynamic features in Platform 8, it may well be desirable to control whether adapters can supply data service information or add to the dynamic field set.

To achieve this, Platform 8 supports API keys that are mapped at the receiving end to a set of roles that control which dynamic features are available.

The following roles are available:

Role Description

ds-connect

Allow a peer to connect

ds-dynamic-fields

Allow a peer to supply and receive field codes

ds-dynamic-peer

Allow a peer to connect dynamically

ds-dynamic-service

Allow a peer to supply data-service configuration

For more details, see add-apikey and add-peer::apikey.

Once add-apikey has been added to a Liberator’s or Transformer’s configuration, all dynamic peer connections to that application need to use an API key.

Setting up API keys

The following steps should be followed to apply API key authentication to a datasource connection.

Follow the steps below to create an API key and configure the initiating and receiving peers:

  1. Devise a random key phrase for the API key.

  2. In the configuration of the initiating peer, specify the random key phrase using the appropriate configuration below:

    Discovery deployment
    datasrc-apikey "random_phrase"
    Non-Discovery deployment
    add-peer
    ...
    apikey "random_phrase"
end-peer

  3. In the configuration of the receiving peer, map the SHA256 hash of the random key phrase to a comma-separated list of security roles using the configuration below:

    add-apikey sha256_hash "roles"

    You can generate the SHA256 hash of the random phrase using the sha256sum command line tool:

    echo -n 'random_phrase' | sha256sum

    For a list of available roles, see the documentation for add-apikey.

For a practical application of the steps above, see the example below.

Example 1. Securing dynamic peer connections to a Liberator

Consider a Liberator and a connecting peer.

In this example, we want the peer to be able to connect as a dynamic peer and exchange dynamic field codes, but we don’t want to allow the peer to provide dynamic service configuration.

We will use the random phrase 9702ff749fc8bc340053059b1029b491 as the API key, with a SHA256 hash as generated below:

$ echo -n '9702ff749fc8bc340053059b1029b491' | sha256sum
f9912b266474a1805205454548fa6e4f80f5f688a379481d14976bdbea25e047

We will grant three roles to the API key:

  • ds-connect: the ability to connect

  • ds-dynamic-peer: the ability to connect as a dynamic peer

  • ds-dynamic-fields: the ability to exchange field codes dynamically with the Liberator

Liberator configuration (for clarity, the SHA256 hash is not reproduced in full)
add-apikey f9912b266...ea25e047 "ds-connect,ds-dynamic-peer,ds-dynamic-fields"
Peer configuration
# Connection details to the Liberator
add-peer
    ...
    apikey "9702ff749fc8bc340053059b1029b491"
end-peer