Python için Azure Key Vault Yönetimi istemci kitaplığı - sürüm 4.3.0

Not: Yönetim kitaplığı yalnızca Yönetilen HSM ile çalışır; Key Vault hedefleyen işlevler başarısız olur.

Azure Key Vault aşağıdaki sorunların çözülmesine yardımcı olur:

• Kasa yönetimi (bu kitaplık) - rol tabanlı erişim denetimi (RBAC) ve kasa düzeyinde yedekleme ve geri yükleme seçenekleri
• Şifreleme anahtarı yönetimi (azure-keyvault-keys) - verilerinizi şifrelemek için kullanılan anahtarlara erişimi oluşturma, depolama ve denetleme
• Gizli dizi yönetimi (azure-keyvault-secrets) - belirteçlere, parolalara, sertifikalara, API anahtarlarına ve diğer gizli dizilere erişimi güvenli bir şekilde depolayın ve denetleyin
• Sertifika yönetimi (azure-keyvault-certificates) - genel ve özel SSL/TLS sertifikaları oluşturma, yönetme ve dağıtma

Kaynak kodu | Paket (PyPI) | Paket (Conda) | API başvuru belgeleri | Ürün belgeleri | Örnekleri

Bildirim

Python 2.7 için Azure SDK Python paketleri desteği 01 Ocak 2022'de sona erdi. Daha fazla bilgi ve soru için lütfen bu paketi kullanmak için https://github.com/Azure/azure-sdk-for-python/issues/20691.Python 3.7 veya üzeri gereklidir konusuna bakın. Daha fazla ayrıntı için lütfen Python için Azure SDK sürüm desteği ilkesine bakın.

Başlarken

Paketleri yükleme

pip ile azure-keyvault-administration ve azure-identity yükleyin:

pip install azure-keyvault-administration azure-identity

azure-identity , aşağıda gösterildiği gibi Azure Active Directory kimlik doğrulaması için kullanılır.

Önkoşullar

• Azure aboneliği
• Python 3.7 veya üzeri
• Mevcut Key Vault Yönetilen HSM. Bir tane oluşturmanız gerekiyorsa, bu belgedeki adımları izleyerek Azure CLI'yı kullanarak bunu yapabilirsiniz.

İstemcinin kimliğini doğrulama

Azure Key Vault hizmetiyle etkileşim kurmak için bir KeyVaultAccessControlClient veya KeyVaultBackupClient örneğinin yanı sıra bir kasa url'sine (Azure Portalda "DNS Adı" olarak görebileceğiniz) ve kimlik bilgisi nesnesine ihtiyacınız olacaktır. Bu belgede, yerel geliştirme ve üretim ortamları dahil olmak üzere çoğu senaryo için uygun olan DefaultAzureCredential kullanımı gösterilmektedir. Üretim ortamlarında kimlik doğrulaması için yönetilen kimlik kullanmanızı öneririz.

Diğer kimlik doğrulama yöntemleri ve ilgili kimlik bilgileri türleri hakkında daha fazla bilgi için bkz. azure-identity belgeleri.

KeyVaultAccessControlClient Oluşturma

Ortamınızı DefaultAzureCredential için uygun bir kimlik doğrulama yöntemi kullanacak şekilde yapılandırdıktan sonra, bir erişim denetimi istemcisi oluşturmak için aşağıdakileri yapabilirsiniz (değerini vault_url Yönetilen HSM'nizin URL'si ile değiştirerek):

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOT: Zaman uyumsuz bir istemci için bunun yerine 'leri KeyVaultAccessControlClient içeri aktarabilirsinizazure.keyvault.administration.aio.

KeyVaultBackupClient Oluşturma

Ortamınızı DefaultAzureCredential için uygun bir kimlik doğrulama yöntemi kullanacak şekilde yapılandırdıktan sonra, yedekleme istemcisi oluşturmak için aşağıdakileri yapabilirsiniz (değerini vault_url Yönetilen HSM'nizin URL'si ile değiştirerek):

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()

client = KeyVaultBackupClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOT: Zaman uyumsuz bir istemci için bunun yerine 'leri KeyVaultBackupClient içeri aktarabilirsinizazure.keyvault.administration.aio.

KeyVaultSettingsClient Oluşturma

Ortamınızı DefaultAzureCredential için uygun bir kimlik doğrulama yöntemi kullanacak şekilde yapılandırdıktan sonra, bir ayar istemcisi oluşturmak için aşağıdakileri yapabilirsiniz (değerini vault_url Yönetilen HSM'nizin URL'si ile değiştirerek):

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultSettingsClient

credential = DefaultAzureCredential()

client = KeyVaultSettingsClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

NOT: Zaman uyumsuz bir istemci için bunun yerine 'leri KeyVaultSettingsClient içeri aktarabilirsinizazure.keyvault.administration.aio.

Önemli kavramlar

Rol tanımı

Rol tanımı okuma, yazma ve silme gibi gerçekleştirilebilecek işlemleri tanımlar. İzin verilen işlemlerin dışında tutulan işlemleri de tanımlayabilir.

