343 lines
9 KiB
Plaintext
343 lines
9 KiB
Plaintext
---
|
||
layout: api
|
||
page_title: Azure - Secrets Engines - HTTP API
|
||
description: This is the API documentation for the Vault Azure secrets engine.
|
||
---
|
||
|
||
# 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][docs].
|
||
|
||
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.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------- |
|
||
| `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](/docs/secrets/azure#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](/docs/secrets/azure#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](/docs/concepts/password-policies) to
|
||
use when creating dynamic credentials. Defaults to generating an alphanumeric password if not set.
|
||
- `use_microsoft_graph_api` `(bool: false)` - Indicates whether the secrets engine should use the
|
||
[Microsoft Graph API](https://docs.microsoft.com/en-us/graph/use-the-api). If set to false, this will use the Azure
|
||
Active Directory API which is being [retired by Microsoft and will be removed in 2022](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-faq).
|
||
- `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).
|
||
|
||
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: `Application.ReadWrite.All`, `Directory.ReadWrite.All`, and `Group.ReadWrite.All`.
|
||
|
||
Aside from the permissions listed above, setting this to true should be transparent to users.
|
||
|
||
### Sample Payload
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
<Tabs>
|
||
<Tab heading="cURL">
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request POST \
|
||
--data @payload.json \
|
||
https://127.0.0.1:8200/v1/azure/config
|
||
```
|
||
|
||
</Tab>
|
||
<Tab heading="CLI">
|
||
|
||
```shell-session
|
||
$ vault write azure/config \
|
||
subscription_id="94ca80..." \
|
||
tenant_id="d0ac7e...",
|
||
client_id="e607c4...",
|
||
client_secret="9a6346...",
|
||
environment="AzureGermanCloud",
|
||
password_policy="azure_policy"
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## Read Config
|
||
|
||
Return the stored configuration, omitting `client_secret`.
|
||
|
||
| Method | Path |
|
||
| :----- | :-------------- |
|
||
| `GET` | `/azure/config` |
|
||
|
||
### Sample Request
|
||
|
||
<Tabs>
|
||
<Tab heading="cURL">
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request GET \
|
||
https://127.0.0.1:8200/v1/azure/config
|
||
```
|
||
|
||
</Tab>
|
||
<Tab heading="CLI">
|
||
|
||
```shell-session
|
||
$ vault read azure/config
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"subscription_id": "94ca80...",
|
||
"tenant_id": "d0ac7e...",
|
||
"client_id": "e607c4...",
|
||
"environment": "AzureGermanCloud"
|
||
},
|
||
...
|
||
}
|
||
```
|
||
|
||
## Delete Config
|
||
|
||
Deletes the stored Azure configuration and credentials.
|
||
|
||
| Method | Path |
|
||
| :------- | :-------------- |
|
||
| `DELETE` | `/azure/config` |
|
||
|
||
### Sample Request
|
||
|
||
<Tabs>
|
||
<Tab heading="cURL">
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request DELETE \
|
||
https://127.0.0.1:8200/v1/azure/config
|
||
```
|
||
|
||
</Tab>
|
||
<Tab heading="CLI">
|
||
|
||
```shell-session
|
||
$ vault delete azure/config
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
## 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.
|
||
|
||
| Method | Path |
|
||
| :----- | :------------------------ |
|
||
| `POST` | `/azure/rotate-root` |
|
||
|
||
### Parameters
|
||
|
||
There are no parameters to this operation.
|
||
|
||
### Sample Request
|
||
|
||
```shell-session
|
||
$ 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][roles] for more
|
||
information about roles.
|
||
|
||
| Method | Path |
|
||
| :----- | :------------------- |
|
||
| `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][roles]
|
||
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][groups]
|
||
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][roles] 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
|
||
|
||
```json
|
||
{
|
||
"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
|
||
|
||
```shell-session
|
||
$ 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.
|
||
|
||
| Method | Path |
|
||
| :----- | :------------- |
|
||
| `LIST` | `/azure/roles` |
|
||
|
||
### Sample Request
|
||
|
||
<Tabs>
|
||
<Tab heading="cURL">
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
--request LIST \
|
||
https://127.0.0.1:8200/v1/azure/roles
|
||
```
|
||
|
||
</Tab>
|
||
<Tab heading="CLI">
|
||
|
||
```shell-session
|
||
$ vault list azure/roles
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"keys": ["my-role-one", "my-role-two"]
|
||
}
|
||
}
|
||
```
|
||
|
||
## Generate Credentials
|
||
|
||
This endpoint generates a new service principal based on the named role.
|
||
|
||
| Method | Path |
|
||
| :----- | :------------------- |
|
||
| `GET` | `/azure/creds/:name` |
|
||
|
||
### Parameters
|
||
|
||
- `name` (`string: <required>`) - Specifies the name of the role to create credentials against.
|
||
|
||
### Sample Request
|
||
|
||
<Tabs>
|
||
<Tab heading="cURL">
|
||
|
||
```shell-session
|
||
$ curl \
|
||
--header "X-Vault-Token: ..." \
|
||
http://127.0.0.1:8200/v1/azure/creds/my-role
|
||
```
|
||
|
||
</Tab>
|
||
<Tab heading="CLI">
|
||
|
||
```shell-session
|
||
$ vault read azure/creds/my-role
|
||
```
|
||
|
||
</Tab>
|
||
</Tabs>
|
||
|
||
### Sample Response
|
||
|
||
```json
|
||
{
|
||
"data": {
|
||
"client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab",
|
||
"client_secret": "9PfdaDP9qcf98ggw8WSttfVreFcN4q9c4m4x",
|
||
...
|
||
}
|
||
}
|
||
```
|
||
|
||
## Revoking/Renewing Secrets
|
||
|
||
See docs on how to [renew](/api/system/leases#renew-lease) and [revoke](/api/system/leases#revoke-lease) leases.
|
||
|
||
[docs]: /docs/secrets/azure
|
||
[roles]: /docs/secrets/azure#roles
|
||
[groups]: /docs/secrets/azure#azure-groups
|