Azure KeyVault Administration-clientbibliotheek voor .NET - versie 4.3.0

Azure Key Vault Managed HSM is een volledig beheerde, maximaal beschikbare cloudservice met één tenant en voldoet aan standaarden waarmee u cryptografische sleutels voor uw cloudtoepassingen kunt beveiligen met behulp van HSM's met FIPS 140-2 Niveau 3.

De Azure Key Vault-beheerbibliotheekclients ondersteunen beheertaken zoals volledige back-up/herstel en op rollen gebaseerd toegangsbeheer op sleutelniveau (RBAC).

Broncode | Pakket (NuGet) | Productdocumentatie | Monsters

Aan de slag

Het pakket installeren

Installeer de Azure Key Vault-beheerclientbibliotheek voor .NET met NuGet:

dotnet add package Azure.Security.KeyVault.Administration

Vereisten

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

Voer de volgende CLI-opdracht uit om een beheerde HSM-resource te maken:

az keyvault create --hsm-name <your-key-vault-name> --resource-group <your-resource-group-name> --administrators <your-user-object-id> --location <your-azure-location>

<your-user-object-id> U kunt de volgende CLI-opdracht uitvoeren:

az ad user show --id <your-user-principal> --query id

De client verifiëren

Als u wilt communiceren met de Azure Key Vault-service, moet u een exemplaar van de onderstaande clientklassen 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, wat 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 van verificatie en de bijbehorende referentietypen vindt u in de Documentatie over 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

Uw beheerde HSM activeren

Alle gegevensvlakopdrachten worden uitgeschakeld totdat de HSM is geactiveerd. U kunt geen sleutels maken of rollen toewijzen. Alleen de aangewezen beheerders, die zijn toegewezen tijdens het maken van de opdracht, kunnen de HSM activeren. Als u de HSM wilt activeren, moet u het beveiligingsdomein downloaden.

Om uw HSM te activeren, hebt u het volgende nodig:

• Minimaal 3 RSA-sleutelparen (maximaal 10)
• Geef het minimale aantal sleutels op dat is vereist voor het ontsleutelen van het beveiligingsdomein (quorum)

Als u de HSM wilt activeren, stuurt u ten minste 3 (maximaal 10) openbare RSA-sleutels naar de HSM. De HSM versleutelt het beveiligingsdomein met deze sleutels en stuurt het terug. Zodra dit beveiligingsdomein is gedownload, is uw HSM klaar voor gebruik. U moet ook een quorum opgeven. Dit is het minimale aantal persoonlijke sleutels dat vereist is voor het ontsleutelen van het beveiligingsdomein.

In het onderstaande voorbeeld ziet u hoe u openssl gebruikt om 3 zelfondertekende certificaten te genereren.

openssl req -newkey rsa:2048 -nodes -keyout cert_0.key -x509 -days 365 -out cert_0.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_1.key -x509 -days 365 -out cert_1.cer
openssl req -newkey rsa:2048 -nodes -keyout cert_2.key -x509 -days 365 -out cert_2.cer

Gebruik de az keyvault security-domain download opdracht om het beveiligingsdomein te downloaden en uw beheerde HSM te activeren. In het onderstaande voorbeeld worden drie RSA-sleutelparen gebruikt (alleen openbare sleutels zijn nodig voor deze opdracht) en wordt het quorum ingesteld op 2.

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

Toegang tot uw beheerde HSM beheren

De aangewezen beheerders die tijdens het maken zijn toegewezen, worden automatisch toegevoegd aan de ingebouwde rol Beheerde HSM-beheerders, die een beveiligingsdomein kunnen downloaden en rollen kunnen beheren voor toegang tot het gegevensvlak, naast andere beperkte machtigingen.

Als u andere acties op sleutels wilt uitvoeren, moet u principals toewijzen aan andere rollen, zoals 'Beheerde HSM Crypto-gebruiker', die niet-destructieve sleutelbewerkingen kan uitvoeren:

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>

Lees de best practices voor het correct beveiligen van uw beheerde HSM.

KeyVaultAccessControlClient maken

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

KeyVaultAccessControlClient client = new KeyVaultAccessControlClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

KeyVaultBackupClient maken

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

KeyVaultBackupClient client = new KeyVaultBackupClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

KeyVaultSettingClient maken

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

KeyVaultSettingsClient client = new KeyVaultSettingsClient(new Uri(managedHsmUrl), new DefaultAzureCredential());

