Skip to content

Commit 513e980

Browse files
Monkeychipschavis
Monkeychip
and
schavis
authored
[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 <[email protected]> * Update website/content/docs/secrets/azure.mdx Co-authored-by: Sarah Chavis <[email protected]> * 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 <[email protected]> * Apply suggestions from code review Co-authored-by: Sarah Chavis <[email protected]> * 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 <[email protected]> * Update azure.mdx change heading to match --------- Co-authored-by: Sarah Chavis <[email protected]>
1 parent 3bd1ae5 commit 513e980

File tree

12 files changed

+383
-155
lines changed

12 files changed

+383
-155
lines changed

‎website/content/docs/secrets/aws.mdx

Lines changed: 130 additions & 55 deletions
Original file line numberDiff line numberDiff line change
@@ -53,68 +53,143 @@ Most secrets engines must be configured in advance before they can perform their
5353
functions. These steps are usually completed by an operator or configuration
5454
management tool.
5555

56-
1. Enable the AWS secrets engine:
56+
Enable the AWS secrets engine:
5757

58-
```text
59-
$ vault secrets enable aws
60-
Success! Enabled the aws secrets engine at: aws/
61-
```
58+
<Tabs>
6259

63-
By default, the secrets engine will mount at the name of the engine. To
64-
enable the secrets engine at a different path, use the `-path` argument.
60+
<Tab heading="CLI" group="cli">
6561

66-
1. Configure the credentials that Vault uses to communicate with AWS to generate
67-
the IAM credentials:
62+
```shell-session
63+
$ vault secrets enable gcp
64+
Success! Enabled the gcp secrets engine at: gcp/
65+
```
6866

69-
```text
70-
$ vault write aws/config/root \
71-
access_key=AKIAJWVN5Z4FOFT7NLNA \
72-
secret_key=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 \
73-
region=us-east-1
74-
```
67+
By default, the secrets engine will mount at the name of the engine. To
68+
enable the secrets engine at a different path, use the `-path` argument.
7569

76-
Internally, Vault will connect to AWS using these credentials. As such,
77-
these credentials must be a superset of any policies which might be granted
78-
on IAM credentials. Since Vault uses the official AWS SDK, it will use the
79-
specified credentials. You can also specify the credentials via the standard
80-
AWS environment credentials, shared file credentials, or IAM role/ECS task
81-
credentials. (Note that you can't authorize vault with IAM role credentials if you plan
82-
on using STS Federation Tokens, since the temporary security credentials
83-
associated with the role are not authorized to use GetFederationToken.)
84-
85-
In some cases, you cannot set sensitive IAM security credentials in your
86-
Vault configuration. For example, your organization may require that all
87-
security credentials are short-lived or explicitly tied to a machine identity.
88-
89-
To provide IAM security credentials to Vault, we recommend using Vault
90-
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
91-
(WIF).
92-
93-
~> **Notice:** Even though the path above is `aws/config/root`, do not use
94-
your AWS root account credentials. Instead, generate a dedicated user or
95-
role.
96-
97-
1. Alternatively, configure the audience claim value and the role ARN to assume for plugin workload identity federation:
70+
</Tab>
9871

99-
```text
100-
$ vault write aws/config/root \
101-
identity_token_audience="<TOKEN AUDIENCE>" \
102-
role_arn="<AWS ROLE ARN>"
103-
```
72+
<Tab heading="GUI" group="gui">
73+
74+
![Partial screenshot of the Vault GUI showing the "Identity token key" search select input](/img/gui/aws/identityTokenKey.png)
75+
76+
You must have `list` permission on the `identity/oidc/key` endpoint to view
77+
existing workload identity federation (WIF) identity token keys during setup.
78+
79+
1. Open the web UI for your Vault instance.
80+
1. Login under the target namespace or choose the target namespace from the
81+
selector at the bottom of the left-hand menu and re-authenticate.
82+
1. Select **Secrets Engines** from the left-hand menu.
83+
1. Click **Enable new engine +** on the **Secrets Engines** page.
84+
1. Select **AWS**.
85+
1. Click **Next**.
86+
1. Set the mount path for the AWS plugin. For example, `aws`.
87+
1. If you use WIF, add the identity token key:
88+
- Click **Method Options**.
89+
- Click **Identity Token Key**.
90+
- Enter your new key name or select one from the token key list.
91+
1. Click **Enable engine**.
92+
1. Click **Save** to enable the plugin.
93+
94+
</Tab>
95+
96+
</Tabs>
97+
98+
Configure the credentials that Vault uses to communicate with AWS to generate the IAM credentials:
99+
100+
<Tabs>
101+
102+
<Tab heading="CLI" group="cli">
103+
104+
```shell-session
105+
$ vault write aws/config/root \
106+
access_key=AKIAJWVN5Z4FOFT7NLNA \
107+
secret_key=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 \
108+
region=us-east-1
109+
```
110+
111+
</Tab>
112+
113+
<Tab heading="GUI" group="gui">
114+
115+
![Partial screenshot of the Vault GUI showing the Configuration form](/img/gui/aws/configure.png)
116+
117+
1. Open the web UI for your Vault instance.
118+
1. Login under the target namespace or choose the target namespace from the
119+
selector at the bottom of the left-hand menu and re-authenticate.
120+
1. Select **Secrets Engines** from the left-hand menu.
121+
1. Select your `aws` plugin you want to update.
122+
1. Click **Configure**.
123+
1. Enter your configuration information.
124+
1. Set the access type <EnterpriseAlert inline="true" />
125+
1. Save your changes.
126+
127+
</Tab>
128+
129+
</Tabs>
130+
131+
Internally, Vault will connect to AWS using these credentials. As such,
132+
these credentials must be a superset of any policies which might be granted
133+
on IAM credentials. Since Vault uses the official AWS SDK, it will use the
134+
specified credentials. You can also specify the credentials via the standard
135+
AWS environment credentials, shared file credentials, or IAM role/ECS task
136+
credentials. (Note that you can't authorize vault with IAM role credentials if you plan
137+
on using STS Federation Tokens, since the temporary security credentials
138+
associated with the role are not authorized to use GetFederationToken.)
139+
140+
In some cases, you cannot set sensitive IAM security credentials in your
141+
Vault configuration. For example, your organization may require that all
142+
security credentials are short-lived or explicitly tied to a machine identity.
143+
144+
To provide IAM security credentials to Vault, we recommend using Vault
145+
[plugin workload identity federation](#plugin-workload-identity-federation-wif)
146+
(WIF).
147+
148+
~> **Notice:** Even though the path above is `aws/config/root`, do not use
149+
your AWS root account credentials. Instead, generate a dedicated user or
150+
role.
151+
152+
Alternatively, configure the audience claim value and the role ARN to assume for plugin workload identity federation:
153+
154+
<Tabs>
155+
156+
<Tab heading="CLI" group="cli">
157+
158+
```shell-session
159+
$ vault write aws/config/root \
160+
identity_token_audience="<TOKEN AUDIENCE>" \
161+
role_arn="<AWS ROLE ARN>"
162+
```
163+
164+
</Tab>
165+
166+
<Tab heading="GUI" group="gui">
167+
168+
Select **Workload Identity Federation** for Access Type and enter the following information:
169+
![Partial screenshot of the Vault GUI showing the Configuration form with WIF access type selected](/img/gui/aws/configure-wif.png)
170+
171+
- **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`.
172+
- **Role ARN**: The ARN of the AWS IAM role to assume.
173+
- **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.
174+
175+
</Tab>
176+
177+
</Tabs>
178+
179+
## Role setup
180+
Vault's identity token provider will internally sign the plugin identity token JWT.
181+
Given a trust relationship is configured between Vault and AWS via
182+
Web Identity Federation, the secrets engine can exchange this identity token to obtain
183+
ephemeral STS credentials.
104184

105-
Vault's identity token provider will internally sign the plugin identity token JWT.
106-
Given a trust relationship is configured between Vault and AWS via
107-
Web Identity Federation, the secrets engine can exchange this identity token to obtain
108-
ephemeral STS credentials.
109-
110-
~> **Notice:** For this trust relationship to be established, AWS must have an
111-
an [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
112-
configured with information about the fully qualified and network-reachable
113-
Issuer URL for Vault's plugin [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
114-
This is to ensure that AWS can fetch the JWKS [public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
115-
and verify the plugin identity token signature. To configure Vault's Issuer,
116-
please refer to the Identity Tokens
117-
[documentation](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
185+
~> **Notice:** For this trust relationship to be established, AWS must have an
186+
an [IAM OIDC identity provider](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_providers_create_oidc.html)
187+
configured with information about the fully qualified and network-reachable
188+
Issuer URL for Vault's plugin [identity token provider](/vault/api-docs/secret/identity/tokens#read-plugin-identity-well-known-configurations).
189+
This is to ensure that AWS can fetch the JWKS [public keys](/vault/api-docs/secret/identity/tokens#read-active-public-keys)
190+
and verify the plugin identity token signature. To configure Vault's Issuer,
191+
please refer to the Identity Tokens
192+
[documentation](/vault/api-docs/secret/identity/tokens#configure-the-identity-tokens-backend)
118193

119194
1. Configure a Vault role that maps to a set of permissions in AWS as well as an
120195
AWS credential type. When users generate credentials, they are generated

0 commit comments

Comments
 (0)