Key Vault

Overview

User credentials must be configured in the secrets engine manually by the client gateway admin during the initial gateway deployment. Most secrets engines provide a user interface to manage such values.

The client gateway has no UI to enable user registration or password recovery/reset. These must be done through the secrets engine manually by person/team deploying the client gateway.

Each user represents a secret record in the selected secret engine.

Supported Secrets Engine

1. HashiCorp Key Vault

2. Azure Key Vault

3. AWS Secrets Manager

Secret Record Field

Field Name	Description	Remarks
username	identifies the user with access to the system
password	a secret used to verify the user’s identity
role	defines the user’s level of access in the system	Possible Values: admin messaging

Secret engine accessibility check

In most cases, your secret engine will be on a private network. Please be sure that the client gateway can access the secret engine if they are not in the same network.

User Guide

Pre-requisites

• Access credentials to the selected secret engines

Get Azure Key Vault access credentials

• You should have a Key Vault resource created. You may follow https://docs.microsoft.com/en-us/azure/key-vault/general/quick-create-portal

• You need a Service Principle which has Read&Write access to the Key Vault resource.

  • To create a service principle and retrieve the access credentials, please follow this guide (make sure to follow Password-based authentication): https://docs.microsoft.com/en-us/cli/azure/create-an-azure-service-principal-azure-cli?view=azure-cli-latest#password-based-authentication

• After the service principle is created, follow this guide to create an access policy for the service principle (recommend to use 'Secret Management' template as shown on the official guide): https://docs.microsoft.com/en-us/azure/key-vault/general/assign-access-policy?tabs=azure-portal#assign-an-access-policy

Your output may look like below. All you need for DDHub Client GW are:

• clientId

• clientSecret

• tenantId

• Vault URI(on your Key Vaults resource overview page)

{
  "clientId": "dcb*****-5**d-455b-93df-27*******a",
  "clientSecret": "ABy******************UBT",
  "subscriptionId": "3e0778884f-****-3433-5555-4d770DFGSFGDf",
  "tenantId": "778884f-fd1f-****-5e33-4a945d770D56",
  "activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
  "resourceManagerEndpointUrl": "https://management.azure.com/",
  "activeDirectoryGraphResourceId": "https://graph.windows.net/",
  "sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
  "galleryEndpointUrl": "https://gallery.azure.com/",
  "managementEndpointUrl": "https://management.core.windows.net/"
}

Get AWS Secrets Manager access credentials

You'll need the access keys for IAM user / root user, which has privilege to Read&Write into the Secrets Manager in the chosen region.

Please follow this guide if you are not familiar with AWS access keys: https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html

All you need for DDHub Client GW are:

• Access Key ID

• SECRET ACCESS KEY

• Region for the secrets manager

Get HashiCorp Key Vault access token

Please check below scenarios and choose the one suits your use case:

Scenario-1: Existing Hashicorp vault service

1. token for accessing the existing vault service. Please contact your vault admin for access token.

2. vault service address of the existing vault service

3. Complete `ddhub` secret engine creation. You can follow How to create ddhub secret engine step below to do that.

Scenario-2: Deploy new HashiCorp vault service and obtain token - run a single container

Please follow below steps to run HashiCorp vault service in a docker container.

In a terminal:

1. Clone git repository ddhub-client-gateway

   git clone https://github.com/energywebfoundation/ddhub-client-gateway.git

2. Change directory to example directory

   cd ddhub-client-gateway && cd get-started

3. Start the vault service

   docker compose up vault_demo

4. You should have the vault service and UI available at port 8200.

5. On a web browser, enter http://127.0.0.1:8200/ui in the address bar. Follow https://learn.hashicorp.com/tutorials/vault/getting-started-ui?in=vault/getting-started#start-web-ui starting from step 5. Then, you should have the root_token. The vault server address is http://localhost:8200

6. Complete `ddhub` secret engine creation. You can follow How to create ddhub secret engine step below to do that.

Scenario-3: Deploy new HashiCorp vault service and obtain token - Kubernetes

Please follow the steps below:

1. Follow this guide to deploy a HashiCorp vault service in kubernetes.

2. Once your vault service is up and running, on a web browser, enter http(s)://YOUR_VAULT_ADDRESS/ui in the address bar. Follow https://learn.hashicorp.com/tutorials/vault/getting-started-ui?in=vault/getting-started#start-web-ui starting from step 5. Then, you should have the root_token. The vault server address is http://YOUR_VAULT_ADDRESS

3. Complete `ddhub` secret engine creation. You can follow How to create ddhub secret engine step below to do that.