Zoho Vault: A Comprehensive Step-by-Step Integration Guide

In today’s world, securing sensitive information like passwords and credentials is crucial. Zoho Vault offers a robust solution for storing and managing secrets securely. In this blog, we’ll walk you through how to integrate Zoho Vault, enabling secure storage and retrieval of credentials.

Why Zoho Vault?

Zoho Vault is a cloud-based password management solution that helps securely store and share passwords and other sensitive data. It offers features like encryption, secure sharing, and access control, making it an ideal choice for teams and businesses.

Step 1: Set Up Zoho Vault API Access

To interact with Zoho Vault, you need to configure API access. Follow these steps to get your API credentials:

1. Create a Zoho Account: If you don’t already have a Zoho account, create one at Zoho Vault.
2. Access the Zoho API Console: Head over to the Zoho Developer Console and create a new client.
3. Generate Client ID and Client Secret: In the API console, create a Self Client application type. This will provide you with the necessary Client ID and Client Secret, which are essential for authenticating your API requests.
4. Set the Required API Scopes: Scopes define the permissions your API requests will have. For Zoho Vault, you’ll need the following scopes to access and manage secrets:

   ZohoVault.secrets.CREATE, ZohoVault.secrets.UPDATE, ZohoVault.secrets.READ, ZohoVault.secrets.DELETE

   Scopes are essentially permission sets that allow your API to perform specific actions on Zoho Vault. Once you’ve selected the scopes, generate them in the console.

5. Generate API Tokens: With the Client ID, Client Secret, and the selected scopes, you can now generate an OAuth code. Use this code, along with your Client ID and Client Secret, to obtain the API tokens (both access and refresh tokens). These tokens will authenticate and authorize your API requests to Zoho Vault.

Step 2: Obtain and Refresh Zoho Vault API Tokens

To securely access Zoho Vault from your Java application, you need an access token for authenticating your API requests. The access token, however, is valid only for a short period (usually 1 hour). To avoid re-authenticating every time, you will also get a refresh token, which allows you to request new access tokens as needed.

Here’s a detailed explanation of how to obtain the refresh token:

➡️ Exchange Authorization Code for Access and Refresh Tokens

After you’ve obtained the authorization code (as explained in the previous step), you can exchange it for both an access token and a refresh token by making a POST request to Zoho’s token endpoint.

Request URL:

https://accounts.zoho.in/oauth/v2/token  //.in is only for India location

Request Parameters:

You will need to pass the following parameters to the token endpoint:

code=<your authorization code>
client_id=<your client ID>
client_secret=<your client secret>
grant_type=authorization_code
redirect_uri=<your redirect URI>

• code: This is the authorization code you received in the first step.
• client_id: Your Client ID from the Zoho Developer Console.
• client_secret: Your Client Secret from the Zoho Developer Console.
• grant_type: Use authorization_code as the value for this parameter.
• redirect_uri: The redirect URI you specified when creating the client.

Example Request (using curl):

• Replace YOUR_AUTHORIZATION_CODE, YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, and YOUR_REDIRECT_URI with the actual values from your Zoho API setup.

Response Example:

{
"access_token": "1000.xxxx",
"refresh_token": "1000.yyyy",
"expires_in": 3600,
"token_type": "Bearer"
}

• The access_token is used to authenticate API calls.
• The refresh_token can be used to request a new access token when the current one expires.
• expires_in: Time (in seconds) for which the access token is valid (usually 1 hour).

➡️ Use the Refresh Token to Get a New Access Token

Once the access token expires, use the refresh token to obtain a new one without needing to repeat the authentication process.:

Request URL:

https://accounts.zoho.in/oauth/v2/token

Request Parameters:

client_id=<your client ID>
client_secret=<your client secret>
refresh_token=<your refresh token>
grant_type=refresh_token

• client_id: Your Client ID.
• client_secret: Your Client Secret.
• refresh_token: The refresh token you received in the previous response.
• grant_type: Use refresh_token as the value for this parameter.

Example Request (using curl):

Response Example:

{
"access_token": "1000.newaccessxxxx",
"expires_in": 3600,
"token_type": "Bearer"
}

Step 3: Retrieve Policy ID and Secret Type ID for API Calls

Now that you have your access token, you’re ready to make authenticated API calls to Zoho Vault. However, to store credentials in Zoho Vault, you will also need two crucial pieces of information:

• Policy ID: Represents the password policy you want to apply to the secret (credential).
• Secret Type ID: Represents the type of secret (credential) you are storing, such as a password, document, or other sensitive data.

