Adding a new authentication method
1) Go to the Vault (in incognito mode) and login with the root token.

2) Go to Access → Auth Methods → Enable new method → Username & Password

Adding a new Secret Engine

1) Go to the Vault (in incognito mode) and login with the root token.

2) Go to Secrets → Enable new engine → KV

Creating a new User (assumes a Username/Password authentication method is already added to the vault)

Creating a new User can be done in two ways

Method 1 → API call(recommended):
This is simple and straightforward . Copy and run this curl command (You should replace the vaultEndpoint, xVaultToken , userName , passWord and mountPoint )

curl --location '{vaultEndpoint}/v1/auth/{mountPoint}/users/{userName}' \
--header 'X-Vault-Token: {xVaultToken}' \
--header 'Content-Type: application/json' \
--data '{
  "password": "{passWord}""
}'

For Eg:

curl --location 'http://red-osprey-9.phosphorus.io:8200/v1/auth/userpass/users/user3' \
--header 'X-Vault-Token: s.Yr5jEDojF0z9aIaWgRxGMX5j' \
--header 'Content-Type: application/json' \
--data '{
  "password": "superSecretPassword"
}'

Method 2 → UI + CLI

1) Go to the Vault (in incognito mode) and login with the root token.

2) Go to Access → Entities → Create entity → Enter Name and click Create

3) Install Vault CLI

brew tap hashicorp/tap
brew install hashicorp/tap/vault 

For Further info => Install | Vault | HashiCorp Developer

4) Open terminal and set the vaultEndpoint(VAULT_ADDR), vaultToken(VAULT_TOKEN), mountPoint (user pass is the mountPoint in the example below)

export VAULT_ADDR="http://red-osprey-9.phosphorus.io:8200"
export VAULT_TOKEN="s.Yr5jEDojF0z9aIaWgRxGMX5j"
vault write auth/userpass/users/user3 password="superSecretPassword" 

5) You should see the response being printed in the terminal => Success! Data written to: auth/userpass/users/user3

Adding a new ACL Policy

1) Go to the Vault (in incognito mode) and login with the root token.

2) Go to Policies → Create an ACL Policy

path "user3engine/*" {
  capabilities = ["create", "read", "update", "delete", "list", "sudo"]
} path "sys/health" { capabilities = ["read"] } path "sys/auth" { capabilities = ["read", "list"] }

3) Where user3engine is the name of the secret engine

Attaching a ACL Policy to a user
1) Go to the Vault (in incognito mode) and login with the root token.
2) Go to Access → Entities → Select the entity → Edit entity → Select the policies you want to attach → Save

Listing all Users

curl \
    --header "X-Vault-Token: s.Yr5jEDojF0z9aIaWgRxGMX5j" \
    --request LIST \
    http://red-osprey-9.phosphorus.io:8200/v1/auth/userpass/users

This only lists the users under userpass mountpoint, you can change the mountpoint to list the users under the specific mountpoint.

Hashicorp Vault QA Document

Positive Testing:

1. Able to create non-local vault integrations –

2. Able to use Token as the authentication method –

3. Able to use Username/Password as the authentication method –

4. Able to specify mountPoint other than userpass for Username/Password authentication method –

Negative Testing:

1. Specify an invalid Token and make sure error pops up and not being able to create the integration –

2. Specify invalid Username/Password and make sure error pops up and not being able to create the integration –

3. Specify invalid mountPoint and make sure error pops up and not being able to create the integration –

4. Create multiple vault integrations. Bring down the instance and bring it back up. Make sure that the vault are still functional. –

5. Specify an expired Token and make sure error pops up and not being able to create the integration –

Features Testing

1. Create a vault integration and scan few devices with that integration => initialize() and createCredential() –

2. On the Credential Providers Page make sure it displays the correct number of credentials present in that secretEngine => listCredentials() –

3. Go to a device and click on Show Device Password and make sure the device’s password match with what is present in the vault => getCredential() –

4. Rotate a device’s password and make sure the updated password is present in the vault => setCredential() -

Bulk Workers Testing

