vault/website/content/docs/secrets/azure.mdx

---
layout: docs
page_title: Azure secrets engine
description: >-
  Dynamically generate Azure service principals and role assignments with the Azure secrets engine plugin.
---

> [!IMPORTANT]  
> **Documentation Update:** Product documentation, which were located in this repository under `/website`, are now located in [`hashicorp/web-unified-docs`](https://github.com/hashicorp/web-unified-docs), colocated with all other product documentation. Contributions to this content should be done in the `web-unified-docs` repo, and not this one. Changes made to `/website` content in this repo will not be reflected on the developer.hashicorp.com website.

# Azure secrets engine

The Azure secrets engine dynamically generates Azure service principals along
with role and group assignments. Vault roles can be mapped to one or more Azure
roles, and optionally group assignments, providing a simple, flexible way to
manage the permissions granted to generated service principals.

Each service principal is associated with a Vault lease. When the lease expires
(either during normal revocation or through early revocation), the service
principal is automatically deleted.

If an existing service principal is specified as part of the role configuration,
a new password will be dynamically generated instead of a new service principal.
The password will be deleted when the lease is revoked.

## Setup

<Note>

You can configure the Azure secrets engine with the Vault API or
established environment variables such as `AZURE_CLIENT_ID` or
`AZURE_CLIENT_SECRET`. If you use both methods, note that
environment variables always take precedence over API values.

</Note>

Most secrets engines must be configured in advance before they can perform their
functions. These steps are usually completed by an operator or configuration
management tool.

Enable the Azure secrets engine:

<Tabs>

<Tab heading="CLI"  group="cli">

```shell-session
$ vault secrets enable azure
Success! Enabled the azure secrets engine at: azure/
```

By default, the secrets engine will mount at the name of the engine. To
enable the secrets engine at a different path, use the `-path` argument.

</Tab>

<Tab heading="GUI"  group="gui">

![Partial screenshot of the Vault GUI showing the "Identity token key" search select input](/img/gui/azure/identityTokenKey.png)

You must have `list` permission on the `identity/oidc/key` endpoint to view
existing workload identity federation (WIF) identity token keys during setup.

1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
   selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Click **Enable new engine +** on the **Secrets Engines** page.
1. Select **Azure**.
1. Click **Next**.
1. Set the mount path for the Azure plugin. For example, `azure`.
1. If you use WIF, add the identity token key:
   - Click **Method Options**.
   - Click **Identity Token Key**.
   - Enter your new key name or select one from the token key list.
1. Click **Enable engine**.
1. Click **Save** to enable the plugin.

</Tab>

</Tabs>

Configure the secrets engine with account credentials:

<Tabs>

<Tab heading="CLI"  group="cli">

```shell-session
$ vault write azure/config \
    subscription_id=$AZURE_SUBSCRIPTION_ID \
    tenant_id=$AZURE_TENANT_ID \
    client_id=$AZURE_CLIENT_ID \
    client_secret=$AZURE_CLIENT_SECRET

Success! Data written to: azure/config
```

</Tab>

<Tab heading="GUI"  group="gui">

![Partial screenshot of the Vault GUI showing the Configuration form](/img/gui/azure/configure.png)

1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
   selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Select your `azure` plugin you want to update.
1. Click **Configure**.
1. Enter your configuration information.
1. Set the access type <EnterpriseAlert inline="true" />
1. Save your changes.

</Tab>

</Tabs>

If you are running Vault inside an Azure VM with MSI enabled, `client_id` and `client_secret` may be omitted. For more information on authentication, see the [authentication](#authentication) section below.

In some cases, you cannot set sensitive account credentials in your Vault configuration. For example, your organization may require that all security credentials are short-lived or explicitly tied to a machine identity.

To provide managed identity security credentials to Vault, we recommend using Vault
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
(WIF) as shown below.

Alternatively, configure the audience claim value and the Client, Tenant and Subscription IDs for plugin workload identity federation:

<Tabs>

<Tab heading="CLI"  group="cli">

```shell-session
$ vault write azure/config \
    subscription_id=$AZURE_SUBSCRIPTION_ID \
    tenant_id=$AZURE_TENANT_ID \
    client_id=$AZURE_CLIENT_ID \
    identity_token_audience=$TOKEN_AUDIENCE
```

</Tab>

<Tab heading="GUI"  group="gui">

For WIF configuration, select **Workload Identity Federation** for Access Type and enter the following information:
  ![Partial screenshot of the Vault GUI showing the Configuration form with WIF access type selected](/img/gui/azure/configure-wif.png)
  - **Subscription ID**: The ID of the Azure subscription.
  - **Tenant ID**: The ID of the Azure Active Directory tenant.
  - **Client ID**: The OAuth2 client id to connect to Azure.
  - **Issuer URL**: The fully qualified and network-reachable issuer URL for the Vault plugin identity token issuer. For example, `https://vault.example.com/v1/identity/oidc/plugins`.
  - **Identity token audience**: The audience claim value for the plugin identity tokens. This value must match the allowed audiences configured for the target Federated Identity Credential. Mutually exclusive with `client_secret`.

</Tab>

</Tabs>

The Vault identity token provider signs the plugin identity token JWT internally.
If a trust relationship exists between Vault and Azure through WIF, the secrets
engine can exchange the Vault identity token for a federated access token.

To configure a trusted relationship between Vault and Azure:

- You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
  for Vault.
- Azure must have a
  [federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app)
  configured with information about the fully qualified and network-reachable
  issuer URL for the Vault plugin
  [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).

Establishing a trusted relationship between Vault and Azure ensures that Azure
can fetch JWKS
[public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
and verify the plugin identity token signature.

Configure a role. A role may be set up with either an existing service principal, or a set of Azure roles that will be assigned to a dynamically created service principal.

<Note>
  The Vault UI only supports Azure Secret engine configuration. You must use the
  CLI/API for role configuration and credential rotation.
</Note>

To configure a role called "my-role" with an existing service principal:

```shell-session
$ vault write azure/roles/my-role \
    application_object_id=<existing_app_obj_id> \
    ttl=1h
```

Alternatively, to configure the role to create a new service principal with Azure roles:

```shell-session
$ vault write azure/roles/my-role ttl=1h azure_roles=-<<EOF
    [
        {
            "role_name": "Contributor",
            "scope":  "/subscriptions/<uuid>/resourceGroups/Website"
        }
    ]
EOF
```

Roles may also have their own TTL configuration that is separate from the mount's
TTL. For more information on roles see the [roles](#roles) section below.

## Usage

After the secrets engine is configured and a user/machine has a Vault token with
the proper permissions, it can generate credentials. The usage pattern is the same
whether an existing or dynamic service principal is used.

To generate a credential using the "my-role" role:

```shell-session
$ vault read azure/creds/my-role

Key                Value
---                -----
lease_id           azure/creds/sp_role/1afd0969-ad23-73e2-f974-962f7ac1c2b4
lease_duration     60m
lease_renewable    true
client_id          408bf248-dd4e-4be5-919a-7f6207a307ab
client_secret      ad06228a-2db9-4e0a-8a5d-e047c7f32594
```

This endpoint generates a renewable set of credentials. The application can login
using the `client_id`/`client_secret` and will have access provided by configured service
principal or the Azure roles set in the "my-role" configuration.

## Root credential rotation

Mounts can rotate root credential keys configured directly within the mount.
Rotating to a Vault-generated key makes the key value inaccessible to the
operator and ensures only Vault can operate as a root user to manipulate dynamic
and static credentials.

```shell-session
vault write -f azure/rotate-root
```

### Schedule-based credential rotation

@include 'alerts/enterprise-only.mdx'

Use the [`rotation_schedule`](/vault/api-docs/secret/azure#rotation_schedule) field
to configure schedule-based, automatic credential rotation for root credentials in
the Azure secrets engine. For example, the following command set the rotation to
occur every Saturday at midnight (00:00)::

```shell-session
$ vault write azure/config \
    ...
    rotation_schedule="0 * * * SAT"
    ...
```

Scheduled root credential rotation can also set a
[rotation_window](/vault/api-docs/secret/azure#rotation_window) during which the
scheduled rotation is allowed to occur. Vault will stop trying to rotate the
credential once the window expires. For example, the following command tells
Vault to rotate the credential on Saturday at midnight, but only within the span
of an hour. If Vault cannot rotate the credential by 1:00, due to a failure
or otherwise, Vault will stop trying to rotate the credential until the next
scheduled rotation.

```shell-session
$ vault write azure/config \
    ...
    rotation_window="1h" \
    rotation_schedule="0 * * * SAT"
    ...
```

You can temporarily disable root rotation by setting
[`disable_automated_rotation`](/vault/api-docs/secret/azure#disable_automated_rotation)
to `true`. Setting the `disable_automated_rotation` field prevent any rotation
of the root credential until the field is reset to `false`. If you use
`rotation_period`, setting `disable_automated_rotation` also resets the credential
TTL.

For more details on rotating root credentials in the Azure plugin, refer to the
[Root credential rotation](/vault/api-docs/secret/azure#rotate-root) API docs.

## Roles

Vault roles let you configure either an existing service principal or a set of Azure roles, along with
role-specific TTL parameters. If an existing service principal is not provided, the configured Azure
roles will be assigned to a newly created service principal. The Vault role may optionally specify
role-specific `ttl` and/or `max_ttl` values. When the lease is created, the more restrictive of the
mount or role TTL value will be used.

### Application object IDs

If an existing service principal is to be used, the Application Object ID must be set on the Vault role.
This ID can be found by inspecting the desired Application with the `az` CLI tool, or via the Azure Portal. Note
that the Application **Object** ID must be provided, not the Application ID.

### Azure roles

If dynamic service principals are used, Azure roles must be configured on the Vault role.
Azure roles are provided as a JSON list, with each element describing an Azure role and scope to be assigned.
Azure roles may be specified using the `role_name` parameter ("Owner"), or `role_id`
("/subscriptions/.../roleDefinitions/...").
`role_id` is the definitive ID that's used during Vault operation; `role_name` is a convenience during
role management operations. All roles _must exist_ when the configuration is written or the operation will fail. The role lookup priority is:

1. If `role_id` is provided, it is validated and the corresponding `role_name` updated.
1. If only `role_name` is provided, a case-insensitive search-by-name is made, succeeding
   only if _exactly one_ matching role is found. The `role_id` field will updated with the matching role ID.

The `scope` must be provided for every role assignment.

### Azure groups

If dynamic service principals are used, a list of Azure groups may be configured on the Vault role.
When the service principal is created, it will be assigned to these groups. Similar to the format used
for specifying Azure roles, Azure groups may be referenced by either their `group_name` or `object_id`.
Group specification by name must yield a single matching group.

Example of role configuration:

```shell-session
$ vault write azure/roles/my-role \
    ttl=1h \
    max_ttl=24h \
    azure_roles=@az_roles.json \
    azure_groups=@az_groups.json

$ cat az_roles.json
[
  {
    "role_name": "Contributor",
    "scope":  "/subscriptions/<uuid>/resourceGroups/Website"
  },
  {
    "role_id": "/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>",
    "scope":  "/subscriptions/<uuid>"
  },
  {
    "role_name": "This won't matter as it will be overwritten",
    "role_id": "/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>",
    "scope":  "/subscriptions/<uuid>/resourceGroups/Database"
  }
]

$ cat az_groups.json
[
  {
    "group_name": "foo"
  },
  {
    "group_name": "This won't matter as it will be overwritten",
    "object_id": "a6a834a6-36c3-4575-8e2b-05095963d603"
  }
]
```

### Permanently delete Azure objects

If dynamic service principals are used, the option to permanently delete the applications and service principals created by Vault may be configured on the Vault role.
When this option is enabled and a lease is expired or revoked, the application and service principal associated with the lease will be [permanently deleted](https://docs.microsoft.com/en-us/graph/api/directory-deleteditems-delete) from the Azure Active Directory.
As a result, these objects will not count toward the [quota](https://docs.microsoft.com/en-us/azure/azure-resource-manager/management/azure-subscription-service-limits#active-directory-limits) of total resources in an Azure tenant. When this option is not enabled
and a lease is expired or revoked, the application and service principal associated with the lease will be deleted, but not permanently. These objects will be available to restore for 30 days from deletion.

Example of role configuration:

```shell-session
$ vault write azure/roles/my-role permanently_delete=true ttl=1h azure_roles=-<<EOF
    [
        {
            "role_name": "Contributor",
            "scope":  "/subscriptions/<uuid>/resourceGroups/Website"
        }
    ]
EOF
```

## Authentication

The Azure secrets backend must have sufficient permissions to read Azure role information and manage
service principals. The authentication parameters can be set in the backend configuration or as environment
variables. Environment variables will take precedence. The individual parameters are described in the
[configuration][config] section of the API docs.

If the client ID or secret are not present and Vault is running on an Azure VM, Vault will attempt to use
[Managed Service Identity (MSI)](https://docs.microsoft.com/en-us/azure/active-directory/managed-service-identity/overview)
to access Azure. Note that when MSI is used, tenant and subscription IDs must still be explicitly provided
in the configuration or environment variables.

### MS Graph API permissions

The following MS Graph [API permissions](https://learn.microsoft.com/en-us/azure/active-directory/develop/permissions-consent-overview#types-of-permissions)
must be assigned to the service principal provided to Vault for managing Azure. The permissions
differ depending on if you're using [dynamic or existing](#choosing-between-dynamic-or-existing-service-principals)
service principals.

#### Dynamic Service Principals

| Permission Name               | Type        |
| ----------------------------- | ----------- |
| Application.ReadWrite.OwnedBy | Application |
| GroupMember.ReadWrite.All     | Application |

~> **Note**: If you plan to use the [rotate root](/vault/api-docs/secret/azure#rotate-root)
credentials API, you'll need to change `Application.ReadWrite.OwnedBy` to `Application.ReadWrite.All`.

#### Existing Service Principals

| Permission Name               | Type        |
| ----------------------------- | ----------- |
| Application.ReadWrite.All     | Application |
| GroupMember.ReadWrite.All     | Application |

### Role assignments

The following Azure [role assignments](https://learn.microsoft.com/en-us/azure/role-based-access-control/role-assignments-cli)
must be granted in order for the secrets engine to manage role assignments for service
principles it creates.

| Role                                           | Scope        | Security Principal                          |
|------------------------------------------------| ------------ | ------------------------------------------- |
| [User Access Administrator][user_access_admin] | Subscription | Service Principal ID given in configuration |

## Plugin Workload Identity Federation (WIF)

<EnterpriseAlert product="vault" />

The Azure secrets engine supports the plugin WIF workflow, and has a source of identity called
a plugin identity token. The plugin identity token is a JWT that is signed internally by Vault's
[plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration).

If there is a trust relationship configured between Vault and Azure through
[workload identity federation](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation),
the secrets engine can exchange its identity token for short-lived access tokens needed to
perform its actions.

Exchanging identity tokens for access tokens lets the Azure secrets engine
operate without configuring explicit access to sensitive client credentials.

To configure the secrets engine to use plugin WIF:

1. Ensure that Vault [openid-configuration](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-openid-configuration)
   and [public JWKS](/vault/api-docs/secret/identity/tokens#read-plugin-identity-token-issuer-s-public-jwks)
   APIs are network-reachable by Azure. We recommend using an API proxy or gateway
   if you need to limit Vault API exposure.

1. Configure a
   [federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app)
   on a dedicated application registration in Azure to establish a trust relationship with Vault.
   1. The issuer URL **must** point at your [Vault plugin identity token issuer](/vault/api-docs/secret/identity/tokens#read-plugin-workload-identity-issuer-s-openid-configuration) with the
   `/.well-known/openid-configuration` suffix removed. For example:
   `https://host:port/v1/identity/oidc/plugins`.
   1. The subject identifier **must** match the unique `sub` claim issued by plugin identity tokens.
   The subject identifier should have the form `plugin-identity:<NAMESPACE_ID>:secret:<AZURE_MOUNT_ACCESSOR>`.
   1. The audience should be under 600 characters. The default value in Azure is `api://AzureADTokenExchange`.

1. Configure the Azure secrets engine with the subscription, client and tenant IDs and the OIDC audience value.

   ```shell-session
   $ vault write azure/config \
     subscription_id=$AZURE_SUBSCRIPTION_ID \
     tenant_id=$AZURE_TENANT_ID \
     client_id=$AZURE_CLIENT_ID \
     identity_token_audience="api://AzureADTokenExchange"
   ```

Your secrets engine can now use plugin WIF for its configuration credentials.
By default, WIF [credentials](https://learn.microsoft.com/en-us/entra/identity-platform/access-tokens#token-lifetime)
have a time-to-live of 1 hour and automatically refresh when they expire.

Please see the [API documentation](/vault/api-docs/secret/azure#configure-access)
for more details on the fields associated with plugin WIF.

## Choosing between dynamic or existing service principals

Dynamic service principals are preferred if the desired Azure resources can be provided
via the RBAC system and Azure roles defined in the Vault role. This form of credential is
completely decoupled from any other clients, is not subject to permission changes after
issuance, and offers the best audit granularity.

Access to some Azure services cannot be provided with the RBAC system, however. In these
cases, an existing service principal can be set up with the necessary access, and Vault
can create new passwords for this service principal. Any changes to the service principal
permissions affect all clients. Furthermore, Azure does not provide any logging with
regard to _which_ credential was used for an operation.

An important limitation when using an existing service principal is that Azure limits the
number of passwords for a single Application. This limit is based on Application object
size and isn't firmly specified, but in practice hundreds of passwords can be issued per
Application. An error will be returned if the object size is reached. This limit can be
managed by reducing the role TTL, or by creating another Vault role against a different
Azure service principal configured with the same permissions.

## Additional notes

- **If a referenced Azure role doesn't exist, a credential will not be generated.**
  Service principals will only be generated if _all_ role assignments are successful.
  This is important to note if you're using custom Azure role definitions that might be deleted
  at some point.

- Azure roles are assigned only once, when the service principal is created. If the
  Vault role changes the list of Azure roles, these changes will not be reflected in
  any existing service principal, even after token renewal.

- The time required to issue a credential is roughly proportional to the number of
  Azure roles that must be assigned. This operation make take some time (10s of seconds
  are common, and over a minute has been seen).

- Service principal credential timeouts are not used. Vault will revoke access by
  deleting the service principal.

- The Application Name for dynamic service principals will be prefixed with `vault-`. Similarly
  the `keyId` of any passwords added to an existing service principal will begin with
  `ffffff`. These may be used to search for Vault-created credentials using the `az` tool
  or Portal.

## Azure debug logs

The Azure secret engine plugin supports debug logging which includes additional information
about requests and responses from the Azure API.

To enable the Azure debug logs, set the `AZURE_SDK_GO_LOGGING`  environment variable to `all` on your Vault
server:

```shell
AZURE_SDK_GO_LOGGING=all
```

## Help &amp; support

The Azure secrets engine is written as an external Vault plugin and
thus exists outside the main Vault repository. It is automatically bundled with
Vault releases, but the code is managed separately.

Please report issues, add feature requests, and submit contributions to the
[vault-plugin-secrets-azure repo][repo] on GitHub.

## Tutorial

Refer to the [Azure Secrets
Engine](/vault/tutorials/secrets-management/azure-secrets) tutorial
to learn how to use the Azure secrets engine to dynamically generate Azure credentials.

## API

The Azure secrets engine has a full HTTP API. Please see the [Azure secrets engine API docs][api]
for more details.

[api]: /vault/api-docs/secret/azure
[config]: /vault/api-docs/secret/azure#configure-access
[repo]: https://github.com/hashicorp/vault-plugin-secrets-azure
[user_access_admin]: https://learn.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#user-access-administrator