Clarify Key Vault client creation instructions (Azure#23594)

* Clarify Key Vault client creation instructions

Fixes Azure#23586

* Resolved PR feedback

Author: heaths

sdk/keyvault/Azure.Security.KeyVault.Administration/README.md

@@ -5,7 +5,7 @@ cryptographic keys for your cloud applications using FIPS 140-2 Level 3 validate
 
 The Azure Key Vault administration library clients support administrative tasks such as full backup / restore and key-level role-based access control (RBAC).
 
-[Source code][admin_client_src] | [Package (NuGet)][admin_client_nuget_package] | [Product documentation][keyvault_docs] | [Samples][admin_client_samples]
+[Source code][admin_client_src] | [Package (NuGet)][admin_client_nuget_package] | [Product documentation][managedhsm_docs] | [Samples][admin_client_samples]
 
 ## Getting started
 
@@ -24,7 +24,7 @@ See the final two steps in the next section for details on creating the Key Vaul
 
 ### Authenticate the client
 In order to control permissions to the Key Vault service, you'll need to create an instance of the [KeyVaultAccessControlClient][rbac_client] class.
-You need a **vault URL**, which you may see as "DNS Name" in the portal,  and **client secret credentials (client id, client secret, tenant id)**
+You need a **Managed HSM URL**, which you may see as "DNS Name" in the portal,  and **client secret credentials (client id, client secret, tenant id)**
 to instantiate a client object.
 
 Client secret credential authentication is being used in this getting started section but you can find more ways to authenticate with
@@ -69,15 +69,15 @@ environment variables. The following example shows a way to do this in Powershel
     ```
 
 * Create the Managed HSM and grant the above mentioned service principal authorization to perform administrative operations on the Managed HSM
-(replace `<your-resource-group-name>` and `<your-key-vault-name>` with your own, unique names and `<your-service-principal-object-id>` with the value from above):
+(replace `<your-resource-group-name>` and `<your-managed-hsm-name>` with your own, unique names and `<your-service-principal-object-id>` with the value from above):
     ```PowerShell
-    az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-service-principal-object-id> --location <your-azure-location>
+    az keyvault create --hsm-name <your-managed-hsm-name> --resource-group <your-resource-group-name> --administrators <your-service-principal-object-id> --location <your-azure-location>
     ```
   This service principal is automatically added to the "Managed HSM Administrators" [built-in role][built_in_roles].
 
 * Use the above mentioned Azure Key Vault name to retrieve details of your Vault which also contains your Azure Key Vault URL:
     ```PowerShell
-    az keyvault show --hsm-name <your-key-vault-name>
+    az keyvault show --hsm-name <your-managed-hsm-name> --query properties.hsmUri --output tsv
     ```
 
 #### Activate your managed HSM
@@ -104,7 +104,7 @@ Use the `az keyvault security-domain download` command to download the security
 The example below, uses 3 RSA key pairs (only public keys are needed for this command) and sets the quorum to 2.
 
 ```PowerShell
-az keyvault security-domain download --hsm-name <your-key-vault-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json
+az keyvault security-domain download --hsm-name <your-managed-hsm-name> --sd-wrapping-keys ./certs/cert_0.cer ./certs/cert_1.cer ./certs/cert_2.cer --sd-quorum 2 --security-domain-file ContosoMHSM-SD.json
 ```
 
 #### Controlling access to your managed HSM
@@ -114,25 +114,24 @@ who are able to download a security domain and [manage roles for data plane acce
 To perform other actions on keys, you need to assign principals to other roles such as "Managed HSM Crypto User", which can perform non-destructive key operations:
 
 ```PowerShell
-az keyvault role assignment create --hsm-name <your-key-vault-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>
+az keyvault role assignment create --hsm-name <your-managed-hsm-name> --role "Managed HSM Crypto User" --scope / --assignee-object-id <principal-or-user-object-ID> --assignee-principal-type <principal-type>
 ```
 
 Please read [best practices][best_practices] for properly securing your managed HSM.
 
 #### Create KeyVaultAccessControlClient
-Once you've populated the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZURE_TENANT_ID** environment variables and replaced **your-vault-url**
-with the above returned URI, you can create the [KeyVaultAccessControlClient][rbac_client]:
+Once you've populated the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET**, and **AZURE_TENANT_ID** environment variables, replace **managedHsmUrl** with the output of `az keyvault show` in the example below to create the [KeyVaultAccessControlClient][rbac_client]
 
 ```C# Snippet:HelloCreateKeyVaultAccessControlClient
-KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 ```
 
 #### Create KeyVaultBackupClient
-Once you've populated the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZURE_TENANT_ID** environment variables and replaced **your-vault-url**
+Once you've populated the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET** and **AZURE_TENANT_ID** environment variables and replaced **your-hsm-url**
 with the above returned URI, you can create the [KeyVaultBackupClient][backup_client]:
 
 ```C# Snippet:HelloCreateKeyVaultBackupClient
-KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 ```
 
 ## Key concepts
@@ -270,7 +269,7 @@ additional questions or comments.
 [code_of_conduct]: https://opensource.microsoft.com/codeofconduct/
 [rbac_client]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultAccessControlClient.cs
 [backup_client]: https://github.com/Azure/azure-sdk-for-net/blob/main/sdk/keyvault/Azure.Security.KeyVault.Administration/src/KeyVaultBackupClient.cs
-[keyvault_docs]: https://docs.microsoft.com/azure/key-vault/
+[managedhsm_docs]: https://docs.microsoft.com/azure/key-vault/managed-hsm/
 [keyvault_rest]: https://docs.microsoft.com/rest/api/keyvault/
 [admin_client_nuget_package]: https://www.nuget.org/packages?q=Azure.Security.KeyVault.Administration
 [admin_client_samples]: https://github.com/Azure/azure-sdk-for-net/tree/main/sdk/keyvault/Azure.Security.KeyVault.Administration/samples

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldAsync.md

@@ -11,7 +11,7 @@ You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number
 In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
 
 ```C# Snippet:HelloCreateKeyVaultBackupClient
-KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 ```
 
 ## Performing a full key backup

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_BackupHelloWorldSync.md

@@ -11,7 +11,7 @@ You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number
 In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
 
 ```C# Snippet:HelloCreateKeyVaultBackupClient
-KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 ```
 
 ## Performing a full key backup

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldAsync.md

@@ -11,7 +11,7 @@ You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number
 In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
 
 ```C# Snippet:HelloCreateKeyVaultAccessControlClient
-KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 ```
 
 ## Listing All Role Definitions

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample1_RbacHelloWorldSync.md

@@ -11,7 +11,7 @@ You can use the [DefaultAzureCredential][DefaultAzureCredential] to try a number
 In the sample below, you can set `keyVaultUrl` based on an environment variable, configuration setting, or any way that works for your application.
 
 ```C# Snippet:HelloCreateKeyVaultAccessControlClient
-KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 ```
 
 ## Listing All Role Definitions

sdk/keyvault/Azure.Security.KeyVault.Administration/samples/Sample3_BackRestoreResume.md

@@ -12,7 +12,7 @@ and check for status or wait for completion.
 
 ```C# Snippet:ResumeBackupAsync
 // Construct a new KeyVaultBackupClient or use an existing one.
-KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 
 // Construct a BackupOperation using a KeyVaultBackupClient and the Id from a previously started operation.
 KeyVaultBackupOperation backupOperation = new KeyVaultBackupOperation(client, backupOperationId);
@@ -33,7 +33,7 @@ and check for status or wait for completion.
 
 ```C# Snippet:ResumeRestoreAsync
 // Construct a new KeyVaultBackupClient or use an existing one.
-KeyVaultBackupClient Client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+KeyVaultBackupClient Client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 
 // Construct a RestoreOperation using a KeyVaultBackupClient and the Id from a previously started operation.
 KeyVaultRestoreOperation restoreOperation = new KeyVaultRestoreOperation(client, restoreOperationId);

sdk/keyvault/Azure.Security.KeyVault.Administration/tests/samples/AccessControlSampleSnippets.cs

@@ -31,11 +31,11 @@ public void TestSetup()
         public void CreateClient()
         {
             // Environment variable with the Key Vault endpoint.
-            string keyVaultUrl = TestEnvironment.ManagedHsmUrl;
+            string managedHsmUrl = TestEnvironment.ManagedHsmUrl;
 
             // Create a new access control client using the default credential from Azure.Identity using environment variables previously set,
             // including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
-            KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(vaultUri: new Uri(keyVaultUrl), credential: new DefaultAzureCredential());
+            KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(vaultUri: new Uri(managedHsmUrl), credential: new DefaultAzureCredential());
 #if !SNIPPET
             client = Client;
 #endif

sdk/keyvault/Azure.Security.KeyVault.Administration/tests/samples/Sample1_BackupHelloWorld.cs

@@ -18,10 +18,10 @@ public Sample1_BackupHelloWorld(bool isAsync, KeyVaultAdministrationClientOption
         [Test]
         public void CreateClientSample()
         {
-            var keyVaultUrl = TestEnvironment.ManagedHsmUrl;
+            var managedHsmUrl = TestEnvironment.ManagedHsmUrl;
 
             #region Snippet:HelloCreateKeyVaultBackupClient
-            KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+            KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
             #endregion
         }
 

sdk/keyvault/Azure.Security.KeyVault.Administration/tests/samples/Sample1_RbacHelloWorld.cs

@@ -32,10 +32,10 @@ public void TestSetup()
         public void CreateClient()
         {
             // Environment variable with the Key Vault endpoint.
-            string keyVaultUrl = TestEnvironment.ManagedHsmUrl;
+            string managedHsmUrl = TestEnvironment.ManagedHsmUrl;
 
             #region Snippet:HelloCreateKeyVaultAccessControlClient
-            KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+            KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
             #endregion
             client = Client;
         }

sdk/keyvault/Azure.Security.KeyVault.Administration/tests/samples/Sample3_BackRestoreResume.cs

@@ -34,7 +34,7 @@ public async Task ResumeBackupRestore()
             #region Snippet:ResumeBackupAsync
 #if SNIPPET
             // Construct a new KeyVaultBackupClient or use an existing one.
-            KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+            KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 #endif
 
             // Construct a BackupOperation using a KeyVaultBackupClient and the Id from a previously started operation.
@@ -62,7 +62,7 @@ public async Task ResumeBackupRestore()
             #region Snippet:ResumeRestoreAsync
 #if SNIPPET
             // Construct a new KeyVaultBackupClient or use an existing one.
-            KeyVaultBackupClient Client = new KeyVaultBackupClient(new Uri(keyVaultUrl), new DefaultAzureCredential());
+            KeyVaultBackupClient Client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());
 #endif
 
             // Construct a RestoreOperation using a KeyVaultBackupClient and the Id from a previously started operation.