[KV] Add executable rotation samples (Azure#21161)

Author: mccoyp

sdk/keyvault/azure-keyvault-keys/README.md

@@ -251,7 +251,7 @@ from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotatio
 credential = DefaultAzureCredential()
 key_client = KeyClient(vault_url="https://my-key-vault.vault.azure.net/", credential=credential)
 
-# Set the key's automated rotation policy to rotate the key 30 days before expiry
+# Set the key's automated rotation policy to rotate the key 30 days before the key expires
 actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_before_expiry="P30D")]
 # You may also specify the duration after which the newly rotated key will expire
 # In this example, any new key versions will expire after 90 days

sdk/keyvault/azure-keyvault-keys/samples/README.md

@@ -20,7 +20,9 @@ These code snippets highlight this SDK's common use cases.
 [backup_restore_operations_async.py][backup_operations_async_sample] - backup and
 recover keys
 * [recover_purge_operations.py][recover_purge_sample] and
-[recover_purge_operations_async.py][recover_purge_async_sample] - recovering and purging keys
+[recover_purge_operations_async.py][recover_purge_async_sample] - recover and purge keys
+* [key_rotation.py][key_rotation_sample] and
+[key_rotation_async.py][key_rotation_async_sample] - rotate keys automatically and on-demand
 
 [hello_world_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/hello_world.py
 [hello_world_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/hello_world_async.py
@@ -29,4 +31,6 @@ recover keys
 [list_operations_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/list_operations.py
 [list_operations_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/list_operations_async.py
 [recover_purge_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/recover_purge_operations.py
-[recover_purge_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/recover_purge_operations_async.py
+[recover_purge_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/recover_purge_operations_async.py
+[key_rotation_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/key_rotation.py
+[key_rotation_async_sample]: https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys/samples/key_rotation_async.py

sdk/keyvault/azure-keyvault-keys/samples/backup_restore_operations.py

@@ -4,19 +4,23 @@
 # ------------------------------------
 import os
 import time
-from azure.keyvault.keys import KeyClient
 from azure.identity import DefaultAzureCredential
-from azure.core.exceptions import HttpResponseError
+from azure.keyvault.keys import KeyClient
 
 # ----------------------------------------------------------------------------------------------------------
 # Prerequisites:
-# 1. An Azure Key Vault (https://docs.microsoft.com/en-us/azure/key-vault/quick-create-cli)
+# 1. An Azure Key Vault (https://docs.microsoft.com/azure/key-vault/quick-create-cli)
 #
 # 2. azure-keyvault-keys and azure-identity libraries (pip install these)
 #
-# 3. Set Environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, VAULT_URL
+# 3. Set environment variable VAULT_URL with the URL of your key vault
+#    
+# 4. Set up your environment to use azure-identity's DefaultAzureCredential. To authenticate a service principal with
+#    environment variables, set AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID
 #    (See https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys#authenticate-the-client)
 #
+# 5. Key create, backup, delete, purge, and restore permissions for your service principal in your vault
+#
 # ----------------------------------------------------------------------------------------------------------
 # Sample - demonstrates the basic backup and restore operations on a vault(key) resource for Azure Key Vault
 #
@@ -32,9 +36,7 @@
 # ----------------------------------------------------------------------------------------------------------
 
 # Instantiate a key client that will be used to call the service.
-# Notice that the client is using default Azure credentials.
-# To make default credentials work, ensure that environment variables 'AZURE_CLIENT_ID',
-# 'AZURE_CLIENT_SECRET' and 'AZURE_TENANT_ID' are set with the service principal credentials.
+# Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
 VAULT_URL = os.environ["VAULT_URL"]
 credential = DefaultAzureCredential()
 client = KeyClient(vault_url=VAULT_URL, credential=credential)

sdk/keyvault/azure-keyvault-keys/samples/backup_restore_operations_async.py

@@ -4,19 +4,23 @@
 # ------------------------------------
 import asyncio
 import os
-from azure.keyvault.keys.aio import KeyClient
 from azure.identity.aio import DefaultAzureCredential
-from azure.core.exceptions import HttpResponseError
+from azure.keyvault.keys.aio import KeyClient
 
 # ----------------------------------------------------------------------------------------------------------
 # Prerequisites:
-# 1. An Azure Key Vault (https://docs.microsoft.com/en-us/azure/key-vault/quick-create-cli)
+# 1. An Azure Key Vault (https://docs.microsoft.com/azure/key-vault/quick-create-cli)
 #
 # 2. azure-keyvault-keys and azure-identity libraries (pip install these)
 #
-# 3. Set Environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, VAULT_URL
+# 3. Set environment variable VAULT_URL with the URL of your key vault
+#
+# 4. Set up your environment to use azure-identity's DefaultAzureCredential. To authenticate a service principal with
+#    environment variables, set AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID
 #    (See https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys#authenticate-the-client)
 #
+# 5. Key create, backup, delete, purge, and restore permissions for your service principal in your vault
+#
 # ----------------------------------------------------------------------------------------------------------
 # Sample - demonstrates the basic backup and restore operations on a vault(key) resource for Azure Key Vault
 #
@@ -30,11 +34,10 @@
 #
 # 5. Restore a key (restore_key_backup)
 # ----------------------------------------------------------------------------------------------------------
+
 async def run_sample():
     # Instantiate a key client that will be used to call the service.
-    # Notice that the client is using default Azure credentials.
-    # To make default credentials work, ensure that environment variables 'AZURE_CLIENT_ID',
-    # 'AZURE_CLIENT_SECRET' and 'AZURE_TENANT_ID' are set with the service principal credentials.
+    # Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
     VAULT_URL = os.environ["VAULT_URL"]
     credential = DefaultAzureCredential()
     client = KeyClient(vault_url=VAULT_URL, credential=credential)

sdk/keyvault/azure-keyvault-keys/samples/hello_world.py

@@ -4,19 +4,23 @@
 # ------------------------------------
 import datetime
 import os
-from azure.keyvault.keys import KeyClient
 from azure.identity import DefaultAzureCredential
-from azure.core.exceptions import HttpResponseError
+from azure.keyvault.keys import KeyClient
 
 # ----------------------------------------------------------------------------------------------------------
 # Prerequisites:
-# 1. An Azure Key Vault (https://docs.microsoft.com/en-us/azure/key-vault/quick-create-cli)
+# 1. An Azure Key Vault (https://docs.microsoft.com/azure/key-vault/quick-create-cli)
 #
 # 2. azure-keyvault-keys and azure-identity libraries (pip install these)
 #
-# 3. Set Environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, VAULT_URL
+# 3. Set environment variable VAULT_URL with the URL of your key vault
+#    
+# 4. Set up your environment to use azure-identity's DefaultAzureCredential. To authenticate a service principal with
+#    environment variables, set AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID
 #    (See https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys#authenticate-the-client)
 #
+# 5. Key create, get, update, and delete permissions for your service principal in your vault
+#
 # ----------------------------------------------------------------------------------------------------------
 # Sample - demonstrates the basic CRUD operations on a vault(key) resource for Azure Key Vault
 #
@@ -32,9 +36,7 @@
 # ----------------------------------------------------------------------------------------------------------
 
 # Instantiate a key client that will be used to call the service.
-# Notice that the client is using default Azure credentials.
-# To make default credentials work, ensure that environment variables 'AZURE_CLIENT_ID',
-# 'AZURE_CLIENT_SECRET' and 'AZURE_TENANT_ID' are set with the service principal credentials.
+# Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
 VAULT_URL = os.environ["VAULT_URL"]
 credential = DefaultAzureCredential()
 client = KeyClient(vault_url=VAULT_URL, credential=credential)

sdk/keyvault/azure-keyvault-keys/samples/hello_world_async.py

@@ -2,22 +2,26 @@
 # Copyright (c) Microsoft Corporation.
 # Licensed under the MIT License.
 # ------------------------------------
-import datetime
 import asyncio
+import datetime
 import os
-from azure.keyvault.keys.aio import KeyClient
 from azure.identity.aio import DefaultAzureCredential
-from azure.core.exceptions import HttpResponseError
+from azure.keyvault.keys.aio import KeyClient
 
 # ----------------------------------------------------------------------------------------------------------
 # Prerequisites:
-# 1. An Azure Key Vault (https://docs.microsoft.com/en-us/azure/key-vault/quick-create-cli)
+# 1. An Azure Key Vault (https://docs.microsoft.com/azure/key-vault/quick-create-cli)
 #
 # 2. azure-keyvault-keys and azure-identity libraries (pip install these)
 #
-# 3. Set Environment variables AZURE_CLIENT_ID, AZURE_TENANT_ID, AZURE_CLIENT_SECRET, VAULT_URL
+# 3. Set environment variable VAULT_URL with the URL of your key vault
+#
+# 4. Set up your environment to use azure-identity's DefaultAzureCredential. To authenticate a service principal with
+#    environment variables, set AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID
 #    (See https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys#authenticate-the-client)
 #
+# 5. Key create, get, update, and delete permissions for your service principal in your vault
+#
 # ----------------------------------------------------------------------------------------------------------
 # Sample - demonstrates the basic CRUD operations on a vault(key) resource for Azure Key Vault
 #
@@ -31,11 +35,10 @@
 #
 # 5. Delete a key (delete_key)
 # ----------------------------------------------------------------------------------------------------------
+
 async def run_sample():
     # Instantiate a key client that will be used to call the service.
-    # Notice that the client is using default Azure credentials.
-    # To make default credentials work, ensure that environment variables 'AZURE_CLIENT_ID',
-    # 'AZURE_CLIENT_SECRET' and 'AZURE_TENANT_ID' are set with the service principal credentials.
+    # Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
     VAULT_URL = os.environ["VAULT_URL"]
     credential = DefaultAzureCredential()
     client = KeyClient(vault_url=VAULT_URL, credential=credential)

sdk/keyvault/azure-keyvault-keys/samples/key_rotation.py

@@ -0,0 +1,79 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+import os
+from azure.identity import DefaultAzureCredential
+from azure.keyvault.keys import KeyClient, KeyRotationLifetimeAction, KeyRotationPolicyAction
+
+# ----------------------------------------------------------------------------------------------------------
+# Prerequisites:
+# 1. An Azure Key Vault (https://docs.microsoft.com/azure/key-vault/quick-create-cli)
+#
+# 2. azure-keyvault-keys and azure-identity libraries (pip install these)
+#
+# 3. Set environment variable VAULT_URL with the URL of your key vault
+#    
+# 4. Set up your environment to use azure-identity's DefaultAzureCredential. To authenticate a service principal with
+#    environment variables, set AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID
+#    (See https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys#authenticate-the-client)
+#
+# 5. Key rotation permissions for your service principal in your vault
+#
+# ----------------------------------------------------------------------------------------------------------
+# Sample - creates and updates a key's automated rotation policy, and rotates a key on-demand
+#
+# 1. Create a new key rotation policy (update_key_rotation_policy)
+#
+# 2. Get a key's current rotation policy (get_key_rotation_policy)
+#
+# 3. Update a key's rotation policy (update_key_rotation_policy)
+#
+# 4. Rotate a key on-demand (rotate_key)
+#
+# 5. Delete a key (begin_delete_key)
+# ----------------------------------------------------------------------------------------------------------
+
+# Instantiate a key client that will be used to call the service.
+# Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
+VAULT_URL = os.environ["VAULT_URL"]
+credential = DefaultAzureCredential()
+client = KeyClient(vault_url=VAULT_URL, credential=credential)
+
+# First, create a key
+key_name = "rotation-sample-key"
+key = client.create_rsa_key(key_name)
+print("\nCreated a key; new version is {}".format(key.properties.version))
+
+# Set the key's automated rotation policy to rotate the key two months after the key was created
+actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_after_create="P2M")]
+updated_policy = client.update_key_rotation_policy(key_name, lifetime_actions=actions)
+
+# The created policy should only have one action
+assert len(updated_policy.lifetime_actions) == 1, "There should be exactly one rotation policy action"
+policy_action = updated_policy.lifetime_actions[0]
+print("\nCreated a new key rotation policy: {} after {}".format(policy_action.action, policy_action.time_after_create))
+
+# Get the key's current rotation policy
+current_policy = client.get_key_rotation_policy(key_name)
+policy_action = current_policy.lifetime_actions[0]
+print("\nCurrent rotation policy: {} after {}".format(policy_action.action, policy_action.time_after_create))
+
+# Update the key's automated rotation policy to notify 30 days before the key expires
+new_actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.NOTIFY, time_before_expiry="P30D")]
+# You may also specify the duration after which the newly rotated key will expire
+# In this example, any new key versions will expire after 90 days
+new_policy = client.update_key_rotation_policy(key_name, expires_in="P90D", lifetime_actions=new_actions)
+
+# The updated policy should only have one action
+assert len(new_policy.lifetime_actions) == 1, "There should be exactly one rotation policy action"
+policy_action = new_policy.lifetime_actions[0]
+print("\nUpdated rotation policy: {} {} before expiry".format(policy_action.action, policy_action.time_before_expiry))
+
+# Finally, you can rotate a key on-demand by creating a new version of the key
+rotated_key = client.rotate_key(key_name)
+print("\nRotated the key on-demand; new version is {}".format(rotated_key.properties.version))
+
+# To clean up, delete the key
+client.begin_delete_key(key_name)
+print("\nDeleted the key")

sdk/keyvault/azure-keyvault-keys/samples/key_rotation_async.py

@@ -0,0 +1,95 @@
+# ------------------------------------
+# Copyright (c) Microsoft Corporation.
+# Licensed under the MIT License.
+# ------------------------------------
+import asyncio
+import os
+from azure.identity.aio import DefaultAzureCredential
+from azure.keyvault.keys import KeyRotationLifetimeAction, KeyRotationPolicyAction
+from azure.keyvault.keys.aio import KeyClient
+
+# ----------------------------------------------------------------------------------------------------------
+# Prerequisites:
+# 1. An Azure Key Vault (https://docs.microsoft.com/azure/key-vault/quick-create-cli)
+#
+# 2. azure-keyvault-keys and azure-identity libraries (pip install these)
+#
+# 3. Set environment variable VAULT_URL with the URL of your key vault
+#
+# 4. Set up your environment to use azure-identity's DefaultAzureCredential. To authenticate a service principal with
+#    environment variables, set AZURE_CLIENT_ID, AZURE_CLIENT_SECRET, and AZURE_TENANT_ID
+#    (See https://github.com/Azure/azure-sdk-for-python/tree/main/sdk/keyvault/azure-keyvault-keys#authenticate-the-client)
+#
+# 5. Key rotation permissions for your service principal in your vault
+#
+# ----------------------------------------------------------------------------------------------------------
+# Sample - creates and updates a key's automated rotation policy, and rotates a key on-demand
+#
+# 1. Create a new key rotation policy (update_key_rotation_policy)
+#
+# 2. Get a key's current rotation policy (get_key_rotation_policy)
+#
+# 3. Update a key's rotation policy (update_key_rotation_policy)
+#
+# 4. Rotate a key on-demand (rotate_key)
+#
+# 5. Delete a key (delete_key)
+# ----------------------------------------------------------------------------------------------------------
+
+async def run_sample():
+    # Instantiate a key client that will be used to call the service.
+    # Here we use the DefaultAzureCredential, but any azure-identity credential can be used.
+    VAULT_URL = os.environ["VAULT_URL"]
+    credential = DefaultAzureCredential()
+    client = KeyClient(vault_url=VAULT_URL, credential=credential)
+
+    # First, create a key
+    key_name = "rotation-sample-key"
+    key = await client.create_rsa_key(key_name)
+    print("\nCreated a key; new version is {}".format(key.properties.version))
+
+    # Set the key's automated rotation policy to rotate the key two months after the key was created
+    actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.ROTATE, time_after_create="P2M")]
+    updated_policy = await client.update_key_rotation_policy(key_name, lifetime_actions=actions)
+
+    # The created policy should only have one action
+    assert len(updated_policy.lifetime_actions) == 1, "There should be exactly one rotation policy action"
+    policy_action = updated_policy.lifetime_actions[0]
+    print(
+        "\nCreated a new key rotation policy: {} after {}".format(policy_action.action, policy_action.time_after_create)
+    )
+
+    # Get the key's current rotation policy
+    current_policy = await client.get_key_rotation_policy(key_name)
+    policy_action = current_policy.lifetime_actions[0]
+    print("\nCurrent rotation policy: {} after {}".format(policy_action.action, policy_action.time_after_create))
+
+    # Update the key's automated rotation policy to notify 30 days before the key expires
+    new_actions = [KeyRotationLifetimeAction(KeyRotationPolicyAction.NOTIFY, time_before_expiry="P30D")]
+    # You may also specify the duration after which the newly rotated key will expire
+    # In this example, any new key versions will expire after 90 days
+    new_policy = await client.update_key_rotation_policy(key_name, expires_in="P90D", lifetime_actions=new_actions)
+
+    # The updated policy should only have one action
+    assert len(new_policy.lifetime_actions) == 1, "There should be exactly one rotation policy action"
+    policy_action = new_policy.lifetime_actions[0]
+    print(
+        "\nUpdated rotation policy: {} {} before expiry".format(policy_action.action, policy_action.time_before_expiry)
+    )
+
+    # Finally, you can rotate a key on-demand by creating a new version of the key
+    rotated_key = await client.rotate_key(key_name)
+    print("\nRotated the key on-demand; new version is {}".format(rotated_key.properties.version))
+
+    # To clean up, delete the key
+    await client.delete_key(key_name)
+    print("\nDeleted the key")
+
+    await credential.close()
+    await client.close()
+
+
+if __name__ == "__main__":
+    loop = asyncio.get_event_loop()
+    loop.run_until_complete(run_sample())
+    loop.close()