Azure Key Vault-clientbibliotheek voor geheimen voor .NET - versie 4.5.0

  • Artikel

Azure Key Vault is een cloudservice die een veilige opslag van geheimen biedt, zoals wachtwoorden en databaseverbindingsreeksen.

Met de azure Key Vault-clientbibliotheek voor geheimen kunt u de toegang tot tokens, wachtwoorden, API-sleutels en andere geheimen veilig opslaan en beheren. Deze bibliotheek biedt bewerkingen voor het maken, ophalen, bijwerken, verwijderen, opschonen, back-up maken, herstellen en vermelden van de geheimen en de bijbehorende versies.

Broncode | Pakket (NuGet) | API-referentiedocumentatie | Productdocumentatie | Monsters | Migratiehandleiding

Aan de slag

Het pakket installeren

Installeer de azure Key Vault secrets-clientbibliotheek voor .NET met NuGet:

dotnet add package Azure.Security.KeyVault.Secrets

Vereisten

  • Een Azure-abonnement.
  • Een bestaande Azure-Key Vault. Als u een Azure-Key Vault wilt maken, kunt u Azure Portal of Azure CLI gebruiken.
  • Autorisatie voor een bestaande Azure-Key Vault met behulp van RBAC (aanbevolen) of toegangsbeheer.

Als u de Azure CLI gebruikt, vervangt u en <your-key-vault-name> door <your-resource-group-name> uw eigen, unieke namen:

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

De client verifiëren

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de klasse SecretClient maken. U hebt een kluis-URL nodig, die u mogelijk ziet als 'DNS-naam' in de portal, en referenties om een clientobject te instantiëren.

In de onderstaande voorbeelden wordt een DefaultAzureCredentialgebruikt, die geschikt is voor de meeste scenario's, waaronder lokale ontwikkel- en productieomgevingen. Daarnaast raden we u aan een beheerde identiteit te gebruiken voor verificatie in productieomgevingen. Meer informatie over verschillende manieren om te verifiëren en de bijbehorende referentietypen vindt u in de Documentatie voor Azure Identity .

Als u de DefaultAzureCredential onderstaande provider of andere referentieproviders wilt gebruiken die bij de Azure SDK worden geleverd, moet u eerst het pakket Azure.Identity installeren:

dotnet add package Azure.Identity

Instantieer een DefaultAzureCredential om door te geven aan de client. Hetzelfde exemplaar van een tokenreferentie kan worden gebruikt met meerdere clients als ze verifiëren met dezelfde identiteit.

// 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");

Belangrijkste concepten

KeyVaultSecret

Een KeyVaultSecret is de fundamentele resource binnen Azure Key Vault. Vanuit het perspectief van een ontwikkelaar accepteren en retourneren Azure Key Vault API's geheime waarden als tekenreeksen.

SecretClient

A SecretClient biedt zowel synchrone als asynchrone bewerkingen in de SDK, zodat een client kan worden geselecteerd op basis van de use-case van een toepassing. Zodra u een SecretClienthebt geïnitialiseerd, kunt u werken met geheimen in Azure Key Vault.

Veiligheid van schroefdraad

We garanderen dat alle clientexemplaren veilig zijn en onafhankelijk van elkaar zijn (richtlijn). Dit zorgt ervoor dat de aanbeveling om clientexemplaren opnieuw te gebruiken altijd veilig is, zelfs voor alle threads.

Aanvullende concepten

Clientopties | Toegang tot het antwoord | Langlopende bewerkingen | Fouten | afhandelen Diagnostics | Spottende | Clientlevensduur

Voorbeelden

Het pakket Azure.Security.KeyVault.Secrets ondersteunt synchrone en asynchrone API's.

De volgende sectie bevat verschillende codefragmenten met behulp van de client hierboven gemaakte code, die betrekking hebben op enkele van de meest voorkomende taken met betrekking tot azure Key Vault secret service:

Voorbeelden van synchronisatie

Asynchrone voorbeelden

Een geheim maken

SetSecretmaakt een KeyVaultSecret die moet worden opgeslagen in de Azure Key Vault. Als er al een geheim met dezelfde naam bestaat, wordt er een nieuwe versie van het geheim gemaakt.

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);

Een geheim ophalen

GetSecrethaalt een geheim op dat eerder is opgeslagen in de Azure Key Vault.

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

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

Een bestaand geheim bijwerken

UpdateSecretPropertieswerkt een geheim bij dat eerder is opgeslagen in de Azure Key Vault. Alleen de kenmerken van het geheim worden bijgewerkt. Als u de waarde wilt bijwerken, roept u SecretClient.SetSecret aan op een geheim met dezelfde naam.

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);

Een geheim verwijderen

