Azure Key Vault hemligt klientbibliotek för .NET – version 4.5.0

  • Artikel

Azure Key Vault är en molntjänst som tillhandahåller en säker lagring av hemligheter, till exempel lösenord och databasanslutningssträngar.

Med klientbiblioteket för Azure Key Vault hemligheter kan du på ett säkert sätt lagra och kontrollera åtkomsten till token, lösenord, API-nycklar och andra hemligheter. Det här biblioteket erbjuder åtgärder för att skapa, hämta, uppdatera, ta bort, rensa, säkerhetskopiera, återställa och lista hemligheterna och dess versioner.

Källkod | Paket (NuGet) | API-referensdokumentation | Produktdokumentation | Prover | Migreringsguide

Komma igång

Installera paketet

Installera klientbiblioteket för Azure Key Vault secrets för .NET med NuGet:

dotnet add package Azure.Security.KeyVault.Secrets

Förutsättningar

  • En Azure-prenumeration.
  • En befintlig Azure-Key Vault. Om du behöver skapa en Azure-Key Vault kan du använda Azure Portal eller Azure CLI.
  • Auktorisering till en befintlig Azure-Key Vault med antingen RBAC (rekommenderas) eller åtkomstkontroll.

Om du använder Azure CLI ersätter <your-resource-group-name> du och <your-key-vault-name> med dina egna unika namn:

az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>

Autentisera klienten

För att kunna interagera med Azure Key Vault-tjänsten måste du skapa en instans av klassen SecretClient. Du behöver en valv-URL som du kan se som "DNS-namn" i portalen och autentiseringsuppgifter för att instansiera ett klientobjekt.

Exemplen som visas nedan använder en DefaultAzureCredential, som är lämplig för de flesta scenarier, inklusive lokala utvecklings- och produktionsmiljöer. Dessutom rekommenderar vi att du använder en hanterad identitet för autentisering i produktionsmiljöer. Du hittar mer information om olika sätt att autentisera och deras motsvarande typer av autentiseringsuppgifter i Azure Identity-dokumentationen .

Om du vill använda providern DefaultAzureCredential som visas nedan eller andra leverantörer av autentiseringsuppgifter som tillhandahålls med Azure SDK måste du först installera Azure.Identity-paketet:

dotnet add package Azure.Identity

Instansiera en DefaultAzureCredential för att skicka till klienten. Samma instans av en tokenautentiseringsuppgift kan användas med flera klienter om de ska autentiseras med samma identitet.

// Create a new secret client using the default credential from Azure.Identity using environment variables previously set,
// including AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID.
var client = new SecretClient(vaultUri: new Uri(vaultUrl), credential: new DefaultAzureCredential());

// Create a new secret using the secret client.
KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

// Retrieve a secret using the secret client.
secret = client.GetSecret("secret-name");

Viktiga begrepp

KeyVaultSecret

A KeyVaultSecret är den grundläggande resursen i Azure Key Vault. Ur utvecklarperspektiv accepterar och returnerar Azure Key Vault API:er hemliga värden som strängar.

SecretClient

A SecretClient tillhandahåller både synkrona och asynkrona åtgärder i SDK så att du kan välja en klient baserat på ett programs användningsfall. När du har initierat en SecretClientkan du interagera med hemligheter i Azure Key Vault.

Trådsäkerhet

Vi garanterar att alla klientinstansmetoder är trådsäkra och oberoende av varandra (riktlinje). Detta säkerställer att rekommendationen att återanvända klientinstanser alltid är säker, även över trådar.

Ytterligare begrepp

Klientalternativ | Åtkomst till svaret | Långvariga åtgärder | Hantera fel | Diagnostik | Gäckande | Klientlivslängd

Exempel

Paketet Azure.Security.KeyVault.Secrets stöder synkrona och asynkrona API:er.

Följande avsnitt innehåller flera kodfragment med hjälp av ovanståendeclient, som omfattar några av de vanligaste uppgifterna för Azure Key Vault secret service:

Synkroniseringsexempel

Asynkrona exempel

