@achs/azure-key-vault 中文文档教程

Question

Azure Key Vault

用于处理 Azure Key Vault 的节点库，在共享保管库时按项目、环境和组抽象机密管理。 此外，该库还处理嵌套的 JSON 结构。

How To Use ????

应使用 AzureKeyVault 初始化为：

import { AzureKeyVault } from '@calvear/azure-key-vault';

// initializes azure key vault
const keyVault = new AzureKeyVault(
    {
        project: 'my-project',
        group: 'web',
        env: 'dev',
    },
    {
        keyVaultUri: 'https://my-key-vault.vault.azure.net',
        clientId: 'f176a774-239e-4cd3-8551-88fd9fb9b441',
        clientSecret: 'WyBwkmcL8rGQe9B2fvRLDrqDuannE4Ku',
        tenantId: '9dba8525-be64-4d10-b124-e6f1644ae513',
    }
);

async function main() {
    await keyVault.setAll({
        SECRET1: 'my secret 1',
        SECRET2: 'my secret 2',
        otherConfig: {
            SECRET3: 'my secret 3',
        },
    });

    const mySecret2 = await keyVault.getInfo('SECRET2');
    console.log(mySecret2);
    // name is 'my-project-dev-web-secret2' and value 'my secret 2'

    const mySecret3 = await keyVault.getInfo('otherConfig:SECRET3');
    console.log(mySecret3);
    // name is 'my-project-dev-web-otherConfig--secret3' and value 'my secret 3'

    const mySecrets = await keyVault.getFor({
        SECRET1: null,
        SECRET2: 'default value',
        otherConfig: {
            SECRET3: null,
        },
        SECRET4: 'def for secret 4',
    });
    console.log(mySecrets);
    // prints { SECRET1: 'my secret 1, SECRET2: 'my secret 2', otherConfig: { SECRET3: 'my secret 3' }, SECRET4: 'def for secret 3' }
}

main();

您可以使用环境变量将密钥保管库初始化为：

import { AzureKeyVault } from '@calvear/azure-key-vault';

...
process.env.AZURE_KEY_VAULT_URI = 'https://my-key-vault.vault.azure.net';
process.env.AZURE_CLIENT_ID = 'f176a774-239e-4cd3-8551-88fd9fb9b441';
process.env.AZURE_CLIENT_SECRET = 'WyBwkmcL8rGQe9B2fvRLDrqDuannE4Ku';
process.env.AZURE_TENANT_ID = '9dba8525-be64-4d10-b124-e6f1644ae513';
...

// initializes azure key vault
const keyVault = new AzureKeyVault({
    project: 'my-project',
    group: 'web',
    env: 'dev'
});

...

Functions

库具有管理密钥保管库机密的功能。

[i] 您可以使用 ':' 作为嵌套路径，（即 car:props:name） [i] 您可以在密钥前加上“&” 对于项目共享机密，（即 car:props:$name）

• get: returns secret value.

Parameters	Description
key	(string) secret key
serialized	(boolean) whether value is serialized

const value = await keyVault.get('my-secret');

• getInfo: returns secret info.

Parameters	Description
key	(string) secret key

const info = await keyVault.getInfo('my-secret');

• set: inserts or updates secret value.

Parameters	Description
key	(string) secret key
value	(string) secret key

const info = await keyVault.set('my-secret', 'my secret value');

• delete: deletes a secret.

Parameters	Description
key	(string) secret key

const deletionInfo = await keyVault.delete('my-secret');

• purge: purges a deleted secret.

Parameters	Description
key	(string) secret key

const info = await keyVault.purge('my-secret');

• restore: restores a deleted secret.

Parameters	Description
key	(string) secret key

const restoredInfo = await keyVault.restore('my-secret');

• getAll: gets all secrets for the project, env and group.

const listOfSecrets = await keyVault.getAll();

• getFor: (faster than getAll) gets all secrets for the project, env and group defined in input object. In order to get array correctly deserialized, use [] as default value instead of null or undefined.

Parameters	Description
secrets	(any) object with secrets (key, value)
[override]	(boolean) (default: false) whether secrets with default value should be override

let secrets = {
    '$global-var': null,
    'my-secret': null,
    'my-secret-2': 'default value',
    'my-secret-group1': {
        'my-secret-3': null,
    },
    // in case of array type variable, default must be
    // an array (or empty array) for correct deserialize
    'my-array-secret': [],
};

