Azure secrets engine (API)

This is the API documentation for the Vault Azure secrets engine. For general information about the usage and operation of the Azure secrets engine, please see the main Azure secrets documentation.

This documentation assumes the Azure secrets engine is enabled at the /azure path in Vault. Since it is possible to mount secrets engines at any path, please update your API calls accordingly.

Configure access

Configures the credentials required for the plugin to perform API calls to Azure. These credentials will be used to query roles and create/delete service principals. Environment variables will override any parameters set in the config.

You can configure the secrets engine with account credentials or using plugin workload identity federation (WIF).

• subscription_id (string: <required>) - The subscription id for the Azure Active Directory. This value can also be provided with the AZURE_SUBSCRIPTION_ID environment variable.
• tenant_id (string: <required>) - The tenant id for the Azure Active Directory. This value can also be provided with the AZURE_TENANT_ID environment variable.
• client_id (string:"") - The OAuth2 client id to connect to Azure. This value can also be provided with the AZURE_CLIENT_ID environment variable. See authentication for more details.
• client_secret (string:"") - The OAuth2 client secret to connect to Azure. This value can also be provided with the AZURE_CLIENT_SECRET environment variable. See authentication for more details. Mutually exclusive with identity_token_audience.
• identity_token_audience (string: "") - EnterpriseEnterprise The audience claim value for plugin identity tokens. Must match the allowed audiences configured for the target Federated Identity Credential. Mutually exclusive with client_secret.
• identity_token_ttl (string/int: 3600) - EnterpriseEnterprise The TTL of generated tokens. Defaults to 1 hour. Uses duration format strings.
• environment (string:"") - The Azure environment. This value can also be provided with the AZURE_ENVIRONMENT environment variable. If not specified, Vault will use Azure Public Cloud.
• root_password_ttl (string: 182d) - Specifies how long the root password is valid for in Azure when rotate-root generates a new client secret. Uses duration format strings.
• metadata (map[string]string: {}) - A map of string to string key/value pairs that will be stored as metadata for the mount. This can be used to store additional information about the mount for reference purposes.

• rotation_period (string/integer: 0) – EnterpriseEnterprise The amount of time, in seconds, Vault should wait before rotating the root credential. A zero value tells Vault not to rotate the root credential. The minimum rotation period is 10 seconds. You must set one of rotation_period or rotation_schedule, but cannot set both.
• rotation_schedule (string: "") – EnterpriseEnterprise The schedule, in cron-style time format, defining the schedule on which Vault should rotate the root token. Standard cron-style time format uses five fields to define the minute, hour, day of month, month, and day of week respectively. For example, 0 0 * * SAT tells Vault to rotate the root token every Saturday at 00:00. You must set one of rotation_schedule or rotation_period, but cannot set both.
• rotation_window (string/integer: 0) – EnterpriseEnterprise The maximum amount of time, in seconds, allowed to complete a rotation when a scheduled token rotation occurs. If Vault cannot rotate the token within the window (for example, due to a failure), Vault must wait to try again until the next scheduled rotation. The default rotation window is unbound and the minimum allowable window is 1 hour. You cannot set a rotation window when using rotation_period.
• disable_automated_rotation (bool: false) - EnterpriseEnterprise Cancels all upcoming rotations of the root credential until unset.

Sample payload