1. Select 4-5 devices and rotate the credentials for those devices and make sure the updated password matches with the vault. –

Auto Renewal Testing (check for multiple vault integrations as well): –

1. Create a token with a TTL of 15m.

2. Make an API call tokenLookupSelf and note down the TTL (dateTime format). Let’s call this T1.

3. Create an integration with Token as the authentication method and specify the created token.

4. Make sure the Auto Renew check box is selected

5. After 10 mins make the same API call as in step 2 and verify that the TTL would have been by 15m. (The reason for 10 mins is that there is an autoTimer in the code that makes the renewToken API call at 7.5mins (T1/2))

   Check for Auto Renew unabled as well.

Retry Logic Testing:

1. Token auth method =>
   a) Create a vault token integration with a token which is about to expire in a few mins (uncheck Auto Renew)
   b) Wait for the token to expire
   c) Now make a vault action like creating a credential.
   You should not be able to create the credential and get the error Unable to complete action, check if Token has expired in the BE logs-

2. Userpass auth method => Retry Logic for userpass is quite tricky and needs local setup –

a)Follow the steps in Hashicorp Vault. Create users to create an authMethod whose token expires in 5 mins.

c) Create a vault userpass integration. Uncheck the auto Renew check box (through the UI).

d) If you do a vault action like creating a credential, it should succeed since the vaultWrapper will call userpassLogin and get a new token

Backward Compatibility Testing –

1. Deploy Master to a RO

2. Create a non-local Vault integration

3. Deploy the branch (feat-PHO-1356-additional-auth-methods) to the same RO

4. Make sure the existing vault integration does not break and also we are able to create new vault integrations

Delete Provider (stop auto renew) Testing –

1. Create a vault integration and set autoRenew to true

2. now before the renewLeaseFunc runs, we delete that integartion

3. Now when the renewLeaseFunc runs , it would not renew the token.

Does not break CyberArk Testing –

1. Create two CA integrations (CA-core, CA-bidirect).

2. Enroll devices in both the CA integrations.

3. Deploy the vault-branch to the RO

4. Verify that existing CA integrations did not break.

5. Verify that we are able to create new vault integrations.

6. Verify that we are able to enroll devices in CA and vault integrations.

7. Create a new CA integration and enroll a device with that integration.

Hashicorp Vault Setup Documentation

Overview

This document describes how to configure your Hashicorp Vault to integrate with the Phosphorus Enterprise application. After you complete this setup, Phosphorus will be able to make use of the vault to access and store device secrets.

This setup includes steps to:

1. Access your Hashicorp Vault

2. Configure a Secrets Engine

3. Configure an ACL Policy

4. Configure an Authentication Method

At the end of this configuration, you must provide the following information about your Hashicorp Vault configuration to Phosphorus:

• Authentication method configured and the specific fields required for that authentication method

• Vault URL

• Secrets Engine Path

• Namespace (if using HCP or Vault Enterprise)

Before you begin

Before you configure the Hashicorp Vault integration, you must have:

• Administrator/root permissions to access and configure the Hashicorp Vault instance you wish to configure within the Phosphorus Enterprise application

Access Your Hashicorp Vault

Access an existing Hashicorp Local Vault

1. Access your instance at https://{instance_name}:8200 and log in with a user that has root privileges.

2. Make note of the above full URL, as this will need to be submitted to Phosphorus to properly integrate with your local Vault.

Configure and access a new HCP Vault

1. Login to the Hashicorp Cloud Platform: HashiCorp Cloud Platform

2. Under the Services section in the navigation bar, click on Vault

3. Under the Start from scratch heading, click Create cluster

4. Configure the cluster as it suits your production environment. Under the Templates setting, make sure to choose the Start from scratch option. Click complete and wait for the cluster to be initialized.

5. Once initialized, in the Quick actions heading and under the New admin token box, click Generate token to generate the admin token that we will use for configuring the HCP Vault cluster. The token will be copied to your clipboard, so make sure to store it somewhere for reference.

