@eqxjs/azure-manage-identity

A TypeScript library for managing Azure Key Vault secrets and cryptographic operations using Azure Managed Identity.

Node: >=22

Description

This library provides a simple interface to interact with Azure Key Vault for secret management, JWT token verification/signing, and data encryption/decryption operations. It uses Azure's DefaultAzureCredential for seamless authentication with managed identities.

Installation

npm install @eqxjs/azure-manage-identity

Features

• Secret Management: Get, set, list, and remove Azure Key Vault secrets
• JWT Operations: Verify and sign JWT tokens using Azure Key Vault keys
• Data Encryption: Encrypt and decrypt data using Azure Key Vault keys
• Managed Identity: Automatic authentication using Azure Managed Identity

Functions

Secret Management

getSecret(keyvaultURL: string, secretName: string, secretOpt?: GetSecretOptions)

Retrieves a secret from Azure Key Vault.

Parameters:

• keyvaultURL - The URL of the Azure Key Vault (e.g., https://your-keyvault.vault.azure.net/)
• secretName - The name of the secret to retrieve
• secretOpt - Optional settings for getting the secret

Returns: Promise<KeyVaultSecret>

Example:

import { getSecret } from '@eqxjs/azure-manage-identity';

const secret = await getSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);
console.log(secret.value);

setSecret(keyvaultURL: string, secretName: string, secretValue: string, secretOpt?: SetSecretOptions)

Creates or updates a secret in Azure Key Vault.

Parameters:

• keyvaultURL - The URL of the Azure Key Vault
• secretName - The name of the secret to set
• secretValue - The value to store in the secret
• secretOpt - Optional settings for setting the secret

Returns: Promise<KeyVaultSecret>

Example:

import { setSecret } from '@eqxjs/azure-manage-identity';

const secret = await setSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
  'my-secret-value',
);

listSecretVersion(keyvaultURL: string, secretName: string, secretOpt?: ListPropertiesOfSecretVersionsOptions)

Lists all versions of a specific secret.

Parameters:

• keyvaultURL - The URL of the Azure Key Vault
• secretName - The name of the secret
• secretOpt - Optional settings for listing secret versions

Returns: PagedAsyncIterableIterator<SecretProperties>

Example:

import { listSecretVersion } from '@eqxjs/azure-manage-identity';

const versions = await listSecretVersion(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);

for await (const version of versions) {
  console.log(version.version);
}

removeSecret(keyvaultURL: string, secretName: string, secretOpt?: BeginDeleteSecretOptions, clientOptions?: SecretClientOptions)

Removes a secret from Azure Key Vault and waits until the deletion is complete.

Parameters:

• keyvaultURL - The URL of the Azure Key Vault
• secretName - The name of the secret to remove
• secretOpt - Optional settings for the delete operation
• clientOptions - Optional configuration for the Secret client

Returns: Promise<DeletedSecret>

Example:

import { removeSecret } from '@eqxjs/azure-manage-identity';

const deleted = await removeSecret(
  'https://your-keyvault.vault.azure.net/',
  'my-secret',
);
console.log(deleted.deletedOn);

JWT Token Operations

verifyJWTToken(keyURL: string, keyName: string, algorithm: string, jwtToken: string)

Verifies a JWT token using an Azure Key Vault cryptographic key.

Parameters:

• keyURL - The URL of the Azure Key Vault
• keyName - The name of the key to use for verification
• algorithm - The signing algorithm (e.g., 'RS256')
• jwtToken - The JWT token to verify

Returns: Promise<VerifyResult>

Example:

import { verifyJWTToken } from '@eqxjs/azure-manage-identity';

const result = await verifyJWTToken(
  'https://your-keyvault.vault.azure.net/',
  'my-key',
  'RS256',
  'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
);
console.log(result.result); // true or false

verifyJWTTokenBySecret(keyURL: string, secretName: string, jwtToken: string)

Verifies a JWT token using a public key stored as a secret in Azure Key Vault. Supports JWKS (JSON Web Key Set) format.

Parameters:

• keyURL - The URL of the Azure Key Vault
• secretName - The name of the secret containing the public key/JWKS
• jwtToken - The JWT token to verify

Returns: Promise<VerifyResult>

Example:

import { verifyJWTTokenBySecret } from '@eqxjs/azure-manage-identity';

const result = await verifyJWTTokenBySecret(
  'https://your-keyvault.vault.azure.net/',
  'jwks-secret',
  'eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...',
);

signJWTToken(keyURL: string, keyName: string, algorithm: string, payload: string)

Signs a JWT payload using an Azure Key Vault cryptographic key.

Parameters:

• keyURL - The URL of the Azure Key Vault
• keyName - The name of the key to use for signing
• algorithm - The signing algorithm (e.g., 'RS256')
• payload - The payload to sign

Returns: Promise<string> - Base64URL-encoded signature

Example:

import { signJWTToken } from '@eqxjs/azure-manage-identity';

const signature = await signJWTToken(
  'https://your-keyvault.vault.azure.net/',
  'my-key',
  'RS256',
  'header.payload',
);

Data Encryption/Decryption

encryptData(keyURL: string, keyName: string, payload: string, ivSecretName: string)

Encrypts data using AES-256-CBC encryption with an Azure Key Vault key.

Parameters:

• keyURL - The URL of the Azure Key Vault
• keyName - The name of the key to use for encryption
• payload - The data to encrypt
• ivSecretName - The name of the secret containing the initialization vector (IV)

Returns: Promise<string> - Base64URL-encoded encrypted data

Example:

import { encryptData } from '@eqxjs/azure-manage-identity';

const encrypted = await encryptData(
  'https://your-keyvault.vault.azure.net/',
  'encryption-key',
  'sensitive data',
  'iv-secret',
);

decryptData(keyURL: string, keyName: string, payloadBase64: string, ivSecretName: string)

Decrypts data that was encrypted using AES-256-CBC encryption.

Parameters:

• keyURL - The URL of the Azure Key Vault
• keyName - The name of the key to use for decryption
• payloadBase64 - The Base64URL-encoded encrypted data
• ivSecretName - The name of the secret containing the initialization vector (IV)

Returns: Promise<string> - Decrypted plaintext data

Example:

import { decryptData } from '@eqxjs/azure-manage-identity';

const decrypted = await decryptData(
  'https://your-keyvault.vault.azure.net/',
  'encryption-key',
  'base64url-encoded-ciphertext',
  'iv-secret',
);

Authentication

This library uses Azure's DefaultAzureCredential for authentication, which automatically handles:

• Managed Identity (for Azure-hosted applications)
• Azure CLI credentials
• Environment variables
• Visual Studio Code credentials
• And other Azure authentication methods

Ensure your application has the appropriate permissions to access the Azure Key Vault resources.

Required Azure Key Vault Permissions

Your managed identity or service principal needs the following permissions:

For Secret Operations:

• Get - To read secrets
• Set - To create/update secrets
• List - To list secret versions
• Delete - To remove secrets

For Key Operations:

• Get - To retrieve keys
• Sign - To sign data/JWT tokens
• Verify - To verify signatures
• Encrypt - To encrypt data
• Decrypt - To decrypt data

Dependencies

This library depends on:

• @azure/identity - Azure authentication
• @azure/keyvault-keys - Key Vault key operations
• @azure/keyvault-secrets - Key Vault secret operations
• jsonwebtoken - JWT operations
• base64url - Base64URL encoding/decoding

License

ISC

Author

Equinox