New Vault OSS Now Includes Multi-factor Authentication! Learn more
  • Overview
    • Automated PKI Infrastructure
    • Data Encryption & Tokenization
    • Database Credential Rotation
    • Dynamic Secrets
    • Identity-based Access
    • Key Management
    • Kubernetes Secrets
    • Secrets Management
  • Enterprise
  • Tutorials
  • Docs
  • API
  • Community
GitHubTry Cloud
Download
    • v1.10.x (latest)
    • v1.9.x
    • v1.8.x
    • v1.7.x
    • v1.6.x
    • v1.5.x
    • v1.4.x
  • Overview
  • Client Libraries
  • Related Tools

    • Overview
    • Active Directory
    • AliCloud
    • AWS
    • Azure
    • Cassandra
    • Consul
    • Cubbyhole
      • Overview
      • Cassandra
      • Couchbase
      • Elasticsearch
      • Influxdb
      • HanaDB
      • MongoDB
      • MongoDB Atlas
      • MSSQL
      • MySQL/MariaDB
      • Oracle
      • PostgreSQL
      • Redshift
      • Snowflake
    • Google Cloud
    • Google Cloud KMS
      • Overview
      • Azure Key Vault
      • AWS KMS
      • GCP Cloud KMS
    • KMIP ENTERPRISE
      • Overview
      • K/V Version 1
      • K/V Version 2
      • Overview
      • Entity
      • Entity Alias
      • Group
      • Group Alias
      • Identity Tokens
      • Lookup
      • OIDC Provider
        • Overview
        • Duo
        • Okta
        • PingID
        • TOTP
        • Login Enforcement
    • MongoDB Atlas
    • Nomad
    • OpenLDAP
    • PKI
    • RabbitMQ
    • SSH
    • Terraform Cloud
    • TOTP
    • Transform ENTERPRISE
    • Transit
    • Overview
    • AliCloud
    • AppRole
    • AWS
    • Azure
    • Cloud Foundry
    • GitHub
    • Google Cloud
    • JWT/OIDC
    • Kerberos
    • Kubernetes
    • LDAP
    • OCI
    • Okta
    • RADIUS
    • TLS Certificates
    • Tokens
    • Username & Password
    • App ID DEPRECATED
    • Overview
    • /sys/audit
    • /sys/audit-hash
    • /sys/auth
    • /sys/capabilities
    • /sys/capabilities-accessor
    • /sys/capabilities-self
    • /sys/config/auditing
    • /sys/config/control-group
    • /sys/config/cors
    • /sys/config/reload
    • /sys/config/state
    • /sys/config/ui
    • /sys/control-group
    • /sys/generate-recovery-token
    • /sys/generate-root
    • /sys/health
    • /sys/host-info
    • /sys/in-flight-req
    • /sys/init
    • /sys/internal/counters
    • /sys/internal/specs/openapi
    • /sys/internal/ui/feature-flags
    • /sys/internal/ui/mounts
    • /sys/internal/ui/namespaces
    • /sys/internal/ui/resultant-acl
    • /sys/key-status
    • /sys/ha-status
    • /sys/leader
    • /sys/leases
    • /sys/license
    • /sys/managed-keys ENT
    • /sys/metrics
      • Overview
      • /sys/mfa/method/duo
      • /sys/mfa/method/okta
      • /sys/mfa/method/pingid
      • /sys/mfa/method/totp
      • /sys/mfa/validate
    • /sys/monitor
    • /sys/mounts
    • /sys/namespaces
    • /sys/plugins/reload/backend
    • /sys/plugins/catalog
    • /sys/policy
    • /sys/policies
    • /sys/policies/password
    • /sys/pprof
    • /sys/quotas/config
    • /sys/quotas/rate-limit
    • /sys/quotas/lease-count
    • /sys/raw
    • /sys/rekey
    • /sys/rekey-recovery-key
    • /sys/remount
      • Overview
      • /sys/replication/performance
      • /sys/replication/dr
    • /sys/rotate
    • /sys/rotate/config
    • /sys/seal
    • /sys/seal-status
    • /sys/sealwrap/rewrap
    • /sys/step-down
      • Overview
      • /sys/storage/raft
      • /sys/storage/raft/autopilot
      • /sys/storage/raft/snapshot-auto
    • /sys/tools
    • /sys/unseal
    • /sys/version-history
    • /sys/wrapping/lookup
    • /sys/wrapping/rewrap
    • /sys/wrapping/unwrap
    • /sys/wrapping/wrap
Type '/' to Search

»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.

