Skip to content

Commit 74f4b8a

Browse files
guardrexguardrex
committed
Add AKV approach
1 parent adfd3a6 commit 74f4b8a

File tree

2 files changed

+198
-2
lines changed

2 files changed

+198
-2
lines changed

‎aspnetcore/blazor/security/account-confirmation-and-password-recovery.md‎

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -43,7 +43,18 @@ Register the `AuthMessageSenderOptions` configuration instance in the `Program`
4343
builder.Services.Configure<AuthMessageSenderOptions>(builder.Configuration);
4444
```
4545

46-
## Configure a user secret for the provider's security key
46+
## Configure a secret for the email provider's security key
47+
48+
Receive the email provider's security key from the provider and use it in the following guidance.
49+
50+
Use either or both of the following approaches to supply the secret to the app:
51+
52+
* [Secret Manager tool](#secret-manager-tool): The Secret Manager tool stores private data on the local machine and is only used during local development.
53+
* [Azure Key Vault](#azure-key-vault): You can store the secret in a key vault for use in any environment, including for the Development environment when working locally. Some developers prefer to use key vaults for staging and production deployments and use the [Secret Manager tool](#secret-manager-tool) for local development.
54+
55+
We strongly recommend that you avoid storing secrets in project code or configuration files. Use secure authentication flows, such as either or both of the approaches in this section.
56+
57+
### Secret Manager tool
4758

4859
If the project has already been initialized for the [Secret Manager tool](xref:security/app-secrets), it will already have an app secrets identifier (`<AppSecretsId>`) in its project file (`.csproj`). In Visual Studio, you can tell if the app secrets ID is present by looking at the **Properties** panel when the project is selected in **Solution Explorer**. If the app hasn't been initialized, execute the following command in a command shell opened to the project's directory. In Visual Studio, you can use the Developer PowerShell command prompt.
4960

@@ -63,6 +74,93 @@ For more information, see <xref:security/app-secrets>.
6374

6475
[!INCLUDE[](~/blazor/security/includes/secure-authentication-flows.md)]
6576

77+
### Azure Key Vault
78+
79+
[Azure Key Vault](https://azure.microsoft.com/products/key-vault/) provides a safe approach for providing the app's client secret to the app.
80+
81+
To create a key vault and set a secret, see [About Azure Key Vault secrets (Azure documentation)](/azure/key-vault/secrets/about-secrets), which cross-links resources to get started with Azure Key Vault. To implement the code in this section, record the key vault URI and the secret name from Azure when you create the key vault and secret. When you set the access policy for the secret in the **Access policies** panel:
82+
83+
* Only the **Get** secret permission is required.
84+
* Select the application as the **Principal** for the secret.
85+
86+
> [!IMPORTANT]
87+
> A key vault secret is created with an expiration date. Be sure to track when a key vault secret is going to expire and create a new secret for the app prior to that date passing.
88+
The following `GetKeyVaultSecret` method retrieves a secret from a key vault. Add this method to the server project. Adjust the namespace (`BlazorSample.Helpers`) to match your project namespace scheme.
89+
90+
`Helpers/AzureHelper.cs`:
91+
92+
```csharp
93+
using Azure;
94+
using Azure.Identity;
95+
using Azure.Security.KeyVault.Secrets;
96+
97+
namespace BlazorSample.Helpers;
98+
99+
public static class AzureHelper
100+
{
101+
public static string GetKeyVaultSecret(string tenantId, string vaultUri, string secretName)
102+
{
103+
DefaultAzureCredentialOptions options = new()
104+
{
105+
// Specify the tenant ID to use the dev credentials when running the app locally
106+
// in Visual Studio.
107+
VisualStudioTenantId = tenantId,
108+
SharedTokenCacheTenantId = tenantId
109+
};
110+
111+
var client = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential(options));
112+
var secret = client.GetSecretAsync(secretName).Result;
113+
114+
return secret.Value.Value;
115+
}
116+
}
117+
```
118+
119+
Where services are registered in the server project's `Program` file, obtain and bind the secret with Options configuration:
120+
121+
```csharp
122+
var tenantId = builder.Configuration.GetValue<string>("AzureAd:TenantId")!;
123+
var vaultUri = builder.Configuration.GetValue<string>("AzureAd:VaultUri")!;
124+
125+
var emailAuthKey = AzureHelper.GetKeyVaultSecret(
126+
tenantId, vaultUri, "EmailAuthKey");
127+
128+
var authMessageSenderOptions =
129+
new AuthMessageSenderOptions() { EmailAuthKey = emailAuthKey };
130+
builder.Configuration.GetSection(authMessageSenderOptions.EmailAuthKey)
131+
.Bind(authMessageSenderOptions);
132+
```
133+
134+
If you wish to control the environment where the preceding code operates, for example to avoid running the code locally because you've opted to use the [Secret Manager tool](#secret-manager-tool) for local development, you can wrap the preceding code in a conditional statement that checks the environment:
135+
136+
```csharp
137+
if (!context.HostingEnvironment.IsDevelopment())
138+
{
139+
...
140+
}
141+
```
142+
143+
In the `AzureAd` section of `appsettings.json`, add the following `VaultUri` and `SecretName` configuration keys and values:
144+
145+
```json
146+
"VaultUri": "{VAULT URI}",
147+
"SecretName": "{SECRET NAME}"
148+
```
149+
150+
In the preceding example:
151+
152+
* The `{VAULT URI}` placeholder is the key vault URI. Include the trailing slash on the URI.
153+
* The `{SECRET NAME}` placeholder is the secret name.
154+
155+
Example:
156+
157+
```json
158+
"VaultUri": "https://contoso.vault.azure.net/",
159+
"SecretName": "BlazorWebAppEntra"
160+
```
161+
162+
Configuration is used to facilitate supplying dedicated key vaults and secret names based on the app's environmental configuration files. For example, you can supply different configuration values for `appsettings.Development.json` in development, `appsettings.Staging.json` when staging, and `appsettings.Production.json` for the production deployment. For more information, see <xref:blazor/fundamentals/configuration>.
163+
66164
## Implement `IEmailSender`
67165

68166
The following example is based on Mailchimp's Transactional API using [Mandrill.net](https://www.nuget.org/packages/Mandrill.net). For a different provider, refer to their documentation on how to implement sending an email message.

‎aspnetcore/blazor/security/webassembly/standalone-with-identity/account-confirmation-and-password-recovery.md‎

Lines changed: 99 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -50,7 +50,18 @@ Register the `AuthMessageSenderOptions` configuration instance in the server pro
5050
builder.Services.Configure<AuthMessageSenderOptions>(builder.Configuration);
5151
```
5252

