# 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 <a href="#configure-access" id="configure-access"></a>

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 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.
* `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.

#### Sample payload <a href="#sample-payload" id="sample-payload"></a>

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

#### Sample request <a href="#sample-request" id="sample-request"></a>

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

### Read config <a href="#read-config" id="read-config"></a>

Return the stored configuration, omitting `client_secret`.

| Method | Path            |
| ------ | --------------- |
| `GET`  | `/azure/config` |

#### Sample request <a href="#sample-request-1" id="sample-request-1"></a>

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

#### Sample response <a href="#sample-response" id="sample-response"></a>

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

### Delete config <a href="#delete-config" id="delete-config"></a>

Deletes the stored Azure configuration and credentials.

| Method   | Path            |
| -------- | --------------- |
| `DELETE` | `/azure/config` |

#### Sample request <a href="#sample-request-2" id="sample-request-2"></a>

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

### Rotate root <a href="#rotate-root" id="rotate-root"></a>

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 <a href="#parameters" id="parameters"></a>

There are no parameters to this operation.

#### Sample request <a href="#sample-request-3" id="sample-request-3"></a>

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

### Create/Update role <a href="#create-update-role" id="create-update-role"></a>

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.

| Method | Path                 |
| ------ | -------------------- |
| `POST` | `/azure/roles/:name` |

#### Parameters <a href="#parameters-1" id="parameters-1"></a>

* `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 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.
* `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`.

#### Sample payload <a href="#sample-payload-1" id="sample-payload-1"></a>

```json
{
  "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"
}
```

#### Sample request <a href="#sample-request-4" id="sample-request-4"></a>

```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 <a href="#list-roles" id="list-roles"></a>

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

| Method | Path           |
| ------ | -------------- |
| `LIST` | `/azure/roles` |

#### Sample request <a href="#sample-request-5" id="sample-request-5"></a>

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

#### Sample response <a href="#sample-response-1" id="sample-response-1"></a>

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

### Generate credentials <a href="#generate-credentials" id="generate-credentials"></a>

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

| Method | Path                 |
| ------ | -------------------- |
| `GET`  | `/azure/creds/:name` |

#### Parameters <a href="#parameters-2" id="parameters-2"></a>

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

#### Sample request <a href="#sample-request-6" id="sample-request-6"></a>

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

#### Sample response <a href="#sample-response-2" id="sample-response-2"></a>

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

### Revoking/Renewing secrets <a href="#revoking-renewing-secrets" id="revoking-renewing-secrets"></a>

See docs on how to renew and revoke leases.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.enclaive.cloud/vault/api/secrets-engines/azure-secrets-engine-api.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.