MethodPath
POST/azure/config
  • 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.

  • 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.

  • password_policy (string: "") - Specifies a password policy to use when creating dynamic credentials. Defaults to generating an alphanumeric password if not set.

  • use_microsoft_graph_api (bool: true) - Indicates whether the secrets engine should use the Microsoft Graph API. If set to false, this will use the Azure Active Directory API which has been deprecated by Microsoft and will be removed in 2022.

    If set to true, the user specified via the client_id and client_secret will need to have the following permissions under the Microsoft Graph API:

Permission NameType
Application.Read.AllApplication
Application.ReadWrite.AllApplication
Application.ReadWrite.OwnedByApplication
Directory.Read.AllApplication
Directory.ReadWrite.AllApplication
Group.Read.AllApplication
Group.ReadWrite.AllApplication
GroupMember.Read.AllApplication
GroupMember.ReadWrite.AllApplication
Permission NameType
Application.Read.AllDelegated
Application.ReadWrite.AllDelegated
Directory.AccessAsUser.AllDelegated
Directory.Read.AllDelegated
Directory.ReadWrite.AllDelegated
Group.Read.AllDelegated
Group.ReadWrite.AllDelegated
GroupMember.Read.AllDelegated
GroupMember.ReadWrite.AllDelegated

Aside from the permissions listed above, setting this to true should be transparent to users.

  • root_password_ttl (string: 182d) - Specifies how long the root password is valid for in Azure when rotate-root generates a new client secret. This can be either a number of seconds or a time formatted duration (ex: 24h, 48d).

»Sample Payload

{
  "subscription_id": "94ca80...",
  "tenant_id": "d0ac7e...",
  "client_id": "e607c4...",
  "client_secret": "9a6346...",
  "environment": "AzureGermanCloud",
  "password_policy": "azure_policy",
  "use_microsoft_graph_api": true,
  "root_password_ttl": "48d"
}
{
  "subscription_id": "94ca80...",
  "tenant_id": "d0ac7e...",
  "client_id": "e607c4...",
  "client_secret": "9a6346...",
  "environment": "AzureGermanCloud",
  "password_policy": "azure_policy",
  "use_microsoft_graph_api": true,
  "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
$ curl \
    --header "X-Vault-Token: ..." \
    --request POST \
    --data @payload.json \
    https://127.0.0.1:8200/v1/azure/config

»Read Config

Return the stored configuration, omitting client_secret.

MethodPath
GET/azure/config

»Sample Request

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

»Sample Response

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

»Delete Config

Deletes the stored Azure configuration and credentials.

MethodPath
DELETE/azure/config

»Sample Request

$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/azure/config
$ curl \
    --header "X-Vault-Token: ..." \
    --request DELETE \
    https://127.0.0.1:8200/v1/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.

Due to the eventual consistency of Microsoft Azure client secret APIs, the plugin may briefly stop authenticating to Azure as the password propagates through their datacenters.

MethodPath
POST/azure/rotate-root

»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
$ 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.

MethodPath
POST/azure/roles/:name

»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.
  • ttl (string: "") – Specifies the default TTL for service principals generated using this role. Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine default TTL time.
  • max_ttl (string: "") – Specifies the maximum TTL for service principals generated using this role. Accepts time suffixed strings ("1h") or an integer number of seconds. Defaults to the system/engine max TTL time.

»Sample Payload

{
  "azure_roles": "[
    {
      \"role_name\": \"Contributor\",
      \"scope\":  \"/subscriptions/<uuid>/resourceGroup/Website\"
    },
    {
      \"role_id\": \"/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>\",
      \"scope\":  \"/subscriptions/<uuid>\"
    }
  ]",
  "ttl": 3600,
  "max_ttl": "24h"
}
{
  "azure_roles": "[
    {
      \"role_name\": \"Contributor\",
      \"scope\":  \"/subscriptions/<uuid>/resourceGroup/Website\"
    },
    {
      \"role_id\": \"/subscriptions/<uuid>/providers/Microsoft.Authorization/roleDefinitions/<uuid>\",
      \"scope\":  \"/subscriptions/<uuid>\"
    }
  ]",
  "ttl": 3600,
  "max_ttl": "24h"
}

»Sample Request

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

»List Roles

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

MethodPath
LIST/azure/roles

»Sample Request

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

»Sample Response

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

»Generate Credentials

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

MethodPath
GET/azure/creds/:name

»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
$ curl \
    --header "X-Vault-Token: ..." \
    http://127.0.0.1:8200/v1/azure/creds/my-role

»Sample Response

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

»Revoking/Renewing Secrets

See docs on how to renew and revoke leases.

github logoEdit this page
DocsAPILearnCommunityPrivacySecurityPress KitConsent Manager