Here’s how you can retrieve these values using Zoho Vault APIs:

1. Retrieve Policy ID

To fetch the Policy ID (password policy), make an API call to the Zoho Vault endpoint that provides available password policies. You’ll need to pass the access token in the header for authentication.

Request URL:

https://vault.zoho.in/api/json/secrets?OPERATION_NAME=GET_PASSWORD_POLICIES

Headers:

Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN

The POLICY_ID is the unique identifier for the password policy, which you’ll need for storing credentials.

2. Retrieve Secret Type ID

Next, to retrieve the Secret Type ID (for example, whether you’re storing a password, key, or document), make an API call to the Zoho Vault endpoint that lists available secret types.

Request URL:

https://vault.zoho.in/api/rest/json/v1/secrettypes

Headers:

Authorization: Zoho-oauthtoken YOUR_ACCESS_TOKEN

From response, you will need to select the secret type ID from the Web Account Section.

You’ll need to store the following in your code, as they will be used in every Zoho API call: your Client ID, Client Secret, Policy ID, Secret Type ID, and Refresh Token. These values will be required for authentication and authorization when interacting with Zoho Vault.

Understanding Secrets and Chambers in Zoho Vault

When integrating Zoho Vault with Java, it’s essential to understand two key concepts: **Secrets** and **Chambers**. These terms refer to how sensitive information is stored and organized within Zoho Vault.

What is a Secret?

A Secret in Zoho Vault refers to any sensitive information that you want to securely store, manage, and share. This could be login credentials (usernames and passwords), API keys, credit card information, or any other confidential data.

Each Secret is encrypted and protected using strong encryption methods, ensuring that only authorized users can access or decrypt it. In Zoho Vault, a Secret can be categorized into different secret types, such as:

• Passwords: Used for storing login details for applications or websites.
• API Keys: Used for storing sensitive keys for various services.
• Documents: Used for storing confidential files or documents.

Every Secret includes metadata such as:

• Secret Name: A descriptive name for the secret.
  
• Secret Data: The sensitive information itself, such as the username and password.
  
• URL: The associated website or service URL, if applicable.

What is a Chamber?

A Chamber in Zoho Vault is like a secure folder or vault where you can store and organize multiple secrets. Chambers help categorize secrets based on departments, teams, or projects, making it easier to manage large amounts of sensitive data.

Think of a Chamber as a logical grouping that allows you to:

• Organize Secrets: Group secrets for specific purposes, like “Credentials” or “Project X API Keys.”
• Control Access: Define which users or teams can access the secrets stored within a particular chamber. You can assign different access levels (read, write, share, etc.) to users or groups.
• Enhance Security: Chambers add an extra layer of organization and security, allowing fine-grained control over who has access to what.

Summary:

• Secrets are individual pieces of sensitive data (passwords, keys, etc.) stored securely in Zoho Vault.
  
• Chambers are like folders that help organize and manage secrets, with access controls to define who can view, edit, or share the contents.

By organizing your secrets into Chambers, you can maintain security, ensure proper access controls, and simplify the management of sensitive information within Zoho Vault.

Storing secret

POST https://vault.zoho.in/api/rest/json/v1/secrets

Request Format:

You need to select x-www-form-urlencoded as the request type. The body of your request will contain a single key-value pair:

• Key: INPUT_DATA.
• Value: A JSON string containing the details of the secret you want to store.

Example:

GET SECRETE BY ID

CREATE CHAMBER

Note:

When you manually add credentials using the Zoho Vault UI, you can see the data in plain text. This is because Zoho Vault handles the encryption and decryption automatically when you use the web interface. However, when you’re interacting with Zoho Vault via the API, things work a bit differently due to the Host-proof Hosting (HPH) model, which is why you’re seeing encrypted data.

Here’s the Distinction:

1. Using Zoho Vault UI (Manual Entry):

When you add credentials (like username and password) manually through the Zoho Vault UI, Zoho handles the encryption and decryption seamlessly. The data is shown to you in plain text because the encryption happens in the background, and the UI decrypts the data for display.

2. Using Zoho Vault API (Programmatic Entry):

When you use the API to save credentials, Zoho expects you to encrypt the data before sending it to their servers. Since Zoho Vault does not perform encryption or decryption when using the API, it will only store and show the encrypted data on the UI.

The reason Zoho Vault displays the data in encrypted form in the UI is that it doesn’t have the decryption key to display the data in plain text.