StartDeleteSecretstart een langdurige bewerking om een geheim te verwijderen dat eerder is opgeslagen in de Azure Key Vault. U kunt het geheim onmiddellijk ophalen zonder te wachten tot de bewerking is voltooid. Wanneer voorlopig verwijderen niet is ingeschakeld voor de Azure Key Vault, wordt het geheim met deze bewerking definitief verwijderd.

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

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

Een geheim verwijderen en opschonen

U moet wachten tot de langlopende bewerking is voltooid voordat u probeert het geheim te verwijderen of te herstellen. U kunt dit doen door in een lus aan te roepen UpdateStatus , zoals hieronder wordt weergegeven:

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);

Geheimen vermelden

In dit voorbeeld worden alle geheimen in de opgegeven Azure-Key Vault weergegeven. De waarde wordt niet geretourneerd wanneer alle geheimen worden weergegeven. U moet aanroepen SecretClient.GetSecret om de waarde op te halen.

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

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

Asynchroon een geheim maken

De asynchrone API's zijn identiek aan hun synchrone tegenhangers, maar worden geretourneerd met het typische Asynchrone achtervoegsel voor asynchrone methoden en retourneren een Task.

In dit voorbeeld wordt een geheim gemaakt in de Azure Key Vault met de opgegeven optionele argumenten.

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

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

Geheimen asynchroon weergeven

Het vermelden van geheimen is niet afhankelijk van het wachten op de GetPropertiesOfSecretsAsync methode, maar retourneert een AsyncPageable<SecretProperties> die u kunt gebruiken met de await foreach -instructie:

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

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

Een geheim asynchroon verwijderen

Wanneer u een geheim asynchroon verwijdert voordat u het opschoont, kunt u wachten op de WaitForCompletionAsync methode voor de bewerking. Deze wordt standaard voor onbepaalde tijd herhaald, maar u kunt deze annuleren door een CancellationTokendoor te geven.

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);

Problemen oplossen

Zie onze gids voor probleemoplossing voor meer informatie over het diagnosticeren van verschillende foutscenario's.

Algemeen

Wanneer u met de geheime clientbibliotheek van Azure Key Vault communiceert met behulp van de .NET SDK, komen fouten die door de service worden geretourneerd, overeen met dezelfde HTTP-statuscodes die worden geretourneerd voor REST API-aanvragen.

Als u bijvoorbeeld een geheim probeert op te halen dat niet bestaat in uw Azure Key Vault, wordt er een 404 fout geretourneerd, die Not Foundaangeeft.

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

U ziet dat aanvullende informatie wordt geregistreerd, zoals de clientaanvraag-id van de bewerking.

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

Volgende stappen

In deze GitHub-opslagplaats zijn verschillende voorbeelden van azure Key Vault geheimen voor u beschikbaar. Deze voorbeelden bevatten voorbeeldcode voor aanvullende scenario's die vaak voorkomen tijdens het werken met Azure Key Vault:

  • Sample1_HelloWorld.md : voor het werken met Azure Key Vault, waaronder:

    • Een geheim maken
    • Een bestaand geheim ophalen
    • Een bestaand geheim bijwerken
    • Geheim verwijderen

  • Sample2_BackupAndRestore.md - bevat de codefragmenten die werken met Azure Key Vault geheimen, waaronder:

    • Een back-up maken van een geheim en deze herstellen

  • Sample3_GetSecrets.md - voorbeeldcode voor het werken met Azure Key Vault geheimen, waaronder:

    • Geheimen maken
    • Alle geheimen in de Key Vault weergeven
    • Geheimen bijwerken in de Key Vault
    • Versies van een opgegeven geheim weergeven
    • Geheimen verwijderen uit de Key Vault
    • Verwijderde geheimen in de Key Vault weergeven

Aanvullende documentatie

Bijdragen

Zie de CONTRIBUTING.md voor meer informatie over het bouwen, testen en bijdragen aan deze bibliotheken.

Wij verwelkomen bijdragen en suggesties voor dit project. Voor de meeste bijdragen moet u instemmen met een licentieovereenkomst voor bijdragers (CLA: Contributor License Agreement) waarin u verklaart dat u gerechtigd bent ons het recht te geven uw bijdrage te gebruiken, en dat u dit ook doet. Ga naar https://cla.microsoft.com voor meer informatie.

Wanneer u een pull-aanvraag indient, wordt met een CLA-bot automatisch bepaald of u een CLA moet verschaffen en wordt de pull-aanvraag dienovereenkomstig opgemaakt (bijvoorbeeld met een label of commentaar). Volg gewoon de instructies van de bot. U hoeft dit maar eenmaal te doen voor alle repo's waar gebruik wordt gemaakt van onze CLA.

Op dit project is de Microsoft Open Source Code of Conduct (Microsoft Open Source-gedragscode) van toepassing. Zie voor meer informatie de veelgestelde vragen over de gedragscode of neem contact op opencode@microsoft.com met eventuele aanvullende vragen of opmerkingen.

Weergaven