Share via

KeyVaultAccessControlClient class

  • Reference
Package:
@azure/keyvault-admin

The KeyVaultAccessControlClient provides methods to manage access control and role assignments in any given Azure Key Vault instance. The client supports creating, retrieving and deleting roles.

Constructors

KeyVaultAccessControlClient(string, TokenCredential, AccessControlClientOptions)

Creates an instance of the KeyVaultAccessControlClient.

Example usage:

import { KeyVaultAccessControlClient } from "@azure/keyvault-admin";
import { DefaultAzureCredential } from "@azure/identity";

let vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();

let client = new KeyVaultAccessControlClient(vaultUrl, credentials);

Properties

vaultUrl

The base URL to the vault

Methods

createRoleAssignment(string, string, string, string, CreateRoleAssignmentOptions)

Creates a role assignment in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleDefinition = await client.listRoleDefinitions("/").next();
const principalId = "4871f6a6-374f-4b6b-8b0c-f5d84db823f6";
const result = await client.createRoleAssignment("/", "295c179b-9ad3-4117-99cd-b1aa66cf4517", roleDefinition, principalId);

Creates a new role assignment.
deleteRoleAssignment(string, string, DeleteRoleAssignmentOptions)

Deletes role assignments previously created in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleAssignment = await client.createRoleAssignment("/", "295c179b-9ad3-4117-99cd-b1aa66cf4517");
await client.deleteRoleAssignment(roleAssignment.properties.roleScope, roleAssignment.name);

Deletes an existing role assignment.
deleteRoleDefinition(string, string, DeleteRoleDefinitionOptions)

Deletes a custom role definition previously created in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleDefinition = await client.setRoleDefinition("/", "23b8bb1a-39c0-4c89-a85b-dd3c99273a8a", []);
await client.deleteRoleDefinition("/", roleDefinition.name);
getRoleAssignment(string, string, GetRoleAssignmentOptions)

Gets a role assignments previously created in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
let roleAssignment = await client.createRoleAssignment("/", "295c179b-9ad3-4117-99cd-b1aa66cf4517");
roleAssignment = const await client.getRoleAssignment(roleAssignment.properties.roleScope, roleAssignment.name);
console.log(roleAssignment);

Gets an existing role assignment.
getRoleDefinition(string, string, GetRoleDefinitionOptions)

Gets a role definition from Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleDefinition = await client.getRoleDefinition("/", "b86a8fe4-44ce-4948-aee5-eccb2c155cd7");
console.log(roleDefinition);
listRoleAssignments(string, ListRoleAssignmentsOptions)

Iterates over all of the available role assignments in an Azure Key Vault.

Example usage:

let client = new KeyVaultAccessControlClient(url, credentials);
for await (const roleAssignment of client.listRoleAssignments("/")) {
  console.log("Role assignment: ", roleAssignment);
}

Lists all of the role assignments in a given scope.
listRoleDefinitions(string, ListRoleDefinitionsOptions)

Iterates over all of the available role definitions in an Azure Key Vault.

Example usage:

let client = new KeyVaultAccessControlClient(url, credentials);
for await (const roleDefinitions of client.listRoleDefinitions("/")) {
  console.log("Role definition: ", roleDefinitions);
}

Lists all of the role definition in a given scope.
setRoleDefinition(string, SetRoleDefinitionOptions)

Creates or updates a role definition in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const permissions = [{ dataActions: [KnownKeyVaultDataAction.BackupHsmKeys] }];
const roleDefinitionName = "23b8bb1a-39c0-4c89-a85b-dd3c99273a8a";
const roleDefinition = await client.setRoleDefinition(KnownKeyVaultRoleScope.Global, { permissions, roleDefinitionName });
console.log(roleDefinition);

Constructor Details

KeyVaultAccessControlClient(string, TokenCredential, AccessControlClientOptions)

Creates an instance of the KeyVaultAccessControlClient.

Example usage:

import { KeyVaultAccessControlClient } from "@azure/keyvault-admin";
import { DefaultAzureCredential } from "@azure/identity";

let vaultUrl = `https://<MY KEY VAULT HERE>.vault.azure.net`;
let credentials = new DefaultAzureCredential();

let client = new KeyVaultAccessControlClient(vaultUrl, credentials);

new KeyVaultAccessControlClient(vaultUrl: string, credential: TokenCredential, options?: AccessControlClientOptions)

Parameters

vaultUrl

string

the URL of the Key Vault. It should have this shape: https://${your-key-vault-name}.vault.azure.net. You should validate that this URL references a valid Key Vault or Managed HSM resource. See https://aka.ms/azsdk/blog/vault-uri for details.

credential
TokenCredential

An object that implements the TokenCredential interface used to authenticate requests to the service. Use the @azure/identity package to create a credential that suits your needs.

options
AccessControlClientOptions

Options used to configure Key Vault API requests. Omit this parameter to use the default configuration.

Property Details

vaultUrl

The base URL to the vault

vaultUrl: string

Property Value

string

Method Details

createRoleAssignment(string, string, string, string, CreateRoleAssignmentOptions)

Creates a role assignment in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleDefinition = await client.listRoleDefinitions("/").next();
const principalId = "4871f6a6-374f-4b6b-8b0c-f5d84db823f6";
const result = await client.createRoleAssignment("/", "295c179b-9ad3-4117-99cd-b1aa66cf4517", roleDefinition, principalId);

Creates a new role assignment.

function createRoleAssignment(roleScope: string, name: string, roleDefinitionId: string, principalId: string, options?: CreateRoleAssignmentOptions): Promise<KeyVaultRoleAssignment>