Rol tanımı, rol atamasının bir parçası olarak belirtilir.

Rol ataması

Rol ataması, rol tanımının hizmet sorumlusuyla ilişkisidir. Bunlar oluşturulabilir, listelenebilir, tek tek getirilebilir ve silinebilir.

KeyVaultAccessControlClient

A KeyVaultAccessControlClient , rol tanımlarını ve rol atamalarını yönetir.

KeyVaultBackupClient

A KeyVaultBackupClient , tam anahtar yedeklemeleri, tam anahtar geri yüklemeleri ve seçmeli anahtar geri yüklemeleri gerçekleştirir.

KeyVaultSettingsClient

A KeyVaultSettingsClient , Yönetilen HSM hesabı ayarlarını yönetir.

Örnekler

Bu bölüm, yaygın görevleri kapsayan kod parçacıkları içerir:

• Erişim denetimi
  • Tüm rol tanımlarını listeleme
  • Rol tanımını ayarlama, alma ve silme
  • Tüm rol atamalarını listeleme
  • Rol ataması oluşturma, alma ve silme
• Yedekleme ve geri yükleme
  • Tam anahtar yedeklemesi gerçekleştirme
  • Tam anahtar geri yükleme işlemi gerçekleştirme

Tüm rol tanımlarını listeleme

Atama için kullanılabilen rol tanımlarını listeleyin.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role definitions available for assignment
role_definitions = client.list_role_definitions(KeyVaultRoleScope.GLOBAL)

for definition in role_definitions:
    print(definition.id)
    print(definition.role_name)
    print(definition.description)

Rol tanımını ayarlama, alma ve silme

set_role_definition özel bir rol tanımı oluşturmak veya mevcut bir tanımı belirtilen adla güncelleştirmek için kullanılabilir.

import uuid
from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import (
    KeyVaultAccessControlClient,
    KeyVaultDataAction,
    KeyVaultPermission,
    KeyVaultRoleScope
)

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# create a custom role definition
permissions = [KeyVaultPermission(allowed_data_actions=[KeyVaultDataAction.READ_HSM_KEY])]
created_definition = client.set_role_definition(KeyVaultRoleScope.GLOBAL, permissions=permissions)

# update the custom role definition
permissions = [
    KeyVaultPermission(allowed_data_actions=[], denied_data_actions=[KeyVaultDataAction.READ_HSM_KEY])
]
updated_definition = client.set_role_definition(
    KeyVaultRoleScope.GLOBAL, permissions=permissions, role_name=created_definition.name
)

# get the custom role definition
definition = client.get_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

# delete the custom role definition
deleted_definition = client.delete_role_definition(KeyVaultRoleScope.GLOBAL, role_name=definition_name)

Tüm rol atamalarını listeleme

Sonraki kod parçacığında yeni rol ataması oluşturmadan önce, geçerli rol atamalarının tümünü listeleyin:

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# this will list all role assignments
role_assignments = client.list_role_assignments(KeyVaultRoleScope.GLOBAL)

for assignment in role_assignments:
    print(assignment.name)
    print(assignment.principal_id)
    print(assignment.role_definition_id)

Rol ataması oluşturma, alma ve silme

Hizmet sorumlusuna rol atayın. Bunun için rol tanımı kimliği ve hizmet sorumlusu nesne kimliği gerekir. Önceki için alınan rol tanımları listesinden bir kimlik ve ikincisinin yukarıdaki kod parçacığında alınan listeden bir atama principal_id kullanabilirsiniz.

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient, KeyVaultRoleScope

credential = DefaultAzureCredential()

client = KeyVaultAccessControlClient(
    vault_url="https://my-managed-hsm-name.managedhsm.azure.net/",
    credential=credential
)

# Replace <role-definition-id> with the id of a definition from the fetched list from an earlier example
role_definition_id = "<role-definition-id>"
# Replace <service-principal-object-id> with the principal_id of an assignment returned from the previous example
principal_id = "<service-principal-object-id>"

# first, let's create the role assignment
role_assignment = client.create_role_assignment(KeyVaultRoleScope.GLOBAL, role_definition_id, principal_id)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# now, we get it
role_assignment = client.get_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

# finally, we delete this role assignment
role_assignment = client.delete_role_assignment(KeyVaultRoleScope.GLOBAL, role_assignment.name)
print(role_assignment.name)
print(role_assignment.principal_id)
print(role_assignment.role_definition_id)

Tam anahtar yedeklemesi gerçekleştirme

Anahtar koleksiyonunuzun tamamını yedekleyin. Tam anahtar yedeklemeleri için yedekleme deposu, Paylaşılan Erişim İmzası kimlik doğrulaması kullanan bir blob depolama kapsayıcısıdır.

kullanarak BlobServiceClientSAS belirteci oluşturma hakkında daha fazla ayrıntı için buradaki örneklere bakın. Alternatif olarak, Depolama Gezgini bir SAS belirteci oluşturmak da mümkündür

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