6. Next, under the Cluster URLs, click on Public to copy the public link for your HCP Vault. Make note of this value, as you will need to provide it as part of the configuration for Vault URL.

7. Open a new tab in your browser and access the public URL that is copied in your clipboard. This should bring you to a login page for your HCP Vault.

8. Select Token as the method and paste the value of the admin token that was generated above.

9. You have now accessed your HCP Vault!

Configure Secret Engine

Phosphorus supports integrating with Vault using a KV (key:value) secrets engine.

1. Within your Hashicorp Vault instance, click on Secret engines in the navigation bar

2. Click on Enable new engine

3. Under the Generic section, select KV and click Next

4. Give the secret engine a name in the Path form. Make note of this name as we will require it for further configuration. For the purpose of this guide, we will name our secret engine user2engine

5. Once done, click Enable Engine to create your secrets engine

Configure ACL Policy

We now need to configure an ACL Policy within your Vault instance in order to provide the policy needed for your secrets engine to access the necessary secrets.

1. Within your Hashicorp Vault instance, click on Policies is the navigation bar and click Create ACL policy

2. Provide a name for the ACL Policy. For the sake of this guide, we will name it user2engine policy

3. Paste the following policy into the text box:

   path "{{name of secret engine created}}/*" {
     capabilities = ["create", "read", "update", "delete", "list", "sudo"]
   }
   
   path "sys/health"
   {
     capabilities = ["read"]
   }
   
   path "sys/auth"
   {
     capabilities = ["read", "list"]
   }

NOTE: It is mandatory for you to replace {{name of secret engine created}} with the name of the secret engine you created above. In our example, this is named user2engine.

4. Click Create Policy

Configure Authentication Method

Phosphorus supports integration with Vault via three authentication methods:

• Username/password

• Token

• AppRole

Please follow the steps for configuring one of these authentication methods.

Username/Password Authentication

1. Within your Hashicorp Vault instance, click on Access in the navigation bar

2. Click on Auth Methods, and then Enable new method

3. Under the Generic heading, select Username & Password and click Next

4. Give this authentication method a name. Make note of this name as we will require it for further configuration. For the purpose of this guide, we will name our user/pass authentication method: userpass

5. Expand the Method Options section

6. Set the Default Lease TTL to 60 days and the Max Lease TTL to 600 days

7. Click Enable Method

8. Next, go back to Access > Auth Methods within your Vault instance, and click on the User&Pass method you just created, and click on Create user.

9. Specify a username and password for this user. Make sure you note down these values, as they will be required to complete configuration.

10. Expand the Tokens section, and under the Generated Token’s Policies, add two rows:

    1. One with a value of default

    2. One with a value of the ACL policy name configured above. For our example, we use user2engine policy.

11. Click Save to finish creating the user

AppRole Authentication

1. Within your Hashicorp Vault instance, click on Access in the navigation bar

2. Click on Auth Methods, and then Enable new method

3. Under the Generic heading, select AppRole and click Next

4. Give this authentication method a name. Make note of this name as we will require it for further configuration. For the purpose of this guide, we will name our AppRole authentication method: approle

5. Next, we need to create and retrieve the RoleId and SecretId for this AppRole authentication method. This information NEEDS to be retrieved via the Vault API as the Vault UI does not currently support this. This configuration guide will provide the cURL commands that can be run via a terminal, but these requests can be made by any tool that allows you to reach the Vault API (ie, PostMan)

Note: The following values need to be substituted in the API calls:

• {{vaultUrl}} – the URL to your Vault instance with port. Example: https://vault-cluster-public-vault-83aa8692.c6220029.z1.hashicorp.cloud:8200

• {{appName}} – the name of the AppRole you want to configure. The recommended value is: phosphorusVault

• {{adminToken}} – the admin token generated/retrieve in the Access Your Hashicorp Vault step

• {{aclPolicy}} – the name of the ACL Policy configured in the Configure ACL Policy step above. In this document, we used user2engine policy as our example value.

• {{namespace}} – the namespace to use for your HCP/Vault Enterprise environment. By default, this should just be admin