53-
## Configure a user secret for the provider's security key
53+
## Configure a secret for the email provider's security key
54+
55+
Receive the email provider's security key from the provider and use it in the following guidance.
56+
57+
Use either or both of the following approaches to supply the secret to the app:
58+
59+
* [Secret Manager tool](#secret-manager-tool): The Secret Manager tool stores private data on the local machine and is only used during local development.
60+
* [Azure Key Vault](#azure-key-vault): You can store the secret in a key vault for use in any environment, including for the Development environment when working locally. Some developers prefer to use key vaults for staging and production deployments and use the [Secret Manager tool](#secret-manager-tool) for local development.
61+
62+
We strongly recommend that you avoid storing secrets in project code or configuration files. Use secure authentication flows, such as either or both of the approaches in this section.
63+
64+
## Secret Manager Tool
5465

5566
If the server project has already been initialized for the [Secret Manager tool](xref:security/app-secrets), it will already have a app secrets identifier (`<AppSecretsId>`) in its project file (`.csproj`). In Visual Studio, you can tell if the app secrets ID is present by looking at the **Properties** panel when the project is selected in **Solution Explorer**. If the app hasn't been initialized, execute the following command in a command shell opened to the server project's directory. In Visual Studio, you can use the Developer PowerShell command prompt (use the `cd` command to change the directory to the server project after you open the command shell).
5667

@@ -70,6 +81,93 @@ For more information, see <xref:security/app-secrets>.
7081

7182
[!INCLUDE[](~/blazor/security/includes/secure-authentication-flows.md)]
7283

84+
### Azure Key Vault
85+
86+
[Azure Key Vault](https://azure.microsoft.com/products/key-vault/) provides a safe approach for providing the app's client secret to the app.
87+
88+
To create a key vault and set a secret, see [About Azure Key Vault secrets (Azure documentation)](/azure/key-vault/secrets/about-secrets), which cross-links resources to get started with Azure Key Vault. To implement the code in this section, record the key vault URI and the secret name from Azure when you create the key vault and secret. When you set the access policy for the secret in the **Access policies** panel:
89+
90+
* Only the **Get** secret permission is required.
91+
* Select the application as the **Principal** for the secret.
92+
93+
> [!IMPORTANT]
94+
> A key vault secret is created with an expiration date. Be sure to track when a key vault secret is going to expire and create a new secret for the app prior to that date passing.
95+
The following `GetKeyVaultSecret` method retrieves a secret from a key vault. Add this method to the server project. Adjust the namespace (`BlazorSample.Helpers`) to match your project namespace scheme.
96+
97+
`Helpers/AzureHelper.cs`:
98+
99+
```csharp
100+
using Azure;
101+
using Azure.Identity;
102+
using Azure.Security.KeyVault.Secrets;
103+
104+
namespace BlazorSample.Helpers;
105+
106+
public static class AzureHelper
107+
{
108+
public static string GetKeyVaultSecret(string tenantId, string vaultUri, string secretName)
109+
{
110+
DefaultAzureCredentialOptions options = new()
111+
{
112+
// Specify the tenant ID to use the dev credentials when running the app locally
113+
// in Visual Studio.
114+
VisualStudioTenantId = tenantId,
115+
SharedTokenCacheTenantId = tenantId
116+
};
117+
118+
var client = new SecretClient(new Uri(vaultUri), new DefaultAzureCredential(options));
119+
var secret = client.GetSecretAsync(secretName).Result;
120+
121+
return secret.Value.Value;
122+
}
123+
}
124+
```
125+
126+
Where services are registered in the server project's `Program` file, obtain and bind the secret with Options configuration:
127+
128+
```csharp
129+
var tenantId = builder.Configuration.GetValue<string>("AzureAd:TenantId")!;
130+
var vaultUri = builder.Configuration.GetValue<string>("AzureAd:VaultUri")!;
131+
132+
var emailAuthKey = AzureHelper.GetKeyVaultSecret(
133+
tenantId, vaultUri, "EmailAuthKey");
134+
135+
var authMessageSenderOptions =
136+
new AuthMessageSenderOptions() { EmailAuthKey = emailAuthKey };
137+
builder.Configuration.GetSection(authMessageSenderOptions.EmailAuthKey)
138+
.Bind(authMessageSenderOptions);
139+
```
140+
141+
If you wish to control the environment where the preceding code operates, for example to avoid running the code locally because you've opted to use the [Secret Manager tool](#secret-manager-tool) for local development, you can wrap the preceding code in a conditional statement that checks the environment:
142+
143+
```csharp
144+
if (!context.HostingEnvironment.IsDevelopment())
145+
{
146+
...
147+
}
148+
```
149+
150+
In the `AzureAd` section of `appsettings.json`, add the following `VaultUri` and `SecretName` configuration keys and values:
151+
152+
```json
153+
"VaultUri": "{VAULT URI}",
154+
"SecretName": "{SECRET NAME}"
155+
```
156+
157+
In the preceding example:
158+
159+
* The `{VAULT URI}` placeholder is the key vault URI. Include the trailing slash on the URI.
160+
* The `{SECRET NAME}` placeholder is the secret name.
161+
162+
Example:
163+
164+
```json
165+
"VaultUri": "https://contoso.vault.azure.net/",
166+
"SecretName": "BlazorWebAppEntra"
167+
```
168+
169+
Configuration is used to facilitate supplying dedicated key vaults and secret names based on the app's environmental configuration files. For example, you can supply different configuration values for `appsettings.Development.json` in development, `appsettings.Staging.json` when staging, and `appsettings.Production.json` for the production deployment. For more information, see <xref:blazor/fundamentals/configuration>.
170+
73171
## Implement `IEmailSender` in the server project
74172

75173
The following example is based on Mailchimp's Transactional API using [Mandrill.net](https://www.nuget.org/packages/Mandrill.net). For a different provider, refer to their documentation on how to implement sending an email message.

0 commit comments

Comments
 (0)