Parameters

roleScope

string

The scope of the role assignment.

name

string

The name of the role assignment. Must be a UUID.

roleDefinitionId

string

The role definition ID used in the role assignment.

principalId

string

The principal ID assigned to the role. This maps to the ID inside the Active Directory. It can point to a user, service principal, or security group.

options
CreateRoleAssignmentOptions

The optional parameters.

Returns

Promise<KeyVaultRoleAssignment>

deleteRoleAssignment(string, string, DeleteRoleAssignmentOptions)

Deletes role assignments previously created in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleAssignment = await client.createRoleAssignment("/", "295c179b-9ad3-4117-99cd-b1aa66cf4517");
await client.deleteRoleAssignment(roleAssignment.properties.roleScope, roleAssignment.name);

Deletes an existing role assignment.

function deleteRoleAssignment(roleScope: string, name: string, options?: DeleteRoleAssignmentOptions): Promise<void>

Parameters

roleScope

string

The scope of the role assignment.

name

string

The name of the role assignment.

options
DeleteRoleAssignmentOptions

The optional parameters.

Returns

Promise<void>

deleteRoleDefinition(string, string, DeleteRoleDefinitionOptions)

Deletes a custom role definition previously created in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleDefinition = await client.setRoleDefinition("/", "23b8bb1a-39c0-4c89-a85b-dd3c99273a8a", []);
await client.deleteRoleDefinition("/", roleDefinition.name);

function deleteRoleDefinition(roleScope: string, name: string, options?: DeleteRoleDefinitionOptions): Promise<void>

Parameters

roleScope

string

The scope of the role definition.

name

string

The name of the role definition to delete.

options
DeleteRoleDefinitionOptions

The optional parameters.

Returns

Promise<void>

getRoleAssignment(string, string, GetRoleAssignmentOptions)

Gets a role assignments previously created in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
let roleAssignment = await client.createRoleAssignment("/", "295c179b-9ad3-4117-99cd-b1aa66cf4517");
roleAssignment = const await client.getRoleAssignment(roleAssignment.properties.roleScope, roleAssignment.name);
console.log(roleAssignment);

Gets an existing role assignment.

function getRoleAssignment(roleScope: string, name: string, options?: GetRoleAssignmentOptions): Promise<KeyVaultRoleAssignment>

Parameters

roleScope

string

The scope of the role assignment.

name

string

The name of the role assignment.

options
GetRoleAssignmentOptions

The optional parameters.

Returns

Promise<KeyVaultRoleAssignment>

getRoleDefinition(string, string, GetRoleDefinitionOptions)

Gets a role definition from Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const roleDefinition = await client.getRoleDefinition("/", "b86a8fe4-44ce-4948-aee5-eccb2c155cd7");
console.log(roleDefinition);

function getRoleDefinition(roleScope: string, name: string, options?: GetRoleDefinitionOptions): Promise<KeyVaultRoleDefinition>

Parameters

roleScope

string

The scope of the role definition.

name

string

The name of the role definition.

options
GetRoleDefinitionOptions

The optional parameters.

Returns

Promise<KeyVaultRoleDefinition>

listRoleAssignments(string, ListRoleAssignmentsOptions)

Iterates over all of the available role assignments in an Azure Key Vault.

Example usage:

let client = new KeyVaultAccessControlClient(url, credentials);
for await (const roleAssignment of client.listRoleAssignments("/")) {
  console.log("Role assignment: ", roleAssignment);
}

Lists all of the role assignments in a given scope.

function listRoleAssignments(roleScope: string, options?: ListRoleAssignmentsOptions): PagedAsyncIterableIterator<KeyVaultRoleAssignment, KeyVaultRoleAssignment[], PageSettings>

Parameters

roleScope

string

The scope of the role assignments.

options
ListRoleAssignmentsOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<KeyVaultRoleAssignment, KeyVaultRoleAssignment[], PageSettings>

listRoleDefinitions(string, ListRoleDefinitionsOptions)

Iterates over all of the available role definitions in an Azure Key Vault.

Example usage:

let client = new KeyVaultAccessControlClient(url, credentials);
for await (const roleDefinitions of client.listRoleDefinitions("/")) {
  console.log("Role definition: ", roleDefinitions);
}

Lists all of the role definition in a given scope.

function listRoleDefinitions(roleScope: string, options?: ListRoleDefinitionsOptions): PagedAsyncIterableIterator<KeyVaultRoleDefinition, KeyVaultRoleDefinition[], PageSettings>

Parameters

roleScope

string

The scope of the role definition.

options
ListRoleDefinitionsOptions

The optional parameters.

Returns

PagedAsyncIterableIterator<KeyVaultRoleDefinition, KeyVaultRoleDefinition[], PageSettings>

setRoleDefinition(string, SetRoleDefinitionOptions)

Creates or updates a role definition in an Azure Key Vault.

Example usage:

const client = new KeyVaultAccessControlClient(url, credentials);
const permissions = [{ dataActions: [KnownKeyVaultDataAction.BackupHsmKeys] }];
const roleDefinitionName = "23b8bb1a-39c0-4c89-a85b-dd3c99273a8a";
const roleDefinition = await client.setRoleDefinition(KnownKeyVaultRoleScope.Global, { permissions, roleDefinitionName });
console.log(roleDefinition);

function setRoleDefinition(roleScope: string, options?: SetRoleDefinitionOptions): Promise<KeyVaultRoleDefinition>

Parameters

roleScope

string

The scope of the role definition.

options
SetRoleDefinitionOptions

The optional parameters.

Returns

Promise<KeyVaultRoleDefinition>