Oracle Health Insurance Agent - Secrets Store Prerequisites

Oracle Health Insurance Agent requires the use of a secret store that holds username & password credentials. These credentials are needed for accessing the Oracle Insurance Gateway for example.

The following secret store types are supported:

  • Java KeyStore: relatively easy to configure and maintain without the need to install additional software.

  • HashiCorp Vault: especially fitting for an organization that already makes use of HashiCorp Vault as a secrets store.

The remainder of this chapter lists requirements and suggestions for installing and using these secret stores for use with Oracle Health Insurance Agent. Note that these secret stores are mutually exclusive: Oracle Health Insurance Agent can be configured to use one and only one.

Java KeyStore

This section explains how to construct a Java KeyStore file that holds the username & password credential that Oracle Health Insurance Agent uses for accessing Oracle Insurance Gateway. Depending on its configuration, Oracle Health Insurance Agent will either use the username & password credential to connect to the Oracle Insurance Gateway using Basic Authentication or it will trade the credential for an OAuth2 access token that it uses to connect to Oracle Insurance Gateway.

KeyStore Requirements

The KeyStore file must meet the following requirements:

  • KeyStore file type: PKCS12.

  • The username must be of entry type SecretKeyEntry with as alias name the credential key followed by suffix "_username".

  • The password must be of entry type SecretKeyEntry with as alias name the credential key followed by suffix "_password".

  • The KeyStore and any entry must be secured with a single password that can be used to access the KeyStore as well as all entries.

To connect to Oracle Insurance Gateway, Oracle Health Insurance Agent requires a credential with credential key "ohi_gateway", thus the alias name for the SecretKeyEntry for the username must be "ohi_gateway_username" and the corresponding alias name for the SecretKeyEntry for the password must be "ohi_gateway_password".

Creating the KeyStore Using the Java Keytool Command Line Interface

Create the KeyStore file using the Java keytool command line utility. The following shell script lists the keytool commands to create the required KeyStore file. It implements the requirements and naming conventions mentioned in the previous paragraph:

#!/usr/bin/env bash

