[DOCS] Add GUI for Azure/AWS/GCP Secret Engines configuration (#29647)

* wip

* finish azure docs

* some fixes

* get role heading to where it was

* Apply suggestions from code review

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update website/content/docs/secrets/azure.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* pr comments

* add aws

* gcp configuration

* fix formatting

* remove indents for parser

* formatting fixed?

* Update website/content/docs/secrets/gcp.mdx

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Apply suggestions from code review

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* try again

* might be the end of me

* tried running npm run format and got some promising results

* missed

* this should work

* numbering fixes

* Apply suggestions from code review

add group="gui"

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>

* Update azure.mdx

change heading to match

---------

Co-authored-by: Sarah Chavis <62406755+schavis@users.noreply.github.com>
This commit is contained in:
Angel Garbarino
2025-02-27 10:49:58 -07:00
committed by GitHub
parent 3bd1ae5007
commit 513e9804ee
12 changed files with 379 additions and 151 deletions

View File

@@ -53,68 +53,143 @@ 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 AWS secrets engine:
Enable the AWS secrets engine:
```text
$ vault secrets enable aws
Success! Enabled the aws secrets engine at: aws/
```
<Tabs>
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.
<Tab heading="CLI" group="cli">
1. Configure the credentials that Vault uses to communicate with AWS to generate
the IAM credentials:
```shell-session
$ vault secrets enable gcp
Success! Enabled the gcp secrets engine at: gcp/
```
```text
$ vault write aws/config/root \
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.
</Tab>
<Tab heading="GUI" group="gui">
![Partial screenshot of the Vault GUI showing the "Identity token key" search select input](/img/gui/aws/identityTokenKey.png)
You must have `list` permission on the `identity/oidc/key` endpoint to view
existing workload identity federation (WIF) identity token keys during setup.
1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Click **Enable new engine +** on the **Secrets Engines** page.
1. Select **AWS**.
1. Click **Next**.
1. Set the mount path for the AWS plugin. For example, `aws`.
1. If you use WIF, add the identity token key:
- Click **Method Options**.
- Click **Identity Token Key**.
- Enter your new key name or select one from the token key list.
1. Click **Enable engine**.
1. Click **Save** to enable the plugin.
</Tab>
</Tabs>
Configure the credentials that Vault uses to communicate with AWS to generate the IAM credentials:
<Tabs>
<Tab heading="CLI" group="cli">
```shell-session
$ vault write aws/config/root \
access_key=AKIAJWVN5Z4FOFT7NLNA \
secret_key=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 \
region=us-east-1
```
```
Internally, Vault will connect to AWS using these credentials. As such,
these credentials must be a superset of any policies which might be granted
on IAM credentials. Since Vault uses the official AWS SDK, it will use the
specified credentials. You can also specify the credentials via the standard
AWS environment credentials, shared file credentials, or IAM role/ECS task
credentials. (Note that you can't authorize vault with IAM role credentials if you plan
on using STS Federation Tokens, since the temporary security credentials
associated with the role are not authorized to use GetFederationToken.)
</Tab>
In some cases, you cannot set sensitive IAM security credentials in your
Vault configuration. For example, your organization may require that all
security credentials are short-lived or explicitly tied to a machine identity.
<Tab heading="GUI" group="gui">
To provide IAM security credentials to Vault, we recommend using Vault
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
(WIF).
![Partial screenshot of the Vault GUI showing the Configuration form](/img/gui/aws/configure.png)
~> **Notice:** Even though the path above is `aws/config/root`, do not use
your AWS root account credentials. Instead, generate a dedicated user or
role.
1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Select your `aws` plugin you want to update.
1. Click **Configure**.
1. Enter your configuration information.
1. Set the access type <EnterpriseAlert inline="true" />
1. Save your changes.
1. Alternatively, configure the audience claim value and the role ARN to assume for plugin workload identity federation:
</Tab>
```text
$ vault write aws/config/root \
</Tabs>
Internally, Vault will connect to AWS using these credentials. As such,
these credentials must be a superset of any policies which might be granted
on IAM credentials. Since Vault uses the official AWS SDK, it will use the
specified credentials. You can also specify the credentials via the standard
AWS environment credentials, shared file credentials, or IAM role/ECS task
credentials. (Note that you can't authorize vault with IAM role credentials if you plan
on using STS Federation Tokens, since the temporary security credentials
associated with the role are not authorized to use GetFederationToken.)
In some cases, you cannot set sensitive IAM security credentials in your
Vault configuration. For example, your organization may require that all
security credentials are short-lived or explicitly tied to a machine identity.
To provide IAM security credentials to Vault, we recommend using Vault
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
(WIF).
~> **Notice:** Even though the path above is `aws/config/root`, do not use
your AWS root account credentials. Instead, generate a dedicated user or
role.
Alternatively, configure the audience claim value and the role ARN to assume for plugin workload identity federation:
<Tabs>
<Tab heading="CLI" group="cli">
```shell-session
$ vault write aws/config/root \
identity_token_audience="<TOKEN AUDIENCE>" \
role_arn="<AWS ROLE ARN>"
```
```
Vault's identity token provider will internally sign the plugin identity token JWT.
Given a trust relationship is configured between Vault and AWS via
Web Identity Federation, the secrets engine can exchange this identity token to obtain
ephemeral STS credentials.
</Tab>
~> **Notice:** For this trust relationship to be established, AWS must have an
an [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
configured with information about the fully qualified and network-reachable
Issuer URL for Vault's plugin [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
This is to ensure that AWS can fetch the JWKS [public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
and verify the plugin identity token signature. To configure Vault's Issuer,
please refer to the Identity Tokens
[documentation](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
<Tab heading="GUI" group="gui">
Select **Workload Identity Federation** for Access Type and enter the following information:
![Partial screenshot of the Vault GUI showing the Configuration form with WIF access type selected](/img/gui/aws/configure-wif.png)
- **Issuer URL**: The fully qualified and network-reachable issuer URL for the Vault plugin identity token issuer. For example, `https://vault.example.com/v1/identity/oidc/plugins`.
- **Role ARN**: The ARN of the AWS IAM role to assume.
- **Identity token audience**: The audience claim value for the plugin identity tokens. This value must match the allowed audiences configured for the target Federated Identity Credential.
</Tab>
</Tabs>
## Role setup
Vault's identity token provider will internally sign the plugin identity token JWT.
Given a trust relationship is configured between Vault and AWS via
Web Identity Federation, the secrets engine can exchange this identity token to obtain
ephemeral STS credentials.
~> **Notice:** For this trust relationship to be established, AWS must have an
an [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
configured with information about the fully qualified and network-reachable
Issuer URL for Vault's plugin [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
This is to ensure that AWS can fetch the JWKS [public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
and verify the plugin identity token signature. To configure Vault's Issuer,
please refer to the Identity Tokens
[documentation](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
1. Configure a Vault role that maps to a set of permissions in AWS as well as an
AWS credential type. When users generate credentials, they are generated

View File

@@ -24,10 +24,10 @@ The password will be deleted when the lease is revoked.
<Note>
You can configure the Azure secrets engine with the Vault API or
established environment variables such as `AZURE_CLIENT_ID` or
`AZURE_CLIENT_SECRET`. If you use both methods, note that
environment variables always take precedence over API values.
You can configure the Azure secrets engine with the Vault API or
established environment variables such as `AZURE_CLIENT_ID` or
`AZURE_CLIENT_SECRET`. If you use both methods, note that
environment variables always take precedence over API values.
</Note>
@@ -35,70 +35,147 @@ 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:
Enable the Azure secrets engine:
```shell
$ vault secrets enable azure
Success! Enabled the azure secrets engine at: azure/
```
<Tabs>
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.
<Tab heading="CLI" group="cli">
1. Configure the secrets engine with account credentials:
```shell-session
$ vault secrets enable azure
Success! Enabled the azure secrets engine at: azure/
```
```shell
$ vault write azure/config \
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.
</Tab>
<Tab heading="GUI" group="gui">
![Partial screenshot of the Vault GUI showing the "Identity token key" search select input](/img/gui/azure/identityTokenKey.png)
You must have `list` permission on the `identity/oidc/key` endpoint to view
existing workload identity federation (WIF) identity token keys during setup.
1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Click **Enable new engine +** on the **Secrets Engines** page.
1. Select **Azure**.
1. Click **Next**.
1. Set the mount path for the Azure plugin. For example, `azure`.
1. If you use WIF, add the identity token key:
- Click **Method Options**.
- Click **Identity Token Key**.
- Enter your new key name or select one from the token key list.
1. Click **Enable engine**.
1. Click **Save** to enable the plugin.
</Tab>
</Tabs>
Configure the secrets engine with account credentials:
<Tabs>
<Tab heading="CLI" group="cli">
```shell-session
$ 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
```
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.
</Tab>
In some cases, you cannot set sensitive account credentials in your
Vault configuration. For example, your organization may require that all
security credentials are short-lived or explicitly tied to a machine identity.
<Tab heading="GUI" group="gui">
To provide managed identity security credentials to Vault, we recommend using Vault
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
(WIF) as shown below.
![Partial screenshot of the Vault GUI showing the Configuration form](/img/gui/azure/configure.png)
1. Alternatively, configure the audience claim value and the Client, Tenant and Subscription IDs for plugin workload identity federation:
1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Select your `azure` plugin you want to update.
1. Click **Configure**.
1. Enter your configuration information.
1. Set the access type <EnterpriseAlert inline="true" />
1. Save your changes.
```text
$ vault write azure/config \
</Tab>
</Tabs>
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.
In some cases, you cannot set sensitive account credentials in your Vault configuration. For example, your organization may require that all security credentials are short-lived or explicitly tied to a machine identity.
To provide managed identity security credentials to Vault, we recommend using Vault
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
(WIF) as shown below.
Alternatively, configure the audience claim value and the Client, Tenant and Subscription IDs for plugin workload identity federation:
<Tabs>
<Tab heading="CLI" group="cli">
```shell-session
$ vault write azure/config \
subscription_id=$AZURE_SUBSCRIPTION_ID \
tenant_id=$AZURE_TENANT_ID \
client_id=$AZURE_CLIENT_ID \
identity_token_audience=$TOKEN_AUDIENCE
```
```
The Vault identity token provider signs the plugin identity token JWT internally.
If a trust relationship exists between Vault and Azure through WIF, the secrets
engine can exchange the Vault identity token for a federated access token.
</Tab>
To configure a trusted relationship between Vault and Azure:
<Tab heading="GUI" group="gui">
- You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
For WIF configuration, select **Workload Identity Federation** for Access Type and enter the following information:
![Partial screenshot of the Vault GUI showing the Configuration form with WIF access type selected](/img/gui/azure/configure-wif.png)
- **Subscription ID**: The ID of the Azure subscription.
- **Tenant ID**: The ID of the Azure Active Directory tenant.
- **Client ID**: The OAuth2 client id to connect to Azure.
- **Issuer URL**: The fully qualified and network-reachable issuer URL for the Vault plugin identity token issuer. For example, `https://vault.example.com/v1/identity/oidc/plugins`.
- **Identity token audience**: The audience claim value for the plugin identity tokens. This value must match the allowed audiences configured for the target Federated Identity Credential. Mutually exclusive with `client_secret`.
</Tab>
</Tabs>
The Vault identity token provider signs the plugin identity token JWT internally.
If a trust relationship exists between Vault and Azure through WIF, the secrets
engine can exchange the Vault identity token for a federated access token.
To configure a trusted relationship between Vault and Azure:
- You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
for Vault.
- Azure must have a
- Azure must have a
[federated identity credential](https://learn.microsoft.com/en-us/entra/workload-id/workload-identity-federation-create-trust?pivots=identity-wif-apps-methods-azp#configure-a-federated-identity-credential-on-an-app)
configured with information about the fully qualified and network-reachable
issuer URL for the Vault plugin
[identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
Establishing a trusted relationship between Vault and Azure ensures that Azure
can fetch JWKS
[public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
and verify the plugin identity token signature.
Establishing a trusted relationship between Vault and Azure ensures that Azure
can fetch JWKS
[public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
and verify the plugin identity token signature.
1. Configure a role. A role may be set up with either an existing service principal, or
a set of Azure roles that will be assigned to a dynamically created service principal.
Configure a role. A role may be set up with either an existing service principal, or a set of Azure roles that will be assigned to a dynamically created service principal.
<Note>
The Vault UI only supports Azure Secret engine configuration. You must use the
CLI/API for role configuration and credential rotation.
</Note>
To configure a role called "my-role" with an existing service principal:

View File

@@ -38,66 +38,142 @@ 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 Google Cloud secrets engine:
Enable the Google Cloud secrets engine:
```shell-session
$ vault secrets enable gcp
Success! Enabled the gcp secrets engine at: gcp/
```
<Tabs>
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.
<Tab heading="CLI" group="cli">
1. Configure the secrets engine with account credentials, or leave blank or unwritten
to use Application Default Credentials.
```shell-session
$ vault secrets enable gcp
Success! Enabled the gcp secrets engine at: gcp/
```
```shell-session
$ vault write gcp/config credentials=@my-credentials.json
Success! Data written to: gcp/config
```
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.
If you are running Vault from inside [Google Compute Engine][gce] or [Google
Kubernetes Engine][gke], the instance or pod service account can be used in
place of specifying the credentials JSON file.
For more information on authentication, see the [authentication section](#authentication) below.
</Tab>
In some cases, you cannot set sensitive IAM security credentials in your
Vault configuration. For example, your organization may require that all
security credentials are short-lived or explicitly tied to a machine identity.
<Tab heading="GUI" group="gui">
To provide IAM security credentials to Vault, we recommend using Vault
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
(WIF) as shown below.
![Partial screenshot of the Vault GUI showing the "Identity token key" search select input](/img/gui/gcp/identityTokenKey.png)
You must have `list` permission on the `identity/oidc/key` endpoint to view
existing workload identity federation (WIF) identity token keys during setup.
1. Alternatively, configure the audience claim value and the service account email to assume for plugin workload identity federation:
1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Click **Enable new engine +** on the **Secrets Engines** page.
1. Select **Google Cloud**.
1. Click **Next**.
1. Set the mount path for the GCP plugin. For example, `gcp`.
1. If you use WIF, add the identity token key:
- Click **Method Options**.
- Click **Identity Token Key**.
- Enter your new key name or select one from the token key list.
1. Click **Enable engine**.
1. Click **Save** to enable the plugin.
```text
$ vault write gcp/config \
identity_token_audience="<TOKEN AUDIENCE>" \
service_account_email="<SERVICE ACCOUNT EMAIL>"
```
</Tab>
Vault's identity token provider signs the plugin identity token JWT internally.
If a trust relationship exists between Vault and GCP through WIF, the secrets
engine can exchange the Vault identity token for a
[federated access token](https://cloud.google.com/docs/authentication/token-types#access).
</Tabs>
To configure a trusted relationship between Vault and GCP:
- You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
Configure the secrets engine with account credentials, or leave blank or unwritten to use Application Default Credentials:
<Tabs>
<Tab heading="CLI" group="cli">
```shell-session
$ vault write gcp/config credentials=@my-credentials.json
Success! Data written to: gcp/config
```
</Tab>
<Tab heading="GUI" group="gui">
![Partial screenshot of the Vault GUI showing the Configuration form](/img/gui/gcp/configure.png)
1. Open the web UI for your Vault instance.
1. Login under the target namespace or choose the target namespace from the
selector at the bottom of the left-hand menu and re-authenticate.
1. Select **Secrets Engines** from the left-hand menu.
1. Select your `gcp` plugin you want to update.
1. Click **Configure**.
1. Enter your configuration information.
1. Set the access type <EnterpriseAlert inline="true" />
1. Save your changes.
</Tab>
</Tabs>
If you are running Vault from inside [Google Compute Engine][gce] or [Google
Kubernetes Engine][gke], the instance or pod service account can be used in
place of specifying the credentials JSON file.
For more information on authentication, see the [authentication section](#authentication) below.
In some cases, you cannot set sensitive IAM security credentials in your
Vault configuration. For example, your organization may require that all
security credentials are short-lived or explicitly tied to a machine identity.
To provide IAM security credentials to Vault, we recommend using Vault
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
(WIF) as shown below.
Alternatively, configure the audience claim value and the service account email to assume for plugin workload identity federation:
<Tabs>
<Tab heading="CLI" group="cli">
```shell-session
$ vault write gcp/config \
identity_token_audience=<TOKEN_AUDIENCE> \
service_account_email=<SERVICE_ACCOUNT_EMAIL>
```
</Tab>
<Tab heading="GUI" group="gui">
Select **Workload Identity Federation** for Access Type and enter the following information:
![Partial screenshot of the Vault GUI showing the Configuration form with WIF access type selected](/img/gui/gcp/configure-wif.png)
- **Issuer URL**: The fully qualified and network-reachable issuer URL for the Vault plugin identity token issuer. For example, `https://vault.example.com/v1/identity/oidc/plugins`.
- **Identity token audience**: The audience claim value for the plugin identity tokens. This value must match the allowed audiences configured for the target Federated Identity Credential.
- **Service account email**: Email ID for the Service Account to impersonate for Workload Identity Federation.
</Tab>
</Tabs>
Vault's identity token provider signs the plugin identity token JWT internally.
If a trust relationship exists between Vault and GCP through WIF, the secrets
engine can exchange the Vault identity token for a
[federated access token](https://cloud.google.com/docs/authentication/token-types#access).
To configure a trusted relationship between Vault and GCP:
- You must configure the [identity token issuer backend](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
for Vault.
- GCP must have a
- GCP must have a
[workload identity pool and provider](https://cloud.google.com/iam/docs/manage-workload-identity-pools-providers)
configured with information about the fully qualified and network-reachable
issuer URL for the Vault plugin's
[identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
Establishing a trusted relationship between Vault and GCP ensures that GCP
can fetch JWKS
[public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
and verify the plugin identity token signature.
Establishing a trusted relationship between Vault and GCP ensures that GCP
can fetch JWKS
[public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
and verify the plugin identity token signature.
1. Configure rolesets or static accounts. See the relevant sections below.
<Note>
The Vault UI only supports GCP Secret engine configuration. You must use the
CLI/API for additional operations.
</Note>
## Rolesets

Binary file not shown.

After

Width:  |  Height:  |  Size: 119 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 109 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 61 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 232 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 199 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 180 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 104 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 77 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 59 KiB