com.azure.security.keyvault.administration.package-info Maven / Gradle / Ivy
Show all versions of azure-security-keyvault-administration Show documentation
// Copyright (c) Microsoft Corporation. All rights reserved.
// Licensed under the MIT License.
/**
* Azure Key Vault Managed HSM is a
* fully-managed, highly-available, single-tenant, standards-compliant cloud service that enables you to safeguard
* cryptographic keys for your cloud applications using FIPS 140-2 Level 3 validated HSMs.
*
*
* The Azure Key Vault Administration client library allows developers to interact with the Azure Key Vault Managed
* HSM service from their applications. The library provides a set of APIs that enable developers to perform
* administrative tasks such as full backup/restore, key-level role-based access control (RBAC), and account settings
* management.
*
*
* Key Concepts:
*
*
* What is a Key Vault Access Control Client?
*
* The Key Vault Access Control client performs the interactions with the Azure Key Vault service for getting,
* setting, deleting, and listing role assignments, as well as listing role definitions. Asynchronous
* (KeyVaultAccessControlAsyncClient) and synchronous (KeyVaultAccessControlClient) clients exist in the SDK allowing
* for the selection of a client based on an application's use case. Once you've initialized a role assignment, you can
* interact with the primary resource types in Key Vault.
*
*
* What is a Role Definition?
*
* A role definition is a collection of permissions. It defines the operations that can be performed, such as read,
* write, and delete. It can also define the operations that are excluded from allowed operations.
*
*
* Role definitions can be listed and specified as part of a role assignment.
*
*
* What is a Role Assignment?
*
* A role assignment is the association of a role definition to a service principal. They can be created, listed,
* fetched individually, and deleted.
*
*
* What is a Key Vault Backup Client
*
* The Key Vault Backup Client provides both synchronous and asynchronous operations for performing full key backups,
* full key restores, and selective key restores. Asynchronous (KeyVaultBackupAsyncClient) and synchronous
* (KeyVaultBackupClient) clients exist in the SDK allowing for the selection of a client based on an application's use
* case.
*
*
* NOTE: The backing store for key backups is a blob storage container using Shared Access Signature
* authentication. For more details on creating a SAS token using the BlobServiceClient, see the Azure
* Storage Blobs client README. Alternatively, it is possible to
* generate a SAS token in Storage Explorer.
*
*
* What is a Backup Operation?
*
* A backup operation represents a long-running operation for a full key backup.
*
*
* What is a Restore Operation
*
* A restore operation represents a long-running operation for both a full key and selective key restore.
*
*
* What is a Key Vault Settings Client?
*
* The Key Vault Settings client allows manipulation of an Azure Key Vault account's settings, with operations
* such as: getting, updating, and listing. Asynchronous (KeyVaultSettingsAsyncClient) and synchronous
* (KeyVaultSettingsClient) clients exist in the SDK allowing for the selection of a client based on an application's
* use case.
*
*
Getting Started
*
* In order to interact with the Azure Key Vault service, you will need to create an instance of the {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient} class, a vault url and a credential
* object.
*
*
* The examples shown in this document use a credential object named DefaultAzureCredential for authentication, which
* is appropriate for most scenarios, including local development and production environments. Additionally, we
* recommend using a
* managed identity for authentication in production environments. You can find more information on different ways
* of authenticating and their corresponding credential types in the Azure Identity
* documentation".
*
*
* Sample: Construct Synchronous Access Control Client
*
*
* The following code sample demonstrates the creation of a {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClient}, using the {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClientBuilder} to configure it.
*
*
* KeyVaultAccessControlClient keyVaultAccessControlClient = new KeyVaultAccessControlClientBuilder()
* .vaultUrl("<your-managed-hsm-url>")
* .credential(new DefaultAzureCredentialBuilder().build())
* .buildClient();
*
*
*
*
* Sample: Construct Asynchronous Access Control Client
*
*
* The following code sample demonstrates the creation of a {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient}, using the {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClientBuilder} to configure it.
*
*
* KeyVaultAccessControlAsyncClient keyVaultAccessControlAsyncClient = new KeyVaultAccessControlClientBuilder()
* .vaultUrl("<your-managed-hsm-url>")
* .credential(new DefaultAzureCredentialBuilder().build())
* .buildAsyncClient();
*
*
*
*
*
* Set a Role Definition
*
* The {@link com.azure.security.keyvault.administration.KeyVaultAccessControlClient} can be used to set a role
* definition in the key vault.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to asynchronously create a role definition in the key vault, using the
* {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClient#setRoleDefinition(com.azure.security.keyvault.administration.models.KeyVaultRoleScope,
* java.lang.String) KeyVaultAccessControlClient.setRoleDefinition(KeyVaultRoleScope, String)} API.
*
*
* KeyVaultRoleDefinition roleDefinition = keyVaultAccessControlClient.setRoleDefinition(KeyVaultRoleScope.GLOBAL);
*
* System.out.printf("Created role definition with randomly generated name '%s' and role name '%s'.%n",
* roleDefinition.getName(), roleDefinition.getRoleName());
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient}.
*
*
* Get a Role Definition
*
* The {@link com.azure.security.keyvault.administration.KeyVaultAccessControlClient} can be used to retrieve a role
* definition from the key vault.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to asynchronously retrieve a role definition from the key vault, using
* the {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClient#getRoleDefinition(com.azure.security.keyvault.administration.models.KeyVaultRoleScope,
* java.lang.String) KeyVaultAccessControlClient.getRoleDefinition(KeyVaultRoleScope, String)} API.
*
*
* String roleDefinitionName = "de8df120-987e-4477-b9cc-570fd219a62c";
* KeyVaultRoleDefinition roleDefinition =
* keyVaultAccessControlClient.getRoleDefinition(KeyVaultRoleScope.GLOBAL, roleDefinitionName);
*
* System.out.printf("Retrieved role definition with name '%s' and role name '%s'.%n", roleDefinition.getName(),
* roleDefinition.getRoleName());
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient}.
*
*
* Delete a Role Definition
*
* The {@link com.azure.security.keyvault.administration.KeyVaultAccessControlClient} can be used to delete a role
* definition from the key vault.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to asynchronously delete a role definition from the key vault, using
* the {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClient#deleteRoleDefinition(com.azure.security.keyvault.administration.models.KeyVaultRoleScope,
* java.lang.String) KeyVaultAccessControlClient.deleteRoleDefinition(KeyVaultRoleScope, String)} API.
*
*
* String roleDefinitionName = "6a709e6e-8964-4012-a99b-6b0131e8ce40";
*
* keyVaultAccessControlClient.deleteRoleDefinition(KeyVaultRoleScope.GLOBAL, roleDefinitionName);
*
* System.out.printf("Deleted role definition with name '%s'.%n", roleDefinitionName);
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient}.
*
*
* Create a Role Assignment
*
* The {@link com.azure.security.keyvault.administration.KeyVaultAccessControlClient} can be used to set a role
* assignment in the key vault.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to asynchronously create a role assignment in the key vault, using the
* {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClient#createRoleAssignment(com.azure.security.keyvault.administration.models.KeyVaultRoleScope,
* java.lang.String, java.lang.String) KeyVaultAccessControlClient.createRoleAssignment(KeyVaultRoleScope, String,
* String)} API.
*
*
* String roleDefinitionId = "b0b43a39-920c-475b-b34c-32ecc2bbb0ea";
* String servicePrincipalId = "169d6a86-61b3-4615-ac7e-2da09edfeed4";
* KeyVaultRoleAssignment roleAssignment =
* keyVaultAccessControlClient.createRoleAssignment(KeyVaultRoleScope.GLOBAL, roleDefinitionId,
* servicePrincipalId);
*
* System.out.printf("Created role assignment with randomly generated name '%s' for principal with id '%s'.%n",
* roleAssignment.getName(), roleAssignment.getProperties().getPrincipalId());
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient}.
*
*
* Get a Role Definition
*
* The {@link com.azure.security.keyvault.administration.KeyVaultAccessControlClient} can be used to retrieve a role
* definition from the key vault.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to asynchronously retrieve a role definition from the key vault, using
* the {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClient#getRoleDefinition(com.azure.security.keyvault.administration.models.KeyVaultRoleScope,
* java.lang.String) KeyVaultAccessControlClient.getRoleDefinition(KeyVaultRoleScope, String)} API.
*
*
* String roleAssignmentName = "06d1ae8b-0791-4f02-b976-f631251f5a95";
* KeyVaultRoleAssignment roleAssignment =
* keyVaultAccessControlClient.getRoleAssignment(KeyVaultRoleScope.GLOBAL, roleAssignmentName);
*
* System.out.printf("Retrieved role assignment with name '%s'.%n", roleAssignment.getName());
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient}.
*
*
* Delete a Role Definition
*
* The {@link com.azure.security.keyvault.administration.KeyVaultAccessControlClient} can be used to delete a role
* definition from an Azure Key Vault account.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to asynchronously delete a role definition from the key vault, using
* the {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlClient#deleteRoleDefinition(com.azure.security.keyvault.administration.models.KeyVaultRoleScope,
* java.lang.String) KeyVaultAccessControlClient.deleteRoleDefinition(KeyVaultRoleScope, String)} API.
*
*
* String roleAssignmentName = "c3ed874a-64a9-4a87-8581-2a1ad84b9ddb";
*
* keyVaultAccessControlClient.deleteRoleAssignment(KeyVaultRoleScope.GLOBAL, roleAssignmentName);
*
* System.out.printf("Deleted role assignment with name '%s'.%n", roleAssignmentName);
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient}.
*
*
* Back Up a Collection of Keys
*
* The {@link com.azure.security.keyvault.administration.KeyVaultBackupClient} can be used to back up the entire
* collection of keys from a key vault.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to synchronously back up an entire collection of keys using, using the
* {@link com.azure.security.keyvault.administration.KeyVaultBackupClient#beginBackup(String, String)} API.
*
*
* String blobStorageUrl = "https://myaccount.blob.core.windows.net/myContainer";
* String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z"
* + "&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
*
* SyncPoller<KeyVaultBackupOperation, String> backupPoller = client.beginBackup(blobStorageUrl, sasToken);
*
* PollResponse<KeyVaultBackupOperation> pollResponse = backupPoller.poll();
*
* System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
*
* PollResponse<KeyVaultBackupOperation> finalPollResponse = backupPoller.waitForCompletion();
*
* if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
* String folderUrl = backupPoller.getFinalResult();
*
* System.out.printf("Backup completed. The storage location of this backup is: %s.%n", folderUrl);
* } else {
* KeyVaultBackupOperation operation = backupPoller.poll().getValue();
*
* System.out.printf("Backup failed with error: %s.%n", operation.getError().getMessage());
* }
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultBackupAsyncClient}.
*
*
* Restore a Collection of Keys
*
* The {@link com.azure.security.keyvault.administration.KeyVaultBackupClient} can be used to restore an entire
* collection of keys from a backup.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to synchronously restore an entire collection of keys from a backup,
* using the {@link com.azure.security.keyvault.administration.KeyVaultBackupClient#beginRestore(String, String)} API.
*
*
* String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
* String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z"
* + "&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
*
* SyncPoller<KeyVaultRestoreOperation, KeyVaultRestoreResult> backupPoller =
* client.beginRestore(folderUrl, sasToken);
*
* PollResponse<KeyVaultRestoreOperation> pollResponse = backupPoller.poll();
*
* System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
*
* PollResponse<KeyVaultRestoreOperation> finalPollResponse = backupPoller.waitForCompletion();
*
* if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
* System.out.printf("Backup restored successfully.%n");
* } else {
* KeyVaultRestoreOperation operation = backupPoller.poll().getValue();
*
* System.out.printf("Restore failed with error: %s.%n", operation.getError().getMessage());
* }
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultBackupAsyncClient}.
*
*
* Selectively Restore a Key
*
* The {@link com.azure.security.keyvault.administration.KeyVaultBackupClient} can be used to restore a specific key
* from a backup.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to synchronously restore a specific key from a backup, using the {@link
* com.azure.security.keyvault.administration.KeyVaultBackupClient#beginSelectiveKeyRestore(String, String, String)}
* API.
*
*
* String folderUrl = "https://myaccount.blob.core.windows.net/myContainer/mhsm-myaccount-2020090117323313";
* String sasToken = "sv=2020-02-10&ss=b&srt=o&sp=rwdlactfx&se=2021-06-17T07:13:07Z&st=2021-06-16T23:13:07Z"
* "&spr=https&sig=n5V6fnlkViEF9b7ij%2FttTHNwO2BdFIHKHppRxGAyJdc%3D";
* String keyName = "myKey";
*
* SyncPoller<KeyVaultSelectiveKeyRestoreOperation, KeyVaultSelectiveKeyRestoreResult> backupPoller =
* client.beginSelectiveKeyRestore(folderUrl, sasToken, keyName);
*
* PollResponse<KeyVaultSelectiveKeyRestoreOperation> pollResponse = backupPoller.poll();
*
* System.out.printf("The current status of the operation is: %s.%n", pollResponse.getStatus());
*
* PollResponse<KeyVaultSelectiveKeyRestoreOperation> finalPollResponse = backupPoller.waitForCompletion();
*
* if (finalPollResponse.getStatus() == LongRunningOperationStatus.SUCCESSFULLY_COMPLETED) {
* System.out.printf("Key restored successfully.%n");
* } else {
* KeyVaultSelectiveKeyRestoreOperation operation = backupPoller.poll().getValue();
*
* System.out.printf("Key restore failed with error: %s.%n", operation.getError().getMessage());
* }
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultBackupAsyncClient}.
*
*
* Get All Settings
*
* The {@link com.azure.security.keyvault.administration.KeyVaultSettingsClient} can be used to list all the settings
* for an Azure Key Vault account.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to synchronously back up an entire collection of keys using, using the
* {@link com.azure.security.keyvault.administration.KeyVaultSettingsClient#getSettings()} API.
*
*
* KeyVaultGetSettingsResult getSettingsResult = keyVaultSettingsClient.getSettings();
* List<KeyVaultSetting> settings = getSettingsResult.getSettings();
*
* settings.forEach(setting ->
* System.out.printf("Retrieved setting with name '%s' and value %s'.%n", setting.getName(),
* setting.asBoolean()));
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultSettingsAsyncClient}.
*
*
* Retrieve a Specific Setting
*
* The {@link com.azure.security.keyvault.administration.KeyVaultSettingsClient} can be used to retrieve a specific
* setting.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to synchronously restore an entire collection of keys from a backup,
* using the {@link com.azure.security.keyvault.administration.KeyVaultSettingsClient#getSetting(String)} API.
*
*
* KeyVaultSetting setting = keyVaultSettingsClient.getSetting(settingName);
*
* System.out.printf("Retrieved setting '%s' with value '%s'.%n", setting.getName(), setting.asBoolean());
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultSettingsAsyncClient}.
*
*
* Update a Specific Setting
*
* The {@link com.azure.security.keyvault.administration.KeyVaultSettingsClient} can be used to restore a specific key
* from a backup.
*
*
* Code Sample:
*
*
* The following code sample demonstrates how to synchronously restore a specific key from a backup, using the {@link
* com.azure.security.keyvault.administration.KeyVaultSettingsClient#updateSetting(com.azure.security.keyvault.administration.models.KeyVaultSetting)
* KeyVaultSettingsClient.updateSetting(KeyVaultSetting)}
*
*
* KeyVaultSetting settingToUpdate = new KeyVaultSetting(settingName, true);
* KeyVaultSetting updatedSetting = keyVaultSettingsClient.updateSetting(settingToUpdate);
*
* System.out.printf("Updated setting '%s' to '%s'.%n", updatedSetting.getName(), updatedSetting.asBoolean());
*
*
*
*
* Note: For the asynchronous sample, refer to {@link
* com.azure.security.keyvault.administration.KeyVaultSettingsAsyncClient}.
*
*
* @see com.azure.security.keyvault.administration.KeyVaultAccessControlClient
* @see com.azure.security.keyvault.administration.KeyVaultAccessControlAsyncClient
* @see com.azure.security.keyvault.administration.KeyVaultAccessControlClientBuilder
* @see com.azure.security.keyvault.administration.KeyVaultBackupClient
* @see com.azure.security.keyvault.administration.KeyVaultBackupAsyncClient
* @see com.azure.security.keyvault.administration.KeyVaultBackupClientBuilder
* @see com.azure.security.keyvault.administration.KeyVaultSettingsClient
* @see com.azure.security.keyvault.administration.KeyVaultSettingsAsyncClient
* @see com.azure.security.keyvault.administration.KeyVaultSettingsClientBuilder
*/
package com.azure.security.keyvault.administration;