[KeyVault] - Migrate all packages to Samples V2 (Azure#15023)

This PR migrates all 4 KeyVault packages to the new Samples V2 implementation.

I left most samples untouched (because otherwise it would be difficult to tell what is migrated vs. what actually changed), but did minor clean up where it made sense.

Resolves Azure#14475

Author: maorleger

sdk/keyvault/keyvault-admin/README.md

@@ -205,22 +205,8 @@ The methods that begin long running operations return a poller that allows you t
 
 We have samples both in JavaScript and TypeScript that show the access control and backup/restore features in this package. Please follow the corresponding readmes for detailed steps to run the samples.
 
-- [Readme for JavaScript samples](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/README.md)
-- [Readme for TypeScript samples](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/typescript/README.md)
-
-Direct links to the specific JavaScript samples follow:
-
-- Access control (RBAC):
-  - [Listing All Role Definitions](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/accessControlHelloWorld.js)
-  - [Listing All Role Assignments](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/accessControlHelloWorld.js)
-  - [Creating a Role Assignment](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/accessControlHelloWorld.js)
-  - [Getting a Role Assignment](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/accessControlHelloWorld.js)
-  - [Deleting a Role Assignment](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/accessControlHelloWorld.js)
-- Backup and restore:
-  - [Performing a full key backup](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/backupRestoreHelloWorld.js)
-  - [Performing a full key restore](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/backupRestoreHelloWorld.js)
-  - [Performing a selective key backup](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/backupSelectiveRestore.js)
-  - [Performing a selective key restore](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/javascript/backupSelectiveRestore.js)
+- [Readme for JavaScript samples](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/v4/javascript/README.md)
+- [Readme for TypeScript samples](https://github.com/Azure/azure-sdk-for-js/blob/master/sdk/keyvault/keyvault-admin/samples/v4/typescript/README.md)
 
 ## Troubleshooting
 

sdk/keyvault/keyvault-admin/package.json

@@ -46,17 +46,17 @@
   },
   "scripts": {
     "audit": "node ../../../common/scripts/rush-audit.js && rimraf node_modules package-lock.json && npm i --package-lock-only 2>&1 && npm audit",
-    "build:samples": "echo skipped",
+    "build:samples": "echo Obsolete.",
     "build:node": "tsc -p . && cross-env ONLY_NODE=true rollup -c 2>&1",
     "build:browser": "tsc -p . && cross-env ONLY_BROWSER=true rollup -c 2>&1",
     "build:nodebrowser": "rollup -c 2>&1",
     "build:test": "tsc -p . && rollup -c rollup.test.config.js 2>&1",
     "build": "tsc -p . && npm run build:nodebrowser && api-extractor run --local",
-    "check-format": "prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"*.{js,json}\"",
+    "check-format": "prettier --list-different --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"samples-dev/**/*.ts\" \"*.{js,json}\"",
     "clean": "rimraf dist dist-* types *.tgz *.log statistics.html coverage && rimraf src/**/*.js && rimraf test/**/*.js",
-    "execute:samples": "npm run build:samples && echo skipped",
+    "execute:samples": "dev-tools samples run samples-dev",
     "extract-api": "tsc -p . && api-extractor run --local",
-    "format": "prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"*.{js,json}\"",
+    "format": "prettier --write --config ../../../.prettierrc.json --ignore-path ../../../.prettierignore \"src/**/*.ts\" \"test/**/*.ts\" \"samples-dev/**/*.ts\" \"*.{js,json}\"",
     "integration-test:browser": "echo skipped",
     "integration-test:node": "nyc mocha -r esm --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --timeout 180000 --full-trace \"dist-esm/**/*.spec.js\"",
     "integration-test:node:no-timeout": "nyc mocha -r esm --require source-map-support/register --reporter ../../../common/tools/mocha-multi-reporter.js --no-timeouts --full-trace \"dist-esm/**/*.spec.js\"",
@@ -74,6 +74,20 @@
     "unit-test": "npm run unit-test:node && npm run unit-test:browser",
     "docs": "typedoc --excludePrivate --excludeNotExported --excludeExternals --stripInternal --mode file --out ./dist/docs ./src"
   },
+  "//sampleConfiguration": {
+    "productName": "Azure Key Vault Administration",
+    "productSlugs": [
+      "azure",
+      "azure-key-vault"
+    ],
+    "requiredResources": {
+      "Azure Key Vault": "https://docs.microsoft.com/azure/key-vault/quick-create-portal"
+    },
+    "customSnippets": {
+      "prerequisites": "samples-dev/snippets/_prerequisites.md"
+    },
+    "skipFolder": true
+  },
   "sideEffects": false,
   "dependencies": {
     "@azure/abort-controller": "^1.0.0",

sdk/keyvault/keyvault-admin/sample.env

@@ -1,8 +1,4 @@
-# The name of the key vault to use in the samples.
-# Create a Key Vault in the Azure Portal and enter its URI (e.g. https://mytest.vault.azure.net/) here.
-KEYVAULT_URI=<key-vault-uri>
-
-# The name of the Managed HSM Key Vault to use in the tests.
+# The name of the Managed HSM Key Vault to use in the samples.
 # At the moment only Azure Managed HSM supports administration operations.
 AZURE_MANAGEDHSM_URI=<managed-hsm-uri>
 
@@ -25,7 +21,3 @@ CLIENT_OBJECT_ID=<client-object-id>
 AZURE_TENANT_ID=<AD tenant id or name>
 AZURE_CLIENT_ID=<ID of the user/service principal to authenticate as>
 AZURE_CLIENT_SECRET=<client secret used to authenticate to Azure AD>
-
-# Our tests assume that TEST_MODE is "playback" by default. You can
-# change it to "record" to generate new recordings, or "live" to bypass the recorder entirely.
-# TEST_MODE=playback

…ypescript/src/accessControlHelloWorld.ts …n/samples-dev/accessControlHelloWorld.tssdk/keyvault/keyvault-admin/samples/typescript/src/accessControlHelloWorld.ts renamed to sdk/keyvault/keyvault-admin/samples-dev/accessControlHelloWorld.ts sdk/keyvault/keyvault-admin/samples/typescript/src/accessControlHelloWorld.ts renamed to sdk/keyvault/keyvault-admin/samples-dev/accessControlHelloWorld.ts

@@ -1,9 +1,13 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+/**
+ * @summary Uses an AccessControlClient to list, create, and assign roles to users.
+ */
+
 import { KeyVaultAccessControlClient, KeyVaultPermission } from "@azure/keyvault-admin";
 import { DefaultAzureCredential } from "@azure/identity";
-import { v4 as uuidv4 } from "uuid";
+import * as uuid from "uuid";
 
 // Load the .env file if it exists
 import * as dotenv from "dotenv";
@@ -14,9 +18,11 @@ export async function main(): Promise<void> {
   // - AZURE_TENANT_ID: The tenant ID in Azure Active Directory
   // - AZURE_CLIENT_ID: The application (client) ID registered in the AAD tenant
   // - AZURE_CLIENT_SECRET: The client secret for the registered application
-  // - CLIENT_OBJECT_ID: Object ID of the application, tenant or principal to whom the role will be assigned to
   const credential = new DefaultAzureCredential();
-  const url = process.env["KEYVAULT_URI"] || "<keyvault-url>";
+  const url = process.env["AZURE_MANAGEDHSM_URI"];
+  if (!url) {
+    throw new Error("Missing environment variable AZURE_MANAGEDHSM_URI.");
+  }
   const client = new KeyVaultAccessControlClient(url, credential);
 
   for await (const roleAssignment of client.listRoleAssignments("/")) {
@@ -25,7 +31,7 @@ export async function main(): Promise<void> {
 
   const globalScope = "/";
 
-  const roleDefinitionName = uuidv4();
+  const roleDefinitionName = uuid.v4();
   const permissions: KeyVaultPermission[] = [
     {
       dataActions: [
@@ -44,12 +50,16 @@ export async function main(): Promise<void> {
 
   // This sample uses a custom role but you may assign one of the many built-in roles.
   // Please refer to https://docs.microsoft.com/azure/key-vault/managed-hsm/built-in-roles for more information.
-  const roleAssignmentName = uuidv4();
+  const roleAssignmentName = uuid.v4();
+  const clientObjectId = process.env["CLIENT_OBJECT_ID"];
+  if (!clientObjectId) {
+    throw new Error("Missing environment variable CLIENT_OBJECT_ID.");
+  }
   let assignment = await client.createRoleAssignment(
     globalScope,
     roleAssignmentName,
     roleDefinition.id,
-    process.env["CLIENT_OBJECT_ID"]
+    clientObjectId
   );
   console.log(assignment);
 

…ypescript/src/backupRestoreHelloWorld.ts …n/samples-dev/backupRestoreHelloWorld.tssdk/keyvault/keyvault-admin/samples/typescript/src/backupRestoreHelloWorld.ts renamed to sdk/keyvault/keyvault-admin/samples-dev/backupRestoreHelloWorld.ts sdk/keyvault/keyvault-admin/samples/typescript/src/backupRestoreHelloWorld.ts renamed to sdk/keyvault/keyvault-admin/samples-dev/backupRestoreHelloWorld.ts

@@ -1,6 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+/**
+ * @summary Uses a BackupClient to backup and fully restore an Azure Key Vault using Azure Storage Blob.
+ */
+
 import { KeyVaultBackupClient } from "@azure/keyvault-admin";
 import { DefaultAzureCredential } from "@azure/identity";
 
@@ -17,18 +21,27 @@ export async function main(): Promise<void> {
   // - BLOB_STORAGE_SAS_TOKEN: URI of the Blob Storage instance, with the name of the container where the Key Vault backups will be generated
   // - CLIENT_OBJECT_ID: Object ID of the application, tenant or principal to whom the role will be assigned to
   const credential = new DefaultAzureCredential();
-  const url = process.env["KEYVAULT_URI"] || "<keyvault-url>";
+  const url = process.env["KEYVAULT_URI"];
+  if (!url) {
+    throw new Error("Missing environment variable KEYVAULT_URI.");
+  }
   const client = new KeyVaultBackupClient(url, credential);
 
   const blobStorageUri = process.env["BLOB_STORAGE_URI"];
+  if (!blobStorageUri) {
+    throw new Error("Missing environment variable BLOB_STORAGE_URI.");
+  }
   const sasToken = process.env["BLOB_STORAGE_SAS_TOKEN"];
-  const backupPoller = await client.beginBackup(blobStorageUri, sasToken);
+  if (!sasToken) {
+    throw new Error("Missing environment variable BLOB_STORAGE_SAS_TOKEN.");
+  }
+  const backupPoller = await client.beginBackup(blobStorageUri!, sasToken);
   const backupResult = await backupPoller.pollUntilDone();
 
   // The folder name should be at the end of the backupFolderUri, as in: https://<blob-storage-endpoint>/<folder-name>
-  const folderName = backupResult.backupFolderUri.split("/").pop();
+  const folderName = backupResult.backupFolderUri!.split("/").pop();
 
-  const restorePoller = await client.beginRestore(blobStorageUri, sasToken, folderName);
+  const restorePoller = await client.beginRestore(blobStorageUri, sasToken, folderName!);
   await restorePoller.pollUntilDone();
 }
 

…typescript/src/backupSelectiveRestore.ts …in/samples-dev/backupSelectiveRestore.tssdk/keyvault/keyvault-admin/samples/typescript/src/backupSelectiveRestore.ts renamed to sdk/keyvault/keyvault-admin/samples-dev/backupSelectiveRestore.ts sdk/keyvault/keyvault-admin/samples/typescript/src/backupSelectiveRestore.ts renamed to sdk/keyvault/keyvault-admin/samples-dev/backupSelectiveRestore.ts

@@ -1,6 +1,10 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT license.
 
+/**
+ * @summary Uses a BackupClient to backup and restore a specific key in Azure Key Vault using Azure Storage Blob.
+ */
+
 import { KeyVaultBackupClient } from "@azure/keyvault-admin";
 import { KeyClient } from "@azure/keyvault-keys";
 import { DefaultAzureCredential } from "@azure/identity";
@@ -18,25 +22,34 @@ export async function main(): Promise<void> {
   // - BLOB_STORAGE_SAS_TOKEN: URI of the Blob Storage instance, with the name of the container where the Key Vault backups will be generated
   // - CLIENT_OBJECT_ID: Object ID of the application, tenant or principal to whom the role will be assigned to
   const credential = new DefaultAzureCredential();
-  const url = process.env["KEYVAULT_URI"] || "<keyvault-url>";
+  const url = process.env["AZURE_MANAGEDHSM_URI"];
+  if (!url) {
+    throw new Error("Missing environment variable AZURE_MANAGEDHSM_URI.");
+  }
   const client = new KeyVaultBackupClient(url, credential);
 
   const keyClient = new KeyClient(url, credential);
   const keyName = "key-name";
   const key = await keyClient.createRsaKey(keyName);
 
   const blobStorageUri = process.env["BLOB_STORAGE_URI"];
+  if (!blobStorageUri) {
+    throw new Error("Missing environment variable BLOB_STORAGE_URI.");
+  }
   const sasToken = process.env["BLOB_STORAGE_SAS_TOKEN"];
+  if (!sasToken) {
+    throw new Error("Missing environment variable BLOB_STORAGE_SAS_TOKEN.");
+  }
   const backupPoller = await client.beginBackup(blobStorageUri, sasToken);
   const backupResult = await backupPoller.pollUntilDone();
 
   // The folder name should be at the end of the backupFolderUri, as in: https://<blob-storage-endpoint>/<folder-name>
-  const folderName = backupResult.backupFolderUri.split("/").pop();
+  const folderName = backupResult.backupFolderUri!.split("/").pop();
 
   const selectiveRestorePoller = await client.beginSelectiveRestore(
     blobStorageUri,
     sasToken,
-    folderName,
+    folderName!,
     key.name
   );
   await selectiveRestorePoller.pollUntilDone();

sdk/keyvault/keyvault-admin/samples-dev/snippets/_prerequisites.md

@@ -0,0 +1,5 @@
+To quickly create the needed Key Vault resources in Azure and to receive a connection string for them, you can deploy our sample template by clicking:
+
+[![](http://azuredeploy.net/deploybutton.png)](https://portal.azure.com/#create/Microsoft.Template/uri/https%3A%2F%2Fraw.githubusercontent.com%2FAzure%2Fazure-sdk-for-js%2Fmaster%2Fsdk%2Fkeyvault%2Ftest-resources.json)
+
+If creating the Key Vault manually using the Azure Portal, be aware that the samples require that the soft-delete feature be enabled. Our template above will enable this feature automatically, but it is possible to enable it manually using the Azure CLI. See [the documentation for enabling soft-delete in Key Vault](https://docs.microsoft.com/azure/key-vault/key-vault-soft-delete-cli) for more information.