# blob storage container URL, for example https://<account name>.blob.core.windows.net/backup
blob_storage_url = "<your-blob-storage-url>"
sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# Backup is a long-running operation. The client returns a poller object whose result() method
# blocks until the backup is complete, then returns an object representing the backup operation.
backup_poller = client.begin_backup(blob_storage_url, sas_token)
backup_operation = backup_poller.result()

# this is the Azure Storage Blob URL of the backup
print(backup_operation.folder_url)

Tam anahtar geri yükleme işlemi gerçekleştirme

Anahtar koleksiyonunuzun tamamını yedekten geri yükleyin. Tam anahtar geri yükleme için veri kaynağı, Paylaşılan Erişim İmzası kimlik doğrulaması kullanılarak erişilen bir depolama blobudur. Yukarıdaki kod parçacığındanazure_storage_blob_container_uri da gereklidir.

kullanarak BlobServiceClientSAS belirteci oluşturma hakkında daha fazla ayrıntı için buradaki örneklere bakın. Alternatif olarak, Depolama Gezgini bir SAS belirteci oluşturmak da mümkündür

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultBackupClient

credential = DefaultAzureCredential()
client = KeyVaultBackupClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

sas_token = "<your-sas-token>"  # replace with a sas token to your storage account

# URL to a storage blob, for example https://<account name>.blob.core.windows.net/backup/mhsm-account-2020090117323313
blob_url = "<your-blob-url>"

# Restore is a long-running operation. The client returns a poller object whose wait() method
# blocks until the restore is complete.
restore_poller = client.begin_restore(blob_url, sas_token)
restore_poller.wait()

Sorun giderme

azure-keyvault-administration Çeşitli hata senaryolarını tanılama hakkında ayrıntılı bilgi için sorun giderme kılavuzuna bakın.

Genel

Key Vault istemcileri azure-core'da tanımlanan özel durumları tetikler. Örneğin, mevcut olmayan bir rol ataması almaya çalışırsanız, KeyVaultAccessControlClient ResourceNotFoundError'ı oluşturur:

from azure.identity import DefaultAzureCredential
from azure.keyvault.administration import KeyVaultAccessControlClient
from azure.core.exceptions import ResourceNotFoundError

credential = DefaultAzureCredential()
client = KeyVaultAccessControlClient(vault_url="https://my-managed-hsm-name.managedhsm.azure.net/", credential=credential)

try:
    client.get_role_assignment("/", "which-does-not-exist")
except ResourceNotFoundError as e:
    print(e.message)

Yönetim kitaplığındaki istemciler yalnızca yönetilen HSM'de işlem gerçekleştirmek için kullanılabilir, bu nedenle Key Vault bunu yapmaya çalışmak hataya neden olur.

Sonraki adımlar

Python için Azure SDK GitHub deposunda çeşitli örnekler mevcuttur. Bu örnekler ek Key Vault senaryoları için örnek kod sağlar: | Dosya | Açıklama | |-------------|-------------| | access_control_operations.py | rol tanımlarını ve rol atamalarını oluşturma/güncelleştirme/silme | | access_control_operations_async.py | zaman uyumsuz istemci ile rol tanımlarını ve rol atamalarını oluşturma/güncelleştirme/silme | | backup_restore_operations.py | tam yedekleme ve geri yükleme | | backup_restore_operations_async.py | zaman uyumsuz istemci ile tam yedekleme ve geri yükleme | | settings_operations.py | Key Vault ayarlarını listeleme ve güncelleştirme | | settings_operations_async.py | zaman uyumsuz istemciyle Key Vault ayarlarını listeleme ve güncelleştirme |

Diğer belgeler

Azure Key Vault hakkında daha kapsamlı belgeler için API başvuru belgelerine bakın.

Yönetilen HSM hakkında daha kapsamlı belgeler için hizmet belgelerine bakın.

Katkıda bulunma

Bu proje, katkı ve önerilere açıktır. Çoğu durumda, sağladığınız katkıyı kullanmamız için bize hak tanıma hakkına sahip olduğunuzu ve bu hakkı bize tanıdığınızı bildiren bir Katkıda Bulunan Lisans Sözleşmesi’ni (CLA) kabul etmeniz gerekir. Ayrıntılar için bkz. https://cla.microsoft.com.

Bir çekme isteği gönderdiğinizde, CLA robotu bir CLA sağlamanız gerekip gerekmediğini otomatik olarak belirler ve çekme isteğini uygun şekilde donatır (örn. etiket, açıklama). Robot tarafından sağlanan yönergeleri izlemeniz yeterlidir. Bu işlemi, CLA’mızı kullanarak tüm depolarda yalnızca bir kere yapmanız gerekir.

Bu proje Microsoft Open Source Code of Conduct (Microsoft Açık Kaynak Kullanım Kuralları) belgesinde listelenen kurallara uygundur. Daha fazla bilgi için Kullanım Kuralları hakkında SSS bölümüne bakın veya başka soru ya da görüşleriniz olursa opencode@microsoft.com ile iletişime geçin.