mirror of
https://github.com/optim-enterprises-bv/vault.git
synced 2025-10-29 17:52:32 +00:00
secrets/azure: add doc for rotate-root and AAD migration (#13066)
* secrets/azure: add doc for rotate-root and AAD migration * Formatting * Fix bad link, update warnings
This commit is contained in:
Jason O'Donnell
@@ -38,7 +38,10 @@ service principals. Environment variables will override any parameters set in th
|
||||
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 has been [deprecated by Microsoft and will be removed in 2022](https://docs.microsoft.com/en-us/graph/migrate-azure-ad-graph-faq).
|
||||
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`.
|
||||
@@ -55,7 +58,8 @@ service principals. Environment variables will override any parameters set in th
|
||||
"client_secret": "9a6346...",
|
||||
"environment": "AzureGermanCloud",
|
||||
"password_policy": "azure_policy",
|
||||
"use_microsoft_graph_api": true
|
||||
"use_microsoft_graph_api": true,
|
||||
"root_password_ttl": "48d"
|
||||
}
|
||||
```
|
||||
|
||||
@@ -162,6 +166,31 @@ $ 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
|
||||
|
||||
@@ -21,12 +21,12 @@ If an existing service principal is specified as part of the role configuration,
|
||||
a new password will be dynamically generated instead of a new service principal.
|
||||
The password will be deleted when the lease is revoked.
|
||||
|
||||
~> Microsoft has deprecated their Azure Active Directory API and will be removing it in
|
||||
~> Microsoft is shutting down their Azure Active Directory API and will be retiring it in
|
||||
2022. If you are currently using this secret engine, you will need to update the
|
||||
credentials to include Microsoft Graph API permissions and specify the
|
||||
`use_microsoft_graph_api` configuration value as true. See the
|
||||
[API Docs](/api-docs/secret/azure#use_microsoft_graph_api) for more details.
|
||||
|
||||
|
||||
## Setup
|
||||
|
||||
Most secrets engines must be configured in advance before they can perform their
|
||||
@@ -50,7 +50,8 @@ management tool.
|
||||
subscription_id=$AZURE_SUBSCRIPTION_ID \
|
||||
tenant_id=$AZURE_TENANT_ID \
|
||||
client_id=$AZURE_CLIENT_ID \
|
||||
client_secret=$AZURE_CLIENT_SECRET
|
||||
client_secret=$AZURE_CLIENT_SECRET \
|
||||
use_microsoft_graph_api=true
|
||||
|
||||
Success! Data written to: azure/config
|
||||
```
|
||||
@@ -192,17 +193,101 @@ The individual parameters are described in the [configuration][config] section o
|
||||
If the client ID or secret are not present and Vault is running on an 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:
|
||||
### MS Graph Permissions
|
||||
|
||||
- "Owner" role for the subscription scope
|
||||
- "Read and write all applications" permission in AAD
|
||||
The following Azure permissions should be assigned to the service principal provided to Vault for managing Azure:
|
||||
|
||||
These permissions can be configured through the Azure Portal, CLI tool, or PowerShell.
|
||||
In your Azure subscription, your account must have `Microsoft.Authorization/*/Write`
|
||||
access to assign an AD app to a role. This action is granted through the [Owner](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#owner) role or
|
||||
[User Access Administrator](https://docs.microsoft.com/en-us/azure/role-based-access-control/built-in-roles#user-access-administrator) role. If your account is assigned to the Contributor role, you
|
||||
don't have adequate permission. You will receive an error when attempting to assign the service
|
||||
principal to a role.
|
||||
| Permission Name | Type |
|
||||
|-------------------------------|-------------|
|
||||
| Application.Read.All | Application |
|
||||
| Application.ReadWrite.All | Application |
|
||||
| Application.ReadWrite.OwnedBy | Application |
|
||||
| Directory.Read.All | Application |
|
||||
| Directory.ReadWrite.All | Application |
|
||||
| Group.Read.All | Application |
|
||||
| Group.ReadWrite.All | Application |
|
||||
| GroupMember.Read.All | Application |
|
||||
| GroupMember.ReadWrite.All | Application |
|
||||
|
||||
| Permission Name | Type |
|
||||
|-------------------------------|-------------|
|
||||
| Application.Read.All | Delegated |
|
||||
| Application.ReadWrite.All | Delegated |
|
||||
| Directory.AccessAsUser.All | Delegated |
|
||||
| Directory.Read.All | Delegated |
|
||||
| Directory.ReadWrite.All | Delegated |
|
||||
| Group.Read.All | Delegated |
|
||||
| Group.ReadWrite.All | Delegated |
|
||||
| GroupMember.Read.All | Delegated |
|
||||
| GroupMember.ReadWrite.All | Delegated |
|
||||
|
||||
Additionally the following IAM roles are required and need to be added to the service
|
||||
principal using the Azure portal:
|
||||
|
||||
- "Owner" role
|
||||
|
||||
### AAD (Azure Active Directory)
|
||||
|
||||
~> Microsoft is shutting down their Azure Active Directory API and will be retiring it in
|
||||
2022. If you are currently using this secret engine, you will need to update the
|
||||
credentials to include Microsoft Graph API permissions and specify the
|
||||
`use_microsoft_graph_api` configuration value as true. See the
|
||||
[API Docs](/api-docs/secret/azure#use_microsoft_graph_api) for more details.
|
||||
|
||||
As part of the retirement of Azure Active Directory, new service principals can no longer
|
||||
be granted Azure Active Directory permissions using the Azure Portal. To add the neccessary
|
||||
API permissions for AAD, the Azure CLI is suggested. The following commands will add the
|
||||
correct privileges to an existing service principal:
|
||||
|
||||
```shell
|
||||
APP_ID='<App ID Here>'
|
||||
|
||||
az ad app permission add \
|
||||
--id ${APP_ID?} \
|
||||
--api 00000002-0000-0000-c000-000000000000 \
|
||||
--api-permissions \
|
||||
1cda74f2-2616-4834-b122-5cb1b07f8a59=Role \
|
||||
78c8a3c8-a07e-4b9e-af1b-b5ccab50a175=Role \
|
||||
970d6fa6-214a-4a9b-8513-08fad511e2fd=Scope \
|
||||
311a71cc-e848-46a1-bdf8-97ff7156d8e6=Scope
|
||||
|
||||
az ad app permission grant --id ${APP_ID?} --api 00000002-0000-0000-c000-000000000000
|
||||
```
|
||||
|
||||
Additionally the following IAM roles are required and need to be added to the service
|
||||
principal using the Azure portal:
|
||||
|
||||
- "Owner" role
|
||||
|
||||
### Migrating From AAD To Microsoft Graph
|
||||
|
||||
In this example we will migrate the Azure secret engine from using Azure Active Directory
|
||||
(AAD) to Microsoft Graph.
|
||||
|
||||
First, create a new service principal [with the proper permissions](/docs/secrets/azure#authentication)
|
||||
for managing Azure accounts. After granting the appropriate permissions, the following will be needed
|
||||
from the service principal to configure the secret engine:
|
||||
|
||||
1. Application (client) ID
|
||||
1. Directory (tenant) ID
|
||||
1. Client Secret
|
||||
1. Subscription ID
|
||||
|
||||
Finally, the Azure secret engine configuration can be updated with the new values:
|
||||
|
||||
```shell
|
||||
TENANT_ID='<Directory (Tenant) ID Here>'
|
||||
CLIENT_ID='Application (Client) ID Here>'
|
||||
CLIENT_SECRET='<Client Secret Here>'
|
||||
SUBSCRIPTION_ID='<Subcription ID Here>'
|
||||
|
||||
vault write azure/config \
|
||||
subscription_id=$SUBSCRIPTION_ID \
|
||||
client_id=$CLIENT_ID \
|
||||
client_secret=$CLIENT_SECRET \
|
||||
tenant_id=$TENANT_ID \
|
||||
use_microsoft_graph_api=true
|
||||
```
|
||||
|
||||
## Choosing between dynamic or existing service principals
|
||||
|
||||
|
||||
Reference in New Issue
Block a user