diff --git a/Makefile b/Makefile index bc4dbda5..ffb9cc26 100644 --- a/Makefile +++ b/Makefile @@ -54,9 +54,4 @@ fmtcheck: fmt: gofmt -w $(GOFMT_FILES) -# TODO: remove once the docs are moved into the Vault repo -copy_website: - cp website-docs/docs.html.md ../vault/website/source/docs/secrets/azure/index.html.md - cp website-docs/api.html.md ../vault/website/source/api/secret/azure/index.html.md - .PHONY: bin default generate test vet bootstrap fmt fmtcheck diff --git a/website-docs/api.html.md b/website-docs/api.html.md deleted file mode 100644 index 3921a542..00000000 --- a/website-docs/api.html.md +++ /dev/null @@ -1,232 +0,0 @@ ---- -layout: "api" -page_title: "Azure - Secrets Engines - HTTP API" -sidebar_current: "docs-http-secret-azure" -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 | Produces | -| :------- | :------------------------| :------------------------ | -| `POST` | `/azure/config` | `204 (empty body)` | - -- `subscription_id` (`string: `) - The subscription id for the Azure Active Directory. - This value can also be provided with the AZURE_SUBSCRIPTION_ID environment variable. -- `tenant_id` (`string: `) - 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](#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_ID environment variable. See [authentication](#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. - -### Sample Payload - -```json -{ - "subscription_id": "94ca80...", - "tenant_id": "d0ac7e...", - "client_id": "e607c4...", - "client_secret": "9a6346...", - "environment": "AzureGermanCloud" -} -``` - -### Sample Request - -``` -$ 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`. - -| Method | Path | Produces | -| :------- | :------------------------| :------------------------ | -| `GET` | `/azure/config` | `200 application/json` | - - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request GET \ - https://127.0.0.1:8200/v1/azure/config -``` - -### 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 | Produces | -| :------- | :--------------------------- | :--------------------- | -| `DELETE` | `/auth/azure/config` | `204 (empty body)` | - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request DELETE \ - https://127.0.0.1:8200/v1/auth/azure/config -``` - - -## Create/Update Role - -Create or update a Vault role. The provided Azure roles must exist -for this call to succeed. See the Azure secrets [roles docs][roles] -for more information about roles. - -| Method | Path | Produces | -| :------- | :------------------------| :------------------------ | -| `POST` | `/azure/roles/:name` | `204 (empty body)` | - - -### Parameters - -- `name` (`string: `) - Required. Name of the role. Cannot be updated. -- `azure_roles` (`array: `) - List of Azure roles to be assigned to the generated service - principal. 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//resourceGroup/Website" - }, - { - "role_id": "/subscriptions//providers/Microsoft.Authorization/roleDefinitions/", - "scope": "/subscriptions/" - } - ], - "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 -``` - - -## List Roles - -Lists all of the roles that are registered with the plugin. - -| Method | Path | Produces | -| :------- | :------------------------| :------------------------ | -| `LIST` | `/azure/roles` | `200 application/json` | - - -### Sample Request - -``` -$ curl \ - --header "X-Vault-Token: ..." \ - --request LIST \ - https://127.0.0.1:8200/v1/azure/roles -``` - -### 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 | Produces | -| :------- | :------------------------| :------------------------ | -| `GET` | `/azure/creds/:name` | `200 application/json` | - -### Parameters - -- `name` (`string: `) - 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 -``` - -### Sample Response - -```json -{ - "data": { - "client_id": "408bf248-dd4e-4be5-919a-7f6207a307ab", - "client_secret": "ad06228a-2db9-4e0a-8a5d-e047c7f32594", - ... - } -} -``` - -## Revoking/Renewing Secrets - -See docs on how to [renew](/api/system/leases.html#renew-lease) and [revoke](/api/system/leases.html#revoke-lease) leases. - - -[docs]: /docs/secrets/azure/index.html -[roles]: /docs/secrets/azure/index.html#roles diff --git a/website-docs/docs.html.md b/website-docs/docs.html.md deleted file mode 100644 index fba2a81d..00000000 --- a/website-docs/docs.html.md +++ /dev/null @@ -1,192 +0,0 @@ ---- -layout: "docs" -page_title: "Azure - Secrets Engine" -sidebar_current: "docs-secrets-azure" -description: |- - The Azure Vault secrets engine dynamically generates Azure - service principals and role assignments. ---- - -# Azure Secrets Engine - -The Azure secrets engine dynamically generates Azure service principals and role -assignments. Vault roles can be mapped to one or more Azure roles, 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. - -## Setup - -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. - -1. Enable the Azure secrets engine: - - ```text - $ 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. - -1. Configure the secrets engine with account credentials: - - ```text - $ 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 - ``` - - 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. - -1. Configure a role. Roles determine the permissions that the service principal -generated by Vault will have to Azure resources. - - To configure a role called "my-role": - - ```text - $ vault write azure/roleset/my-role ttl=1h azure_roles=-</resourceGroup/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. - -To generate a credential using the "my-role" role: - -```text -$ 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 service principal. The application can login -using the `client_id`/`client_secret` and will have access provided by the Azure roles set in -the "my-role" configuration. - - -## Roles - -Vault roles let you configure mapped Azure roles and role-specific TTL parameters. One or more 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. - -### Azure Roles -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 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. - -Example of role configuration: - -```text -$ vault write azure/roleset/my-role ttl=1h max_ttl=24h azure_roles=-</resourceGroup/Website" - }, - { - "role_id": "/subscriptions//providers/Microsoft.Authorization/roleDefinitions/", - "scope": "/subscriptions/" - }, - { - "role_name": "This won't matter as it will be overwritten", - "role_id": "/subscriptions//providers/Microsoft.Authorization/roleDefinitions/", - "scope": "/subscriptions//resourceGroup/Database" - } - ] -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 and 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. - -The following Azure roles and Azure Active Directory (AAD) permissions are required, regardless of which authentication method is used: - -- "Owner" role for the subscription scope -- "Read and write directory data" permission in AAD -- "Read and write all applications" permission in AAD - -These permissions can be configured through the Azure Portal, CLI tool, or PowerShell. - -## 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 the service principal will be prefixed with `vault-`. This may - be used to search for Vault-created credentials using other tools or the Portal. - -## Help & 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. - - -## API -The Azure secrets engine has a full HTTP API. Please see the [Azure secrets engine API docs][api] -for more details. - -[api]: /api/secret/azure/index.html -[config]: /api/secret/azure/index.html#configure -[repo]: https://github.com/hashicorp/vault-plugin-secrets-azure