const listOfSecrets = await keyVault.getFor(secrets);

• setAll: insert or updates a set of secrets.

Parameters	Description
secrets	(any) object with secrets (key, value)

let secrets = {
    '$global-var': 'my shared secret',
    'my-secret': 'my secret',
    'my-secret-2': 'my secret 2',
    'my-secret-group1': {
        'my-secret-3': 'my secret 3',
    },
    'my-array-secret': ['a', 'b', 'c'],
};

const listOfProperties = await keyVault.setAll(secrets);

• deleteAll: deletes every secrets for the project group.

Parameters	Description
skipGlobal	skips global variables

const info = await keyVault.deleteAll();

• purgeAll: purges every deleted secrets for the project group.

Parameters	Description
skipGlobal	skips global variables

const info = await keyVault.purgeAll();

• restoreAll: restores every deleted secrets for the project group.

Parameters	Description
skipGlobal	skips global variables

const info = await keyVault.restoreAll();

Commands

库具有用于 npm 的节点命令。 每个命令都需要凭据参数才能连接到密钥保管库。

Parameters	Description
--project	(string) project name
--group	(string) secrets group
--env	(string) environment
--uri	(string) key vault uri (i.e. https://my-key-vault.vault.azure.net)
--spn	(string) service principal name id (i.e. f176a774-239e-4cd3-8551-88fd9fb9b441)
--password	(string) spn secret password (i.e. WyBwkmcL8rGQe9B2fvRLDrqDuannE4Ku)
--tenant	(string) tenant id (i.e. 9dba8525-be64-4d10-b124-e6f1644ae513)

您应该在 package.json 中将 npm 脚本命令定义为：

// package.json
{
    ...,
    "scripts": {
        ...,
        "akv": "akv --project=my-project --group=web --tenant=9dba8525-be64-4d10-b124-e6f1644ae513",
        ...
    },
    ...
}

• getFor: writes a file with secrets as JSON, using a JSON file as secrets structure definition.

Parameters	Description
--file	(string) relative uri (from cmd root) for JSON file for structure definition
--output	(string) relative uri for result secrets JSON file

foo@bar:~$ npm run akv getFor -- \
    --env=dev \
    --uri=https://my-key-vault.vault.azure.net \
    --spn=f176a774-239e-4cd3-8551-88fd9fb9b441 \
    --password=WyBwkmcL8rGQe9B2fvRLDrqDuannE4Ku \
    --file=secrets-structure-definition.json \
    --output=my-secrets.json \
    --override

• getAll: writes all secrets (for project, group and env) in a JSON file.

Parameters	Description
--output	(string) relative uri for result secrets JSON file

foo@bar:~$ npm run akv getAll -- \
    --env=dev \
    --uri=https://my-key-vault.vault.azure.net \
    --spn=f176a774-239e-4cd3-8551-88fd9fb9b441 \
    --password=WyBwkmcL8rGQe9B2fvRLDrqDuannE4Ku \
    --output=my-secrets.json \
    --override

• publish: creates or updates secrets (for project, group and env) in key vault from a JSON file.

Parameters	Description
--file	(string) relative uri (from cmd root) for JSON file with secrets

foo@bar:~$ npm run akv publish -- \
    --env=dev \
    --uri=https://my-key-vault.vault.azure.net \
    --spn=f176a774-239e-4cd3-8551-88fd9fb9b441 \
    --password=WyBwkmcL8rGQe9B2fvRLDrqDuannE4Ku \
    --file=my-secrets.json

• clear：删除密钥保管库中的所有机密（针对项目、组和环境）。

• restore：恢复密钥保管库中所有已删除的机密（针对项目、组和环境）。

Linting ????

项目使用 ESLint，用于代码格式化和代码样式规范化。

• eslint: JavaScript and React linter with Airbnb React base config and some other additions.

为了正确解释 linters，建议使用 Visual Studio Code 作为 IDE，并将插件安装在“extensions.json”的 .vscode 文件夹中，以及使用“settings.json”中提供的配置

Changelog ????

对于最后的更改，请参阅 CHANGELOG.md 文件了解详细信息。

Built with ????️

• @azure/identity - azure identity provider.
• @azure/keyvault-secrets - azure key vault bae handler.