if [[ $# != 1 ]]; then
    echo "Please specify the keystore file name."
    exit -1
fi

KEY_STORE="$1"

printf "Keystore Password":
read -s PASS_KEYSTORE

printf "\n"
echo -n "Secret[OHI Gateway Username]":
read -s USERNAME

printf "\n"
echo -n "Secret[OHI Gateway Password]":
read -s PASSWORD

printf "\n--------\n"

rm -f ${KEY_STORE}
echo "Creating: ${KEY_STORE}"

printf "${USERNAME}" | keytool -storetype PKCS12 -keystore ${KEY_STORE} \
    -storepass ${PASS_KEYSTORE} \
    -importpass \
    -alias ohi_gateway_username

printf "${PASSWORD}" | keytool -storetype PKCS12 -keystore ${KEY_STORE} \
    -storepass ${PASS_KEYSTORE} \
    -importpass \
    -alias ohi_gateway_password

Remember the KeyStore password that is used at it is needed by Oracle Health Insurance Agent in order to read the KeyStore entries.

Assuming that the KeyStore file is named 'keystore.p12', the following keytool command lists the entries in the KeyStore file (note that this will prompt for the password):

keytool -list -v -keystore keystore.p12

The output should look like the following:

Enter keystore password:
Keystore type: PKCS12
Keystore provider: SUN

The keystore contains 2 entries

Alias name: ohi_gateway_username
Creation date: Aug 25, 2020
Entry type: SecretKeyEntry

*******************************************
*******************************************

Alias name: ohi_gateway_password
Creation date: Aug 25, 2020
Entry type: SecretKeyEntry

*******************************************
*******************************************

Configure Oracle Health Insurance Agent to Use the KeyStore

Specify the URL to the KeyStore file as value for property 'agent.keystore.url'. Refer to Property Management for more information on setting a property.

The password for accessing the KeyStore should be specified as value for property 'agent.keystore.password'. For security reasons this may be listed as environment variable before starting Oracle Health Insurance Agent.

HashiCorp Vault

Note that this is not an Installation Guide for Vault, nor a replacement of the Vault documentation. The remainder of this chapter assumes sufficient knowledge of Vault concepts.

Required: Managing Secrets in Vault

Oracle Health Insurance Agent only accesses the Vault to retrieve secrets, it cannot add new secrets or modify existing ones. Entering and managing secrets must be done by using an external tool, like the Vault Command-Line Interface (CLI) or the Vault HTTP API.

It is required to register a credential that Oracle Health Insurance Agent needs to connect to the Oracle Insurance Gateway. Assuming that the default value "secret" is used for system property "vault.kv.secrets.engine" and the default value "ohi" is used for the system property "vault.ohi.namespace" (elsewhere in this guide it is documented how these values can be changed if desired) then the following Vault CLI command registers that credential:

vault kv put secret/ohi/credential/ohi_gateway/ohi_gateway username=a_username password=secret

If Oracle Health Insurance Agent is configured to connect to the Oracle Insurance Gateway using OAuth2, the credential registered in Vault at "secret/ohi/credential/ohi_gateway/ohi_gateway" will be used to obtain an OAuth2 bearer token. If Oracle Health Insurance Agent is configured to connect to the Oracle Health Insurance Integration Gateway using Basic Authentication then the credential will be used in the Authorization HTTP header.

Required: Enable Vault’s KV Secrets Engine Version 2

Oracle Health Insurance Agent assumes the use of Vault’s KV secrets engine V2. By default, Oracle Health Insurance Agent assumes that the KV secrets engine is available at path "secret". Enable the KV secrets engine and make it available at path "secret" with the following Vault CLI command:

vault secrets enable -version=2 -path=secret kv

If the KV secrets engine is made available using a different path, change Oracle Health Insurance Agent configuration to point to that path by setting the value of system property "vault.kv.secrets.engine" accordingly.

Required: Define Namespaces for Secrets in Vault

Vault stores secrets in namespaces. For accessing secrets, Oracle Health Insurance Agent builds up a namespace using the following attributes:

  • By default, Oracle Health Insurance applications assume that Vault’s Key-Value secrets engine is enabled at root path "secret".

  • Under this root path, Oracle Health Insurance specific namespace section is added. The name is configurable, default value "ohi". Creating Oracle Health Insurance specific section allows a central Vault to be used for other use cases as well.

  • A use case specific entry is added to the namespace: "credential" for credentials and "keystore" for keystores that contain key-value pairs.

  • The name of a configured integration is subsequently added to the path. This is typically a lowercase, unique identifier, for example, "claimsgateway" or "providerimport". It is defined in Oracle Insurance Gateway at the time of configuration.

  • Finally, a use case specific key is added under which a specific credential or key pair is stored. The value of the key is defined in Oracle Insurance Gateway at the time of configuration.

For example, for a "claimsgateway" integration, a credential with key "customer_key" would be stored as follows (specified in Vault CLI syntax):

vault kv put secret/ohi/credential/claimsgateway/customer_key username=a_username password=a_secret_password

Oracle Health Insurance Agent requires the username and password portions of a credential to be named "username" and "password" respectively.

In order for Oracle Health Insurance Agent to connect to Vault, the Vault’s address and a valid access token need to be passed at startup. The following paragraphs list requirements with respect to the address and the token.

Required: Set Up a Vault Policy and Token for Oracle Health Insurance Agent

Initialization is the process by which Vault’s storage backend is prepared to receive data. During initialization, an "Initial Root Token" is generated.

The root token should not be passed to Oracle Health Insurance Agent

Instead, it is recommended to create Oracle Health Insurance Agent specific policy to grant the correct capabilities for a namespace and a matching token for that.

For example, the following Vault policy could be created (in a file named "ohi-integration-agent-policy.hcl"):

path "secret/ohi/credential*" {
  capabilities = ["read", "list"]
}

In Vault CLI syntax, the policy would be added to Vault as follows:

vault policy write ohi-integration-agent-policy /vault/config/ohi-integration-agent-policy.hcl

Subsequently, a token can be created that is attached to the policy. In Vault CLI syntax:

vault token create -display-name=ohi-integration-agent-token -policy=ohi-integration-agent-policy

Optional: Set Up High Availability for Vault

According to its documentation, "Vault supports a multi-server mode for high availability". A prerequisite for operating Vault in high availability mode is the use of a suitable storage backend that supports it. At the moment of writing this guide, the Vault documentation states:

"Currently, there are several storage backends that support high availability mode, including Consul, ZooKeeper and etcd. These may change over time, and the configuration page should be referenced. The Consul backend is the recommended HA [high availability] backend".