Muokkaa

Jaa

Quickstart: Azure Key Vault key client library for .NET

  • Artikkeli

Get started with the Azure Key Vault key client library for .NET. Azure Key Vault is a cloud service that provides a secure store for cryptographic keys. You can securely store cryptographic keys, passwords, certificates, and other secrets. Azure key vaults may be created and managed through the Azure portal. In this quickstart, you learn how to create, retrieve, and delete keys from an Azure key vault using the .NET key client library

Key Vault key client library resources:

API reference documentation | Library source code | Package (NuGet)

For more information about Key Vault and keys, see:

Prerequisites

This quickstart is using dotnet and Azure CLI

Setup

This quickstart is using Azure Identity library with Azure CLI to authenticate user to Azure Services. Developers can also use Visual Studio or Visual Studio Code to authenticate their calls, for more information, see Authenticate the client with Azure Identity client library.

Sign in to Azure

  1. Run the login command.

    az login

    If the CLI can open your default browser, it will do so and load an Azure sign-in page.

    Otherwise, open a browser page at https://aka.ms/devicelogin and enter the authorization code displayed in your terminal.

  2. Sign in with your account credentials in the browser.

Grant access to your key vault

To gain permissions to your key vault through Role-Based Access Control (RBAC), assign a role to your "User Principal Name" (UPN) using the Azure CLI command az role assignment create.

az role assignment create --role "Key Vault Crypto Officer" --assignee "<upn>" --scope "/subscriptions/<subscription-id>/resourceGroups/<resource-group-name>/providers/Microsoft.KeyVault/vaults/<your-unique-keyvault-name>"

Replace <upn>, <subscription-id>, <resource-group-name> and <your-unique-keyvault-name> with your actual values. Your UPN will typically be in the format of an email address (e.g., username@domain.com).

Create new .NET console app

  1. In a command shell, run the following command to create a project named key-vault-console-app:

    dotnet new console --name key-vault-console-app

  2. Change to the newly created key-vault-console-app directory, and run the following command to build the project:

    dotnet build

    The build output should contain no warnings or errors.

    Build succeeded.
 0 Warning(s)
 0 Error(s)

Install the packages

From the command shell, install the Azure Key Vault key client library for .NET:

dotnet add package Azure.Security.KeyVault.Keys

For this quickstart, you'll also need to install the Azure Identity client library:

dotnet add package Azure.Identity

Set environment variables

This application is using key vault name as an environment variable called KEY_VAULT_NAME.

Windows

set KEY_VAULT_NAME=<your-key-vault-name>

Windows PowerShell

$Env:KEY_VAULT_NAME="<your-key-vault-name>"

macOS or Linux

export KEY_VAULT_NAME=<your-key-vault-name>

Object model

The Azure Key Vault key client library for .NET allows you to manage keys. The Code examples section shows how to create a client, set a key, retrieve a key, and delete a key.

Code examples

Add directives

Add the following directives to the top of Program.cs:

using System;
using Azure.Identity;
using Azure.Security.KeyVault.Keys;

Authenticate and create a client

Application requests to most Azure services must be authorized. Using the DefaultAzureCredential class provided by the Azure Identity client library is the recommended approach for implementing passwordless connections to Azure services in your code. DefaultAzureCredential supports multiple authentication methods and determines which method should be used at runtime. This approach enables your app to use different authentication methods in different environments (local vs. production) without implementing environment-specific code.

In this quickstart, DefaultAzureCredential authenticates to key vault using the credentials of the local development user logged into the Azure CLI. When the application is deployed to Azure, the same DefaultAzureCredential code can automatically discover and use a managed identity that is assigned to an App Service, Virtual Machine, or other services. For more information, see Managed Identity Overview.

In this example, the name of your key vault is expanded to the key vault URI, in the format https://<your-key-vault-name>.vault.azure.net. For more information about authenticating to key vault, see Developer's Guide.

var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
var kvUri = $"https://{keyVaultName}.vault.azure.net";

var client = new KeyClient(new Uri(kvUri), new DefaultAzureCredential());

Save a key

For this task, use the CreateKeyAsync method. The method's parameters accepts a key name and the key type.

var key = await client.CreateKeyAsync("myKey", KeyType.Rsa);

Note

If key name exists, this code will create new version of that key.

Retrieve a key

You can now retrieve the previously created key with the GetKeyAsync method.

var key = await client.GetKeyAsync("myKey");

Delete a key

Finally, let's delete and purge the key from your key vault with the StartDeleteKeyAsync and PurgeDeletedKeyAsync methods.

var operation = await client.StartDeleteKeyAsync("myKey");

// You only need to wait for completion if you want to purge or recover the key.
await operation.WaitForCompletionAsync();

var key = operation.Value;
await client.PurgeDeletedKeyAsync("myKey");

Sample code

Modify the .NET console app to interact with the Key Vault by completing the following steps:

  • Replace the code in Program.cs with the following code:

    using System;
using System.Threading.Tasks;
using Azure.Identity;
using Azure.Security.KeyVault.Keys;

namespace key_vault_console_app
{
    class Program
    {
        static async Task Main(string[] args)
        {
            const string keyName = "myKey";
            var keyVaultName = Environment.GetEnvironmentVariable("KEY_VAULT_NAME");
            var kvUri = $"https://{keyVaultName}.vault.azure.net";

            var client = new KeyClient(new Uri(kvUri), new DefaultAzureCredential());

            Console.Write($"Creating a key in {keyVaultName} called '{keyName}' ...");
            var createdKey = await client.CreateKeyAsync(keyName, KeyType.Rsa);
            Console.WriteLine("done.");

            Console.WriteLine($"Retrieving your key from {keyVaultName}.");
            var key = await client.GetKeyAsync(keyName);
            Console.WriteLine($"Your key version is '{key.Value.Properties.Version}'.");

            Console.Write($"Deleting your key from {keyVaultName} ...");
            var deleteOperation = await client.StartDeleteKeyAsync(keyName);
            // You only need to wait for completion if you want to purge or recover the key.
            await deleteOperation.WaitForCompletionAsync();
            Console.WriteLine("done.");

            Console.Write($"Purging your key from {keyVaultName} ...");
            await client.PurgeDeletedKeyAsync(keyName);
            Console.WriteLine(" done.");
        }
    }
}

Test and verify

  1. Execute the following command to build the project

    dotnet build

  2. Execute the following command to run the app.

    dotnet run

  3. When prompted, enter a secret value. For example, mySecretPassword.

    A variation of the following output appears:

    Creating a key in mykeyvault called 'myKey' ... done.
Retrieving your key from mykeyvault.
Your key version is '8532359bced24e4bb2525f2d2050738a'.
Deleting your key from jl-kv ... done
Purging your key from <your-unique-keyvault-name> ... done.

Next steps

In this quickstart, you created a key vault, stored a key, and retrieved that key.

To learn more about Key Vault and how to integrate it with your apps, see the following articles: