Provide Key Vault authentication with an access control policy

Note

This article has been updated to use the new Azure PowerShell Az module. You can still use the AzureRM module, which will continue to receive bug fixes until at least December 2020. To learn more about the new Az module and AzureRM compatibility, see Introducing the new Azure PowerShell Az module. For Az module installation instructions, see Install Azure PowerShell.

The simplest way to authenticate a cloud-based application to Key Vault is with a managed identity; see Use an App Service managed identity to access Azure Key Vault for details. If you are creating an on-prem application, doing local development, or otherwise unable to use a managed identity, you can instead register a service principal manually and provide access to your key vault using an access control policy.

Key vault supports up to 1024 access policy entries, with each entry granting a distinct set of permissions to a "principal": For example, this is how the console app in the Azure Key Vault client library for .NET quickstart accesses the key vault.

For full details on Key Vault access control, see Azure Key Vault security: Identity and access management. For full details on access control, see:

Use Azure Cloud Shell

Azure hosts Azure Cloud Shell, an interactive shell environment that you can use through your browser. You can use either Bash or PowerShell with Cloud Shell to work with Azure services. You can use the Cloud Shell preinstalled commands to run the code in this article without having to install anything on your local environment.

To start Azure Cloud Shell:

Option Example/Link
Select Try It in the upper-right corner of a code block. Selecting Try It doesn't automatically copy the code to Cloud Shell. Example of Try It for Azure Cloud Shell
Go to https://shell.azure.com, or select the Launch Cloud Shell button to open Cloud Shell in your browser. Launch Cloud Shell in a new window
Select the Cloud Shell button on the menu bar at the upper right in the Azure portal. Cloud Shell button in the Azure portal

To run the code in this article in Azure Cloud Shell:

  1. Start Cloud Shell.

  2. Select the Copy button on a code block to copy the code.

  3. Paste the code into the Cloud Shell session by selecting Ctrl+Shift+V on Windows and Linux or by selecting Cmd+Shift+V on macOS.

  4. Select Enter to run the code.

Prerequisites

Grant access to your key vault

Each key vault access policy entry grants a distinct set of permissions to a principal:

  • An application If the application is cloud-based, you should instead Use an managed identity to access Azure Key Vault, if possible
  • An Azure AD group Although key vault only supports 1024 access policy entries, you can add multiple applications and users to a single Azure AD group, and then add that group as a single entry to your access control policy.
  • A User Giving users direct access to a key vault is discouraged. Ideally, users should be added to an Azure AD group, which is in turn given access to the key vault. See Azure Key Vault security: Identity and access management.

Get the objectID

To give an application, Azure AD group, or user access to your key vault, you must first obtain its objectId.

Applications

The objectId for an applications corresponds with its associated service principal. For full details on service principals. see Application and service principal objects in Azure Active Directory.

There are two ways to obtain an objectId for an application. The first is to register your application with Azure Active Directory. To do so, follow the steps in the quickstart Register an application with the Microsoft identity platform. When registration is complete, the objectID will be listed as the "Application (client) ID".

The second is to create a service principal in a terminal window. With the Azure CLI, use the az ad sp create-for-rbac command, and provide a unique service principle name to the -n flag in the format "http://<my-unique-service-principle-name>".

az ad sp create-for-rbac -n "http://<my-unique-service-principle-name"

The objectId will be listed in the output as clientID.

With Azure PowerShell, use the New-AzADServicePrincipal cmdlet.

New-AzADServicePrincipal -DisplayName <my-unique-service-principle-name>

The objectId will be listed in the output as Id (not ApplicationId).

Azure AD Groups

You can add multiple applications and users to an Azure AD group, and then give the group access to your key vault. For more details, see the Creating and adding members to an Azure AD group section, below.

To find the objectId of an Azure AD group with the Azure CLI, use the az ad group list command. Because of the large number of groups that may be in your organization, you should also provide a search string to the --display-name parameter.

az ad group list --display-name <search-string>

The objectId will be returned in the JSON:

    "objectId": "48b21bfb-74d6-48d2-868f-ff9eeaf38a64",
    "objectType": "Group",
    "odata.type": "Microsoft.DirectoryServices.Group",

To find the objectId of an Azure AD group with Azure PowerShell, use the Get-AzADGroup cmdlet. Because of the large number of groups that may be in your organization, you will probably wish to also provide a search string to the -SearchString parameter.

Get-AzADGroup -SearchString <search-string>

In the output, the objectId is listed as Id:

...
Id                    : 1cef38c4-388c-45a9-b5ae-3d88375e166a
...

Users

You can also add an individual user to an key vault's access control policy. We do not recommend this. We instead encourage you to add users to an Azure AD group, and add the group on the policies.

If you nonetheless wish to find a user with the Azure CLI, use the az ad user show command, passing the users email address to the --id parameter.

az ad user show --id <email-address-of-user>

The user's objectId will be returned in the output:

  ...
  "objectId": "f76a2a6f-3b6d-4735-9abd-14dccbf70fd9",
  "objectType": "User",
  ...

To find a user with Azure PowerShell, use the Get-AzADUser cmdlet, passing the users email address to the -UserPrincipalName parameter.

 Get-AzAdUser -UserPrincipalName <email-address-of-user>

The user's objectId will be returned in the output as Id.

...
Id                : f76a2a6f-3b6d-4735-9abd-14dccbf70fd9
Type              :

Give the principal access to your key vault

Now that you have an objectID of your principal, you can create an access policy for your key vault that gives it get, list, set, and delete permissions for both keys and secrets, plus any additional permissions you wish.

With the Azure CLI, this is done by passing the objectId to the az keyvault set-policy command.

az keyvault set-policy -n <your-unique-keyvault-name> --spn <ApplicationID-of-your-service-principal> --secret-permissions get list set delete --key-permissions create decrypt delete encrypt get list unwrapKey wrapKey

With Azure PowerShell, this is done by passing the objectId to the Set-AzKeyVaultAccessPolicy cmdlet.

Set-AzKeyVaultAccessPolicy –VaultName <your-key-vault-name> -PermissionsToKeys create,decrypt,delete,encrypt,get,list,unwrapKey,wrapKey -PermissionsToSecrets get,list,set,delete -ObjectId <Id>

Creating and adding members to an Azure AD group

You can create an Azure AD group, add applications and users to the group, and give the group access to your key vault. This allows you to add a number of applications to a key vault as a single access policy entry, and eliminates the need to give users direct access to your key vault (which we discourage). For more details, see Manage app and resource access using Azure Active Directory groups.

Additional prerequisites

In addition to the prerequisites above, you will need permissions to create/edit groups in your Azure Active Directory tenant. If you don't have permissions, you may need to contact your Azure Active Directory administrator.

If you intend to use PowerShell, you will also need the Azure AD PowerShell module

Create an Azure Active Directory group

Create a new Azure Active Directory group using the Azure CLI az ad group create command, or the Azure PowerShell New-AzureADGroup cmdlet.

az ad group create --display-name <your-group-display-name> --mail-nickname <your-group-mail-nickname>
New-AzADGroup -DisplayName <your-group-display-name> -MailNickName <your-group-mail-nickname>

In either case, make note on the newly created groups GroupId, as you will need it for the steps below.

Find the objectIds of your applications and users

You can find the objectIds of your applications using the Azure CLI with the az ad sp list command, with the --show-mine parameter.

az ad sp list --show-mine

Find the objectIds of your applications using Azure PowerShell with the Get-AzADServicePrincipal cmdlet, passing a search string to the -SearchString parameter.

Get-AzADServicePrincipal -SearchString <search-string>

To find the objectIds of your Users, follow the steps in the Users section, above.

Add your applications and users to the group

Now, add the objectIds to your newly created Azure AD group.

With the Azure CLI, use the az ad group member add, passing the objectId to the --member-id parameter.

az ad group member add -g <groupId> --member-id <objectId>

With Azure PowerShell, use the Add-AzADGroupMember cmdlet, passing the objectId to the -MemberObjectId parameter.

Add-AzADGroupMember -TargetGroupObjectId <groupId> -MemberObjectId <objectId> 

Give the AD group access to your key vault

Lastly, give the AD group permissions to your key vault using the Azure CLI az keyvault set-policy command, or the Azure PowerShell Set-AzKeyVaultAccessPolicy cmdlet. For examples, see the Give the application, Azure AD group, or user access to your key vault section, above.

The application also needs at least one Identity and Access Management (IAM) role assigned to the key vault. Otherwise it will not be able to login and will fail with insufficient rights to access the subscription.

Warning

Azure AD Groups with Managed Identities may require up to 8hr to refresh token and become effective.

Next steps