Introduction

After APIGW Authentication is complete, the HTTPS should be securely configured on the APIGW and able to be authenticated against. The next step is to register an engine with the gateway so that the gateway can fetch results. The APIGW connects to all engines over HTTPS, thus some configurations might be required to ensure it can communicate successfully.

Truststore for HTTPS

If the CA certificate that signed the engine's HTTPS certificate is not a trusted root CA certificate present in the JDK, then a custom truststore containing the needed CA certificates can be provided to the API gateway. If this truststore is not provided, a secure HTTPS connection cannot be established and registering the engine will fail. The insecure_ssl engine registration parameter can be used to bypass the check, however, this should not be used unless the risks are understood.

Providing the custom truststore to the APIGW is a three step process. First, the truststore needs to be created and populated with the relevant CA certificates. We support both Java Keystore (JDK) and PKCS#12 file formats. It then needs to be placed on the host and bind mounted to a specific location inside the container. Finally, the truststore_filename and truststore_password must be specified when registering an engine.

Place the truststore on host machine

This will be done using a bind mount. The truststore file needs to be at /etc/config/certs inside the container and therefore should be placed inside the certs subdirectory in the configuration directory on the host machine.

Set parameters when registering engine

The relevant engine registration parameters are the truststore_filename and truststore_password. The truststore_filename is the name of the PKCS#12 file that contains the CA certificates needed to validate the engine's HTTPS certificate chain. Note that the certs.p12 file needs to be inside the certs subdirectory in the bind mount.

 curl --location --request POST 'https://<hostname>/v1/management/engines' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: apk <your API key>' \
--data-raw '{
    "name": "My Engine",
    "hostname": "engine.delphix.com",
    "username": "admin",
    "password": "<engine password>",
    "truststore_filename": "certs.p12",
    "truststore_password": "notPassword"
}'

Authentication with the engine

All authentication with the Delphix engine is done with the username and password of a domain admin engine user. There are two methods of storing these credentials with the APIGW. They can either be stored and encrypted on the APIGW itself or retrieved from a password vault. We recommend fetching the credentials from a vault. Currently only the HashiCorp vault is supported.

HashiCorp vault

There are two high-level steps to configuring a HashiCorp vault. The first is to set up authentication with the vault and register the vault. The second is to tell the APIGW how to get the specific engine credentials needed from that registered vault. A single vault can be used for multiple different Delphix engines.

Vault Authentication and Registration

First, the APIGW needs to be able to authenticate with the vault. The APIGW supports the Token, AppRole, and TLS Certificates auth methods. This is done by passing a command to the HashiCorp CLI. It is recommended to first ensure that successful authentication is done and one can retrieve the credentials with the HashiCorp CLI directly to ensure the correct commands are passed to the APIGW.

Adding a vault to the APIGW is done through API calls to the /v1/management/vaults/hashicorp endpoint. All authentication methods requires the location of the vault is provided through the env_variables property in the POST body like so:

"env_variables": {
       "VAULT_ADDR": "https://10.119.132.40:8200"
   }
Token

To use the token authentication method, this needs to be included as part of the env_variables field. The full example to register the vault would appear as:

curl --location --request POST 'https://<hostname>/v1/management/vaults/hashicorp' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: apk <your API key>' \
--data-raw '{
   "env_variables": {
       "VAULT_TOKEN": "<your token>"
       "VAULT_ADDR": "https://10.119.132.40:8200"
   }
}'


A response should be received similar to the lines below:

{
   "id": 2,
   "env_variables": {
       "VAULT_TOKEN": "<your token>"
       "VAULT_ADDR": "https://10.119.132.40:8200"
   }
}

Note the id of the vault, this will be needed in the next step to register the engine.

AppRole

To use the AppRole authentication method, this needs to be included as part the login_command_args field, as shown below.

"login_command_args":
       [ "write", "auth/approle/login", "role_id=1", "secret_id=123"]


The full example to register the vault would appear as:

curl --location --request POST 'https://<hostname>/v1/management/vaults/hashicorp' \
--header 'Content-Type: application/json' \
--header 'Accept: application/json' \
--header 'Authorization: apk <your API key>' \
--data-raw '{
   "env_variables": {
       "VAULT_ADDR": "https://10.119.132.40:8200"
   },
   "login_command_args":
       [ "write", "auth/approle/login", "role_id=1", "secret_id=123"]
}'


A response should be received similar to the lines below:

{
   "id": 2,
   "env_variables": {
       "VAULT_TOKEN": "<your token>"
       "VAULT_ADDR": "https://10.119.132.40:8200"
   }
}


TLS Certificates

The configuration of mutual TLS authentication requires an additional step. The private key and corresponding certificate must be placed inside the /etc/config bind mount.

[ "login", "-method=cert", "-client-cert=/etc/config/cert.pem", "-client-key=/etc/config/key.pem" ]

Retrieving engine credentials

Once the APIGW can authenticate with the vault, it needs to know how to fetch the relevant engine credentials. When registering an engine, the user will need to provide the HashiCorp CLI commands through the hashicorp_vault_username_command_args and hashicorp_vault_password_command_args parameters.

The relevant part of the engine registration payload will look like the following:

'{
    "hashicorp_vault_id": 1
    "hashicorp_vault_username_command_args": ["kv", "get", "-field=username",  "kv-v2/delphix-engine-secrets/engineUser"]
,
    "hashicorp_vault_password_command_args": ["kv", "get", "-field=password",  "kv-v2/delphix-engine-secrets/engineUser"]
}'


The hashicorp_vault_id will be the ID that was returned as part of the previous step. Note that the exact paths to fetch the username and password will vary depending on the exact configuration of the vault.