Skapa en hemlighet

SetSecretskapar en KeyVaultSecret som ska lagras i Azure Key Vault. Om det redan finns en hemlighet med samma namn skapas en ny version av hemligheten.

KeyVaultSecret secret = client.SetSecret("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);
Console.WriteLine(secret.Properties.Version);
Console.WriteLine(secret.Properties.Enabled);

Hämta en hemlighet

GetSecrethämtar en hemlighet som tidigare lagrats i Azure Key Vault.

KeyVaultSecret secret = client.GetSecret("secret-name");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Uppdatera en befintlig hemlighet

UpdateSecretPropertiesuppdaterar en hemlighet som tidigare lagrats i Azure Key Vault. Endast attributen för hemligheten uppdateras. Om du vill uppdatera värdet anropar du SecretClient.SetSecret en hemlighet med samma namn.

KeyVaultSecret secret = client.GetSecret("secret-name");

// Clients may specify the content type of a secret to assist in interpreting the secret data when its retrieved.
secret.Properties.ContentType = "text/plain";

// You can specify additional application-specific metadata in the form of tags.
secret.Properties.Tags["foo"] = "updated tag";

SecretProperties updatedSecretProperties = client.UpdateSecretProperties(secret.Properties);

Console.WriteLine(updatedSecretProperties.Name);
Console.WriteLine(updatedSecretProperties.Version);
Console.WriteLine(updatedSecretProperties.ContentType);

Ta bort en hemlighet

StartDeleteSecretstartar en tidskrävande åtgärd för att ta bort en hemlighet som tidigare lagrats i Azure Key Vault. Du kan hämta hemligheten omedelbart utan att vänta på att åtgärden ska slutföras. När mjuk borttagning inte är aktiverat för Azure-Key Vault tar den här åtgärden bort hemligheten permanent.

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

DeletedSecret secret = operation.Value;
Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Ta bort och rensa en hemlighet

Du måste vänta tills den långvariga åtgärden har slutförts innan du försöker rensa eller återställa hemligheten. Du kan göra detta genom att anropa UpdateStatus i en loop enligt nedan:

DeleteSecretOperation operation = client.StartDeleteSecret("secret-name");

// You only need to wait for completion if you want to purge or recover the secret.
// You should call `UpdateStatus` in another thread or after doing additional work like pumping messages.
while (!operation.HasCompleted)
{
    Thread.Sleep(2000);

    operation.UpdateStatus();
}

DeletedSecret secret = operation.Value;
client.PurgeDeletedSecret(secret.Name);

Visa en lista över hemligheter

I det här exemplet visas alla hemligheter i den angivna Azure-Key Vault. Värdet returneras inte när alla hemligheter listas. Du måste anropa SecretClient.GetSecret för att hämta värdet.

Pageable<SecretProperties> allSecrets = client.GetPropertiesOfSecrets();

foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Skapa en hemlighet asynkront

De asynkrona API:erna är identiska med deras synkrona motsvarigheter, men returnerar med det typiska Suffixet "Async" för asynkrona metoder och returnerar ett Task.

Det här exemplet skapar en hemlighet i Azure Key Vault med de angivna valfria argumenten.

KeyVaultSecret secret = await client.SetSecretAsync("secret-name", "secret-value");

Console.WriteLine(secret.Name);
Console.WriteLine(secret.Value);

Visa en lista över hemligheter asynkront

Att visa hemligheter förlitar sig inte på att vänta på GetPropertiesOfSecretsAsync metoden, men returnerar ett AsyncPageable<SecretProperties> som du kan använda med -instruktionen await foreach :

AsyncPageable<SecretProperties> allSecrets = client.GetPropertiesOfSecretsAsync();

await foreach (SecretProperties secretProperties in allSecrets)
{
    Console.WriteLine(secretProperties.Name);
}

Ta bort en hemlighet asynkront

När du tar bort en hemlighet asynkront innan du rensar den kan du vänta WaitForCompletionAsync på -metoden för åtgärden. Som standard loopar den här loopen på obestämd tid, men du kan avbryta den genom att skicka en CancellationToken.

DeleteSecretOperation operation = await client.StartDeleteSecretAsync("secret-name");

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

DeletedSecret secret = operation.Value;
await client.PurgeDeletedSecretAsync(secret.Name);

Felsökning

Mer information om hur du diagnostiserar olika felscenarier finns i vår felsökningsguide .

Allmänt

När du interagerar med Azure Key Vault hemliga klientbiblioteket med hjälp av .NET SDK motsvarar fel som returneras av tjänsten samma HTTP-statuskoder som returneras för REST API-begäranden.

Om du till exempel försöker hämta en hemlighet som inte finns i azure-Key Vault returneras ett 404 fel som anger Not Found.

try
{
    KeyVaultSecret secret = client.GetSecret("some_secret");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Du kommer att märka att ytterligare information loggas, till exempel ID för klientbegäran för åtgärden.

Message:
    Azure.RequestFailedException : Service request failed.
    Status: 404 (Not Found)
Content:
    {"error":{"code":"SecretNotFound","message":"Secret not found: some_secret"}}

Headers:
    Cache-Control: no-cache
    Pragma: no-cache
    Server: Microsoft-IIS/10.0
    x-ms-keyvault-region: westus
    x-ms-request-id: 625f870e-10ea-41e5-8380-282e5cf768f2
    x-ms-keyvault-service-version: 1.1.0.866
    x-ms-keyvault-network-info: addr=131.107.174.199;act_addr_fam=InterNetwork;
    X-AspNet-Version: 4.0.30319
    X-Powered-By: ASP.NET
    Strict-Transport-Security: max-age=31536000;includeSubDomains
    X-Content-Type-Options: nosniff
    Date: Tue, 18 Jun 2019 16:02:11 GMT
    Content-Length: 75
    Content-Type: application/json; charset=utf-8
    Expires: -1

Nästa steg

Det finns flera azure-Key Vault exempel på hemligheter i klientbiblioteket på den här GitHub-lagringsplatsen. De här exemplen innehåller exempelkod för ytterligare scenarier som ofta påträffas när du arbetar med Azure Key Vault:

  • Sample1_HelloWorld.md – för att arbeta med Azure Key Vault, inklusive:

    • Skapa en hemlighet
    • Hämta en befintlig hemlighet
    • Uppdatera en befintlig hemlighet
    • Ta bort hemlighet

  • Sample2_BackupAndRestore.md – innehåller kodfragment som arbetar med Azure Key Vault hemligheter, inklusive:

    • Säkerhetskopiera och återställa en hemlighet

  • Sample3_GetSecrets.md – exempelkod för att arbeta med Azure Key Vault hemligheter, inklusive:

    • Skapa hemligheter
    • Visa en lista över alla hemligheter i Key Vault
    • Uppdatera hemligheter i Key Vault
    • Lista versioner av en angiven hemlighet
    • Ta bort hemligheter från Key Vault
    • Lista borttagna hemligheter i Key Vault

Ytterligare dokumentation

Bidra

Mer information om hur du skapar, testar och bidrar till dessa bibliotek finns i CONTRIBUTING.md .

Det här projektet välkomnar bidrag och förslag. Merparten av bidragen kräver att du godkänner ett licensavtal för bidrag, där du deklarerar att du har behörighet att bevilja oss rättigheten att använda ditt bidrag, och att du dessutom uttryckligen gör så. Mer information finns på https://cla.microsoft.com.

När du skickar en pull-förfrågan avgör en CLA-robot automatiskt om du måste tillhandahålla ett licensavtal för bidrag med lämplig PR (t.ex. etikett eller kommentar). Följ bara robotens anvisningar. Du behöver bara göra detta en gång för alla repor som använder vårt licensavtal för bidrag.

Det här projektet använder sig av Microsofts uppförandekod för öppen källkod. Mer information finns i Vanliga frågor och svar om uppförandekod eller kontakt opencode@microsoft.com med ytterligare frågor eller kommentarer.

Visningar