Belangrijkste concepten

KeyVaultRoleDefinition

Een KeyVaultRoleDefinition is een verzameling machtigingen. Een roldefinitie definieert de bewerkingen die kunnen worden uitgevoerd, zoals lezen, schrijven en verwijderen. Het kan ook de bewerkingen definiëren die zijn uitgesloten van toegestane bewerkingen.

KeyVaultRoleDefinitions kunnen worden vermeld en opgegeven als onderdeel van een KeyVaultRoleAssignment.

KeyVaultRoleAssignment

A KeyVaultRoleAssignment is de koppeling van een KeyVaultRoleDefinition aan een service-principal. Ze kunnen afzonderlijk worden gemaakt, weergegeven, opgehaald en verwijderd.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient biedt zowel synchrone als asynchrone bewerkingen die het beheer van KeyVaultRoleDefinition en-objecten KeyVaultRoleAssignment mogelijk maken.

KeyVaultBackupClient

A KeyVaultBackupClient biedt zowel synchrone als asynchrone bewerkingen voor het uitvoeren van volledige sleutelback-ups, volledige sleutelherstel en selectief sleutelherstel.

BackupOperation

Een BackupOperation vertegenwoordigt een langdurige bewerking voor een volledige sleutelback-up.

RestoreOperation

A RestoreOperation vertegenwoordigt een langdurige bewerking voor zowel een volledige sleutel als het herstellen van een selectieve sleutel.

Veiligheid van schroefdraad

We garanderen dat alle clientexemplaarmethoden thread-veilig 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 | Afhandeling van fouten | Diagnostics | Spottende | Clientlevensduur

Voorbeelden

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

De volgende sectie bevat verschillende codefragmenten met behulp van de client hierboven gemaakte voor toegangsbeheer- of back-upclients, die betrekking hebben op enkele van de meest voorkomende taken met betrekking tot toegangsbeheer in Azure Key Vault:

Voorbeelden van synchronisatie

• Toegangsbeheer
  • Alle roldefinities weergeven
  • Alle roltoewijzingen weergeven
  • Een roltoewijzing maken
  • Een roltoewijzing verkrijgen
  • Een roltoewijzing verwijderen
• Back-ups en herstellen
  • Een volledige sleutelback-up uitvoeren
  • Een volledige sleutelherstel uitvoeren

Asynchrone voorbeelden

• Toegangsbeheer
  • Alle roldefinities weergeven
  • Alle roltoewijzingen weergeven
  • Een roltoewijzing maken
  • Een roltoewijzing verkrijgen
  • Een roltoewijzing verwijderen
• Back-ups en herstellen
  • Een volledige sleutelback-up uitvoeren
  • Een volledige sleutelherstel uitvoeren

Problemen oplossen

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

Algemeen

Wanneer u communiceert met de Azure Key Vault-beheerbibliotheek 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 roltoewijzing probeert op te halen die niet bestaat in uw Azure Key Vault, wordt er een 404 fout geretourneerd met de melding 'Niet gevonden'.

try
{
    KeyVaultRoleAssignment roleAssignment = client.GetRoleAssignment(KeyVaultRoleScope.Global, "example-name");
}
catch (RequestFailedException ex)
{
    Console.WriteLine(ex.ToString());
}

Azure.RequestFailedException: Service request failed.
Status: 404 (Not Found)

Content:
{"error":{"code":"RoleAssignmentNotFound","message":"Requested role assignment not found (Activity ID: a67f09f4-b68e-11ea-bd6d-0242ac120006)"}}

Headers:
X-Content-Type-Options: REDACTED
x-ms-request-id: a67f09f4-b68e-11ea-bd6d-0242ac120006
Content-Length: 143
Content-Type: application/json

Consolelogboekregistratie instellen

De eenvoudigste manier om de logboeken te bekijken, is door de consolelogboekregistratie in te schakelen. Gebruik de methode om een Azure SDK-logboeklistener te maken waarmee berichten worden uitgevoerd naar de AzureEventSourceListener.CreateConsoleLogger console.

// Setup a listener to monitor logged events.
using AzureEventSourceListener listener = AzureEventSourceListener.CreateConsoleLogger();

Meer informatie over andere mechanismen voor logboekregistratie vindt u hier.

Volgende stappen

Ga aan de slag met onze voorbeelden.

Bijdragen

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.

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.