Package com.azure.security.keyvault.administration

Class KeyVaultAccessControlClient

java.lang.Object
com.azure.security.keyvault.administration.KeyVaultAccessControlClient
public final class KeyVaultAccessControlClient extends Object
The KeyVaultAccessControlClient provides synchronous methods to view and manage Role Based Access for the Azure Key Vault. The client supports creating, listing, updating, and deleting role definitions and role assignments.

Instances of this client are obtained by calling the KeyVaultAccessControlClientBuilder.buildClient() method on a KeyVaultAccessControlClientBuilder object.

Samples to construct a sync client

 KeyVaultAccessControlClient keyVaultAccessControlClient = new KeyVaultAccessControlClientBuilder()
     .vaultUrl("<your-managed-hsm-url>")
     .credential(new DefaultAzureCredentialBuilder().build())
     .buildClient();
See Also:

  • Method Details

    • getVaultUrl

      public String getVaultUrl()
      Gets the URL for the Key Vault this client is associated with.
      Returns:
      The Key Vault URL.

    • listRoleDefinitions

      public com.azure.core.http.rest.PagedIterable<KeyVaultRoleDefinition> listRoleDefinitions(KeyVaultRoleScope roleScope)
      Get all role definitions that are applicable at the given role scope and above.

      Code Samples

      Lists all role definitions. Prints out the details of the retrieved role definitions.

       PagedIterable<KeyVaultRoleDefinition> roleDefinitions =
     keyVaultAccessControlClient.listRoleDefinitions(KeyVaultRoleScope.GLOBAL);

 roleDefinitions.forEach(roleDefinition ->
     System.out.printf("Retrieved role definition with name '%s'.%n", roleDefinition.getName()));
      Parameters:
      roleScope - The roleScope of the role definitions.
      Returns:
      A PagedIterable containing the role definitions for the given roleScope.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the roleScope is null.

    • listRoleDefinitions

      public com.azure.core.http.rest.PagedIterable<KeyVaultRoleDefinition> listRoleDefinitions(KeyVaultRoleScope roleScope, com.azure.core.util.Context context)
      Get all role definitions that are applicable at the given role scope and above.

      Code Samples

      Lists all role definitions. Prints out the details of the retrieved role definitions.

       PagedIterable<KeyVaultRoleDefinition> keyVaultRoleDefinitions =
     keyVaultAccessControlClient.listRoleDefinitions(KeyVaultRoleScope.GLOBAL, new Context("key1", "value1"));

 keyVaultRoleDefinitions.forEach(roleDefinition ->
     System.out.printf("Retrieved role definition with name '%s'.%n", roleDefinition.getName()));
      Parameters:
      roleScope - The scope of the role definitions.
      context - Additional Context that is passed through the HTTP pipeline during the service call.
      Returns:
      A PagedIterable containing the role definitions for the given roleScope.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the roleScope is null.

    • setRoleDefinition

      public KeyVaultRoleDefinition setRoleDefinition(KeyVaultRoleScope roleScope)
      Creates a role definition with a randomly generated name.

      Code Samples

      Creates a role definition with a randomly generated name. Prints out the details of the created role definition.

       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());
      Parameters:
      roleScope - The role scope of the role definition. Managed HSM only supports '/'.
      Returns:
      The created role definition.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the role scope is null.

    • setRoleDefinition

      public KeyVaultRoleDefinition setRoleDefinition(KeyVaultRoleScope roleScope, String roleDefinitionName)
      Creates or updates a role definition with a given name. If no name is provided, then a role definition will be created with a randomly generated name.

      Code Samples

      Creates or updates a role definition with a given generated name. Prints out the details of the created role definition.

       String myRoleDefinitionName = "b67c3cf4-cbfd-451e-89ab-97c01906a2e0";
 KeyVaultRoleDefinition myRoleDefinition =
     keyVaultAccessControlClient.setRoleDefinition(KeyVaultRoleScope.GLOBAL, myRoleDefinitionName);

 System.out.printf("Set role definition with name '%s' and role name '%s'.%n", myRoleDefinition.getName(),
     myRoleDefinition.getRoleName());
      Parameters:
      roleScope - The role scope of the role definition. Managed HSM only supports '/'.
      roleDefinitionName - The name of the role definition. It can be any valid UUID. If null is provided, a name will be randomly generated.
      Returns:
      The created or updated role definition.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the role scope or roleDefinitionName are null.

    • setRoleDefinitionWithResponse

      public com.azure.core.http.rest.Response<KeyVaultRoleDefinition> setRoleDefinitionWithResponse(SetRoleDefinitionOptions options, com.azure.core.util.Context context)
      Creates or updates a role definition.

      Code Samples

      Creates or updates a role definition. Prints out the details of the HTTP response and the created role definition.

       String roleDefinitionName = "a86990e4-2080-4666-bd36-6e1664d3706f";

 List<KeyVaultRoleScope> assignableScopes = new ArrayList<>();
 assignableScopes.add(KeyVaultRoleScope.GLOBAL);
 assignableScopes.add(KeyVaultRoleScope.KEYS);

 List<KeyVaultDataAction> dataActions = new ArrayList<>();
 dataActions.add(KeyVaultDataAction.START_HSM_RESTORE);
 dataActions.add(KeyVaultDataAction.START_HSM_BACKUP);
 dataActions.add(KeyVaultDataAction.READ_HSM_BACKUP_STATUS);
 dataActions.add(KeyVaultDataAction.READ_HSM_RESTORE_STATUS);
 dataActions.add(KeyVaultDataAction.BACKUP_HSM_KEYS);
 dataActions.add(KeyVaultDataAction.RESTORE_HSM_KEYS);

 List<KeyVaultPermission> permissions = new ArrayList<>();
 permissions.add(new KeyVaultPermission(null, null, dataActions, null));

 SetRoleDefinitionOptions setRoleDefinitionOptions =
     new SetRoleDefinitionOptions(KeyVaultRoleScope.GLOBAL, roleDefinitionName)
         .setRoleName("Backup and Restore Role Definition")
         .setDescription("Can backup and restore a whole Managed HSM, as well as individual keys.")
         .setAssignableScopes(assignableScopes)
         .setPermissions(permissions);

 Response<KeyVaultRoleDefinition> response =
     keyVaultAccessControlClient.setRoleDefinitionWithResponse(setRoleDefinitionOptions,
         new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Role definition with name '%s' and role name '%s' "
     + "was set.%n", response.getStatusCode(), response.getValue().getName(), response.getValue().getRoleName());
      Parameters:
      options - Object representing the configurable options to create or update a role definition.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A Response whose value contains the created or updated role definition.
      Throws:
      KeyVaultAdministrationException - If any parameter in options is invalid.
      NullPointerException - If the role scope or roleDefinitionName in the options object are null.

    • getRoleDefinition

      public KeyVaultRoleDefinition getRoleDefinition(KeyVaultRoleScope roleScope, String roleDefinitionName)
      Gets a role definition.

      Code Samples

      Gets a role definition. Prints out the details of the retrieved role definition.

       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());
      Parameters:
      roleScope - The role scope of the role definition.
      roleDefinitionName - The name used of the role definition.
      Returns:
      The retrieved role definition.
      Throws:
      KeyVaultAdministrationException - If a role definition with the given name cannot be found or if the given roleScope is invalid.
      NullPointerException - If the role scope or roleDefinitionName are null.

    • getRoleDefinitionWithResponse

      public com.azure.core.http.rest.Response<KeyVaultRoleDefinition> getRoleDefinitionWithResponse(KeyVaultRoleScope roleScope, String roleDefinitionName, com.azure.core.util.Context context)
      Gets a role definition.

      Code Samples

      Gets a role definition. Prints out the details of the HTTP response and the retrieved role definition.

       String myRoleDefinitionName = "cb15ef18-b32c-4224-b048-3a91cd68acc3";
 Response<KeyVaultRoleDefinition> response =
     keyVaultAccessControlClient.getRoleDefinitionWithResponse(KeyVaultRoleScope.GLOBAL, myRoleDefinitionName,
         new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Role definition with name '%s' and role name '%s'"
     + " was retrieved.%n", response.getStatusCode(), response.getValue().getName(),
     response.getValue().getRoleName());
      Parameters:
      roleScope - The role scope of the role definition.
      roleDefinitionName - The name of the role definition.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A Response whose value contains the retrieved role definition.
      Throws:
      KeyVaultAdministrationException - If a role definition with the given name cannot be found or if the given roleScope is invalid.
      NullPointerException - If the role scope or roleDefinitionName are null.

    • deleteRoleDefinition

      public void deleteRoleDefinition(KeyVaultRoleScope roleScope, String roleDefinitionName)
      Deletes a role definition.

      Code Samples

      Deletes a role definition.

       String roleDefinitionName = "6a709e6e-8964-4012-a99b-6b0131e8ce40";

 keyVaultAccessControlClient.deleteRoleDefinition(KeyVaultRoleScope.GLOBAL, roleDefinitionName);

 System.out.printf("Deleted role definition with name '%s'.%n", roleDefinitionName);
      Parameters:
      roleScope - The role scope of the role definition. Managed HSM only supports '/'.
      roleDefinitionName - The name of the role definition.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the role scope or roleDefinitionName are null.

    • deleteRoleDefinitionWithResponse

      public com.azure.core.http.rest.Response<Void> deleteRoleDefinitionWithResponse(KeyVaultRoleScope roleScope, String roleDefinitionName, com.azure.core.util.Context context)
      Deletes a role definition.

      Code Samples

      Deletes a role definition. Prints out the details of the HTTP response.

       String myRoleDefinitionName = "6b2d0b58-4108-44d6-b7e0-4fd02f77fe7e";
 Response<Void> response =
     keyVaultAccessControlClient.deleteRoleDefinitionWithResponse(KeyVaultRoleScope.GLOBAL, myRoleDefinitionName,
         new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Role definition with name '%s' was deleted.%n",
     response.getStatusCode(), myRoleDefinitionName);
      Parameters:
      roleScope - The role scope of the role definition.
      roleDefinitionName - The name of the role definition.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A Response with a Void value.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the role scope or roleDefinitionName are null.

    • listRoleAssignments

      public com.azure.core.http.rest.PagedIterable<KeyVaultRoleAssignment> listRoleAssignments(KeyVaultRoleScope roleScope)
      Get all role assignments that are applicable at the given role scope and above.

      Code Samples

      Lists all role assignments. Prints out the details of the retrieved role assignments.

       PagedIterable<KeyVaultRoleAssignment> roleAssignments =
     keyVaultAccessControlClient.listRoleAssignments(KeyVaultRoleScope.GLOBAL);

 roleAssignments.forEach(roleAssignment ->
     System.out.printf("Retrieved role assignment with name '%s'.%n", roleAssignment.getName()));
      Parameters:
      roleScope - The scope of the role assignment.
      Returns:
      A PagedIterable containing the role assignments for the given roleScope.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the roleScope is null.

    • listRoleAssignments

      public com.azure.core.http.rest.PagedIterable<KeyVaultRoleAssignment> listRoleAssignments(KeyVaultRoleScope roleScope, com.azure.core.util.Context context)
      Get all role assignments that are applicable at the given role scope and above.

      Code Samples

      Lists all role assignments. Prints out the details of the retrieved role assignments.

       PagedIterable<KeyVaultRoleAssignment> keyVaultRoleAssignments =
     keyVaultAccessControlClient.listRoleAssignments(KeyVaultRoleScope.GLOBAL, new Context("key1", "value1"));

 keyVaultRoleAssignments.forEach(roleAssignment ->
     System.out.printf("Retrieved role assignment with name '%s'.%n", roleAssignment.getName()));
      Parameters:
      roleScope - The scope of the role assignment.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A PagedIterable containing the role assignments for the given roleScope.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the roleScope is null.

    • createRoleAssignment

      public KeyVaultRoleAssignment createRoleAssignment(KeyVaultRoleScope roleScope, String roleDefinitionId, String principalId)
      Creates a role assignment with a randomly generated name.

      Code Samples

      Creates a role assignment with a randomly generated name. Prints out the details of the created role assignment.

       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());
      Parameters:
      roleScope - The role scope of the role assignment to create.
      roleDefinitionId - The role definition ID for the role assignment.
      principalId - The principal ID assigned to the role. This maps to the ID inside the Active Directory.
      Returns:
      A Mono containing the created role assignment.
      Throws:
      KeyVaultAdministrationException - If the given roleScope, roleDefinitionId or principalId are invalid.
      NullPointerException - If the roleScope, roleDefinitionId or principalId are null.

    • createRoleAssignment

      public KeyVaultRoleAssignment createRoleAssignment(KeyVaultRoleScope roleScope, String roleDefinitionId, String principalId, String roleAssignmentName)
      Creates a role assignment.

      Code Samples

      Creates a role assignment. Prints out the details of the created role assignment.

       String myRoleDefinitionId = "c7d4f70f-944d-494a-a73e-ff62fe7f04da";
 String myServicePrincipalId = "4196fc8f-7312-46b9-9a08-05bf44fdff37";
 String myRoleAssignmentName = "d80e9366-47a6-4f42-ba84-f2eefb084972";
 KeyVaultRoleAssignment myRoleAssignment =
     keyVaultAccessControlClient.createRoleAssignment(KeyVaultRoleScope.GLOBAL, myRoleDefinitionId,
         myServicePrincipalId, myRoleAssignmentName);

 System.out.printf("Created role assignment with name '%s' for principal with id '%s'.%n",
     myRoleAssignment.getName(), myRoleAssignment.getProperties().getPrincipalId());
      Parameters:
      roleScope - The role scope of the role assignment to create.
      roleAssignmentName - The name used to create the role assignment. It can be any valid UUID.
      roleDefinitionId - The role definition ID for the role assignment.
      principalId - The principal ID assigned to the role. This maps to the ID inside the Active Directory.
      Returns:
      The created role assignment.
      Throws:
      KeyVaultAdministrationException - If a role assignment with the given name already exists or if the given roleScope, roleDefinitionId or principalId are invalid.
      NullPointerException - If the role scope, roleAssignmentName, roleDefinitionId or principalId are null.

    • createRoleAssignmentWithResponse

      public com.azure.core.http.rest.Response<KeyVaultRoleAssignment> createRoleAssignmentWithResponse(KeyVaultRoleScope roleScope, String roleDefinitionId, String principalId, String roleAssignmentName, com.azure.core.util.Context context)
      Creates a role assignment.

      Code Samples

      Creates a role assignment. Prints out details of the HTTP response and the created role assignment.

       String someRoleDefinitionId = "11385c39-5efa-4e5f-8748-055aa51d4d23";
 String someServicePrincipalId = "eab943f7-a204-4434-9681-ef2cc0c85b51";
 String someRoleAssignmentName = "4d95e0ea-4808-43a4-b7f9-d9e61dba7ea9";

 Response<KeyVaultRoleAssignment> response =
     keyVaultAccessControlClient.createRoleAssignmentWithResponse(KeyVaultRoleScope.GLOBAL, someRoleDefinitionId,
         someServicePrincipalId, someRoleAssignmentName, new Context("key1", "value1"));
 KeyVaultRoleAssignment createdRoleAssignment = response.getValue();

 System.out.printf("Response successful with status code: %d. Role assignment with name '%s' for principal with"
     + "id '%s' was created.%n", response.getStatusCode(), createdRoleAssignment.getName(),
     createdRoleAssignment.getProperties().getPrincipalId());
      Parameters:
      roleScope - The role scope of the role assignment to create.
      roleAssignmentName - The name used to create the role assignment. It can be any valid UUID.
      roleDefinitionId - The role definition ID for the role assignment.
      principalId - The principal ID assigned to the role. This maps to the ID inside the Active Directory.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A Mono containing a Response whose value contains the created role assignment.
      Throws:
      KeyVaultAdministrationException - If a role assignment with the given name already exists or if the given roleScope, roleDefinitionId or principalId are invalid.
      NullPointerException - If the role scope, roleAssignmentName, roleDefinitionId or principalId are null.

    • getRoleAssignment

      public KeyVaultRoleAssignment getRoleAssignment(KeyVaultRoleScope roleScope, String roleAssignmentName)
      Gets a role assignment.

      Code Samples

      Deletes a role assignment. Prints out details of the retrieved role assignment.

       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());
      Parameters:
      roleScope - The role scope of the role assignment.
      roleAssignmentName - The name of the role assignment.
      Returns:
      The role assignment.
      Throws:
      KeyVaultAdministrationException - If a role assignment with the given name cannot be found or if the given roleScope is invalid.
      NullPointerException - If the roleScope or roleAssignmentName are null.

    • getRoleAssignmentWithResponse

      public com.azure.core.http.rest.Response<KeyVaultRoleAssignment> getRoleAssignmentWithResponse(KeyVaultRoleScope roleScope, String roleAssignmentName, com.azure.core.util.Context context)
      Gets a role assignment.

      Code Samples

      Deletes a role assignment. Prints out details of the HTTP response and the retrieved role assignment.

       String myRoleAssignmentName = "b4a970d5-c581-4760-bba5-61d3d5aa24f9";
 Response<KeyVaultRoleAssignment> response =
     keyVaultAccessControlClient.getRoleAssignmentWithResponse(KeyVaultRoleScope.GLOBAL, myRoleAssignmentName,
         new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Role assignment with name '%s' was retrieved.%n",
     response.getStatusCode(), response.getValue().getName());
      Parameters:
      roleScope - The role scope of the role assignment.
      roleAssignmentName - The name of the role assignment.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      The role assignment.
      Throws:
      KeyVaultAdministrationException - If a role assignment with the given name cannot be found or if the given roleScope is invalid.
      NullPointerException - If the roleScope or roleAssignmentName are null.

    • deleteRoleAssignment

      public void deleteRoleAssignment(KeyVaultRoleScope roleScope, String roleAssignmentName)
      Deletes a role assignment.

      Code Samples

      Deletes a role assignment.

       String roleAssignmentName = "c3ed874a-64a9-4a87-8581-2a1ad84b9ddb";

 keyVaultAccessControlClient.deleteRoleAssignment(KeyVaultRoleScope.GLOBAL, roleAssignmentName);

 System.out.printf("Deleted role assignment with name '%s'.%n", roleAssignmentName);
      Parameters:
      roleScope - The role scope of the role assignment.
      roleAssignmentName - The name of the role assignment.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the roleScope or roleAssignmentName are null.

    • deleteRoleAssignmentWithResponse

      public com.azure.core.http.rest.Response<Void> deleteRoleAssignmentWithResponse(KeyVaultRoleScope roleScope, String roleAssignmentName, com.azure.core.util.Context context)
      Deletes a role assignment.

      Code Samples

      Deletes a role assignment. Prints out details of the HTTP response.

       String myRoleAssignmentName = "8ac293e1-1ac8-4a71-b254-7caf9f7c2646";
 Response<Void> response =
     keyVaultAccessControlClient.deleteRoleAssignmentWithResponse(KeyVaultRoleScope.GLOBAL, myRoleAssignmentName,
         new Context("key1", "value1"));

 System.out.printf("Response successful with status code: %d. Role assignment with name '%s' was deleted.%n",
     response.getStatusCode(), myRoleAssignmentName);
      Parameters:
      roleScope - The role scope of the role assignment.
      roleAssignmentName - The name of the role assignment.
      context - Additional context that is passed through the HTTP pipeline during the service call.
      Returns:
      A Response with a Void value.
      Throws:
      KeyVaultAdministrationException - If the given roleScope is invalid.
      NullPointerException - If the roleScope or roleAssignmentName are null.