{
  "subscription_id": "94ca80...",
  "tenant_id": "d0ac7e...",
  "client_id": "e607c4...",
  "client_secret": "9a6346...",
  "environment": "AzureGermanCloud",
  "root_password_ttl": "48d"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/azure/config

$ vault write azure/config \
    subscription_id="94ca80..." \
    tenant_id="d0ac7e...",
    client_id="e607c4...",
    client_secret="9a6346...",
    environment="AzureGermanCloud",

Read config

Return the stored configuration, omitting client_secret.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    https://127.0.0.1:8200/v1/azure/config

$ vault read azure/config

Sample response

{
  "data": {
    "subscription_id": "94ca80...",
    "tenant_id": "d0ac7e...",
    "client_id": "e607c4...",
    "environment": "AzureGermanCloud"
  },
  ...
}

Delete config

Deletes the stored Azure configuration and credentials.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/azure/config

$ vault delete azure/config

Rotate root

This endpoint generates a new client secret for the root account defined in the config. The value generated will only be known by Vault.

Parameters

There are no parameters to this operation.

Sample request

$ curl \
  --header "X-Vault-Token: ..." \
  --request POST \
  http://127.0.0.1:8200/v1/azure/rotate-root

Create/Update role

Create or update a Vault role. Either application_object_id or azure_roles must be provided, and these resources must exist for this call to succeed. See the Azure secrets roles docs for more information about roles.

Parameters

• azure_roles (string: "") - List of Azure roles to be assigned to the generated service principal. The array must be in JSON format, properly escaped as a string. See roles docs for details on role definition.
• azure_groups (string: "") - List of Azure groups that the generated service principal will be assigned to. The array must be in JSON format, properly escaped as a string. See groups docs for more details.
• application_object_id (string: "") - Application Object ID for an existing service principal that will be used instead of creating dynamic service principals. If present, azure_roles will be ignored. See roles docs for details on role definition.
• persist_app (bool: "false") – If set to true, persists the created service principal and application for the lifetime of the role. Useful for when the Service Principal needs to maintain ownership of objects it creates
• ttl (string: "") – Specifies the default TTL for service principals generated using the role. Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine default TTL time.
• max_ttl (string: "0") – Specifies the maximum TTL for service principals generated using the role. Accepts time suffixed strings ("1h") or an integer number of seconds. The default (0) defers to the system/engine max TTL time.
• explicit_max_ttl (string: "0") – Limits the lifetime of the service principal secret in Azure and sets an upper bound on the TTL for the corresponding lease. You cannot update the service principle lifetime of an existing lease and clients cannot renew a lease once the lifetime expires. Use the default (0) to create the service principal with a max TTL of 10 years. When the lifetime ends, Vault deletes the service principal and all corresponding leases.
• permanently_delete (bool: false) - Specifies whether to permanently delete Applications and Service Principals that are dynamically created by Vault. If application_object_id is present, permanently_delete must be false.
• sign_in_audience (string: "") - Specifies the security principal types that are allowed to sign in to the application. Valid values are: AzureADMyOrg, AzureADMultipleOrgs, AzureADandPersonalMicrosoftAccount, PersonalMicrosoftAccount.
• tags (string: "") - A comma-separated string of Azure tags to attach to an application.

Sample payload

{
  "azure_roles": "[
    {
      \"role_name\": \"Contributor\",
      \"scope\":  \"/subscriptions/<uuid>/resourceGroups/Website\"
    },
    {
      \"role_id\": \"/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>\",
      \"scope\":  \"/subscriptions/<uuid>\"
    }
  ]",
  "ttl": 3600,
  "max_ttl": "24h",
  "sign_in_audience": "AzureADMyOrg",
  "tags": "team:engineering, environment:development"
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/azure/roles/my-role

Read role

The Read Role endpoint returns information about the named role:

• Configuration details for the role
• The constant invalid_data for roles created in earlier versions of Vault.
• A 404 error if the named role does not exist.

Path parameters

• name (string: <required>) – Specifies the name of the role to read. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/azure/roles/example-role

Sample response

{
  "data": {
    "application_object_id": "",
    "azure_groups": null,
    "azure_roles": [
      {
        "role_name": "Contributor",
        "scope": "/subscriptions/<uuid>>/resourceGroups/Website"
      },
      {
        "role_id": "/subscriptions/<uuid>>/providers/Microsoft.Authorization/roleDefinitions/<uuid>",
        "scope": "/subscriptions/<uuid>"
      }
    ],
    "ttl": 3600,
    "max_ttl": 0,
    "explicit_max_ttl": 0,
    "permanently_delete": false,
    "persist_app": false,
    "sign_in_audience": "AzureADMyOrg",
    "tags": [
      "team:engineering",
      "team:development"
    ],
  }
}

List roles

Lists all of the roles that are registered with the plugin.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request LIST \
    https://127.0.0.1:8200/v1/azure/roles

$ vault list azure/roles

Sample response

{
  "data": {
    "keys": ["my-role-one", "my-role-two"]
  }
}

Delete role

This endpoint deletes an existing role by the given name. If the role does not exist, a 404 is returned.

Parameters

• name (string: <required>) – Specifies the name of the role to delete. This is part of the request URL.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/azure/roles/example-role

Generate credentials

This endpoint generates a new service principal based on the named role.

Parameters

• name (string: <required>) - Specifies the name of the role to create credentials against.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/azure/creds/my-role

$ vault read azure/creds/my-role

Sample response

{
  "data": {
    "client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
    "client_secret": "9PfdaDP9qcf98ggw8WSttfVreFcN4q9c4m4x",
    ...
  }
}

Revoking/Renewing secrets

See docs on how to renew and revoke leases.

Create/Update static role

Create or update static role definitions used to manage pre-existing service principals in Azure.

Path parameters

• name (string: <required>) – Name of the static role you want to create or update.

Request parameters

• application_object_id (string: <required>) - Application object ID for an existing service principal that is managed by the static role.
• ttl (string: "") - Timespan of 1 year (8760h) or more during which the role credentials are valid. You can specify timespans as time suffixed strings ("1h") or an integer number of seconds. Leave ttl unset or set to 0 to use the default value of 2 years (17520h).
• metadata (map[string]string: {}) - A map of string to string key/value pairs that will be stored as metadata for the mount. This can be used to store additional information about the mount for reference purposes. The data stored here is displayed in the response of /azure/static-roles/:name and /azure/static-creds/:name in the metadata field. When also setting the metadata parameter on /azure/static-creds/:name, the two maps will be merged in the response of /azure/static-creds/:name, with the values from /azure/static-roles/:name taking precedence in the event of key collisions.
• secret_id (string: "") - The secret ID of the Azure password credential you want to import. Required if you provide client_secret or expiration.
• client_secret (string: "") - The plaintext secret value of the credential you want to import. If unset, you must rotate the imported credential before you can use it with Vault.
• expiration (string: "") - A future expiration time for the imported credential, in RFC3339 format.
• skip_import_rotation (bool: false) – If set to true, Vault stores the imported credential values without automatically rotating them. You cannot read the imported credentials until you manually rotate them.

Sample payload

{
  "application_object_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
  "ttl": "8760h",
  "metadata": {
    "team": "engineering",
    "environment": "development"
  }
}

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    http://127.0.0.1:8200/v1/azure/static-roles/my-static-role

Read static role

Retrieve the named static role definition.

Path parameters

• name (string: <required>) – Name of the static role you want to read.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request GET \
    http://127.0.0.1:8200/v1/azure/static-roles/my-static-role

Sample response

{
  ...
  "data": {
    "application_object_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
    "ttl": 8760,
  },
  "metadata": {
    "team": "engineering",
    "environment": "development"
  }
  ...
}

List static roles

List all existing static roles in the Azure secrets engine.

Sample request

$ curl
    --header "X-Vault-Token: ..." \
    --request LIST \
    http://127.0.0.1:8200/v1/azure/static-roles

Sample response

{
  "data": {
    "keys": ["my-static-role1", "my-static-role2"]
  }
}

Delete static role

Delete an existing static role by name.

Path parameters

• name (string: <required>) – Name of the static role you want to delete.

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    http://127.0.0.1:8200/v1/azure/static-roles/my-static-role

Get static credentials

Generate credentials associated with the named static role.

Path parameters

• name (string: <required>) – Name of the static role to get credentials for.
• metadata (map[string]any: {}) - A map of string to string key/value pairs that will be stored as metadata for the mount. This can be used to store additional information about the mount for reference purposes. The data stored here is displayed in the response of /azure/static-roles/:name and /azure/static-creds/:name in the metadata field. When also setting the metadata parameter on /azure/static-creds/:name, the two maps will be merged in the response of /azure/static-creds/:name, with the values from /azure/static-roles/:name taking precedence in the event of key collisions.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/azure/static-creds/my-static-role

Sample response

{
  "data": {
    "client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
    "client_secret": "9PfdaDP9qcf98ggw8WSttfVreFcN4q9c4m4x",
    "metadata": {
      "team": "engineering",
      "environment": "development"
    },
    ...
  }
}

Manually rotate static role password

Rotate the password of an existing static role.

Path parameters

• name (string: <required>) – Name of the static role you want to rotate the password for.

Sample request

$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    http://127.0.0.1:8200/v1/azure/rotate-role/:name