You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: articles/azure-app-configuration/use-key-vault-references-dotnet-core.md
+70-54Lines changed: 70 additions & 54 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -20,77 +20,84 @@ ms.custom: mvc
20
20
---
21
21
# Tutorial: Use Key Vault references in an ASP.NET Core app
22
22
23
-
In this tutorial, you'll learn how to use the Azure App Configuration service together with Azure Key Vault. These are complementary services, which will be used side by side in most application deployments. To help you use them together, App Configuration allows you to create keys that reference values stored in Key Vault. When you do this, App Configuration stores the URI to the Key Vault value, rather than the value itself. Your application retrieves the value of this key using the App Configuration client provider, just like any other key stored in App Configuration. The client provider recognizes it as a Key Vault reference, and calls out to Key Vault to retrieve the value. Your application is responsible for authenticating properly to both App Configuration and Key Vault. The two services don't communicate directly.
23
+
In this tutorial, you learn how to use the Azure App Configuration service together with Azure Key Vault. App Configuration and Key Vault are complementary services used side by side in most application deployments.
24
24
25
-
This tutorial shows how you can implement Key Vault references in your code. It builds on the web app introduced in the quickstarts. Before you continue, finish [Create an ASP.NET Core app with App Configuration](./quickstart-aspnet-core-app.md) first.
25
+
App Configuration helps you use the services together by creating keys that reference values stored in Key Vault. When App Configuration creates such keys, it stores the URIs of Key Vault values rather than the values themselves.
26
26
27
-
You can use any code editor to do the steps in this tutorial. [Visual Studio Code](https://code.visualstudio.com/) is an excellent option that's available on the Windows, macOS, and Linux platforms.
27
+
Your application uses the App Configuration client provider to retrieve Key Vault references, just as it does for any other keys stored in App Configuration. In this case, the values stored in App Configuration are URIs that reference the values in the Key Vault. They are not Key Vault values or credentials. Because the client provider recognizes the keys as Key Vault references, it uses Key Vault to retrieve their values.
28
+
29
+
Your application is responsible for authenticating properly to both App Configuration and Key Vault. The two services don't communicate directly.
30
+
31
+
This tutorial shows you how to implement Key Vault references in your code. It builds on the web app introduced in the quickstarts. Before you continue, finish [Create an ASP.NET Core app with App Configuration](./quickstart-aspnet-core-app.md) first.
32
+
33
+
You can use any code editor to do the steps in this tutorial. For example, [Visual Studio Code](https://code.visualstudio.com/) is a cross-platform code editor that's available for the Windows, macOS, and Linux operating systems.
28
34
29
35
In this tutorial, you learn how to:
30
36
31
37
> [!div class="checklist"]
32
-
> * Create an App Config key that references a value stored in Key Vault
33
-
> * Access the value of this key from an ASP.NET Core web application
38
+
> * Create an App Configuration key that references a value stored in Key Vault.
39
+
> * Access the value of this key from an ASP.NET Core web application.
34
40
35
41
## Prerequisites
36
42
37
-
To do this tutorial, install the [.NET Core SDK](https://dotnet.microsoft.com/download).
43
+
Before you start this tutorial, install the [.NET Core SDK](https://dotnet.microsoft.com/download).
1. Select the **Create a resource** option on the upper left-hand corner of the Azure portal
49
+
1. Select the **Create a resource** option in the upper-left corner of the Azure portal:
44
50
45
-
46
-
2. In the Search box, enter **Key Vault**.
47
-
3. From the results list, choose**Key Vault**.
48
-
4. On the Key Vault section, choose**Create**.
49
-
5. On the **Create key vault** section provide the following information:
50
-
-**Name**: A unique name is required. For this quickstart, we use **Contoso-vault2**.
51
-
-**Subscription**: Choose a subscription.
52
-
-Under**Resource Group**, choose **Create new** and enter a resource group name.
53
-
- In the **Location**pull-down menu, choose a location.
54
-
-Leave the other options to their defaults.
55
-
6. After providing the information above, select**Create**.
51
+
52
+
1. In the search box, enter **Key Vault**.
53
+
1. From the results list, select**Key vaults** on the left.
54
+
1. In **Key vaults**, select**Add**.
55
+
1. On the right in **Create key vault**, provide the following information:
56
+
-Select **Subscription** to choose a subscription.
57
+
-In **Resource Group**, select **Create new** and enter a resource group name.
58
+
-In**Key vault name**, a unique name is required. For this tutorial, enter **Contoso-vault2**.
59
+
- In the **Region**drop-down list, choose a location.
60
+
1.Leave the other **Create key vault**options with their default values.
61
+
1. Select**Create**.
56
62
57
63
At this point, your Azure account is the only one authorized to access this new vault.
58
64
59
-
65
+
60
66
61
67
## Add a secret to Key Vault
62
68
63
-
To add a secret to the vault, you just need to take a couple of additional steps. In this case, we add a message that we can use to test Key Vault retrieval. The message is called **Message** and we store the value of **Hello from Key Vault** in it.
69
+
To add a secret to the vault, you need to take just a few additional steps. In this case, add a message that you can use to test Key Vault retrieval. The message is called **Message**, and you store the value "Hello from Key Vault" in it.
64
70
65
-
1. On the Key Vault properties pages, select **Secrets**.
66
-
1. Click on **Generate/Import**.
67
-
1. On the **Create a secret** screen choose the following values:
68
-
-**Upload options**: Manual.
69
-
-**Name**: Message
70
-
-**Value**: Hello from Key Vault
71
-
- Leave the other values to their defaults. Click **Create**.
71
+
1. From the Key Vault properties pages, select **Secrets**.
72
+
1. Select **Generate/Import**.
73
+
1. In the **Create a secret** pane, enter the following values:
74
+
-**Upload options**: Enter **Manual**.
75
+
-**Name**: Enter **Message**.
76
+
-**Value**: Enter **Hello from Key Vault**.
77
+
1. Leave the other **Create a secret** properties with their default values.
78
+
1. Select **Create**.
72
79
73
-
## Add a Key Vault reference to App Config
80
+
## Add a Key Vault reference to App Configuration
74
81
75
-
1. Sign in to the [Azure portal](https://portal.azure.com). Select **All resources**, and select the app configuration store instance that you created in the quickstart.
82
+
1. Sign in to the [Azure portal](https://portal.azure.com). Select **All resources**, and then select the App Configuration store instance that you created in the quickstart.
76
83
77
-
1.Click**Configuration Explorer**
84
+
1.Select**Configuration Explorer**.
78
85
79
-
1.Click**+ Create** > **Key vault reference** and choose the following values:
80
-
-**Key**: TestApp:Settings:KeyVaultMessage
81
-
-**Label**: Leave blank
82
-
-**Subscription**, **Resource group**, **Key vault**: Choose the options corresponding to the Key Vault that you created in the previous section.
83
-
-**Secret**: Select the secret called**Message** that you created in the previous section.
86
+
1.Select**+ Create** > **Key vault reference**, and then specify the following values:
-**Subscription**, **Resource group**, and **Key vault**: Enter the values corresponding to those in the key vault you created in the previous section.
90
+
-**Secret**: Select the secret named**Message** that you created in the previous section.
84
91
85
92
## Connect to Key Vault
86
93
87
-
1.For this tutorial, you'll use a service principal for authentication to KeyVault. To create this service principal, use the Azure CLI [az ad sp create-for-rbac](/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) command:
94
+
1.In this tutorial, you use a service principal for authentication to Key Vault. To create this service principal, use the Azure CLI [az ad sp create-for-rbac](/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) command:
88
95
89
96
```azurecli
90
97
az ad sp create-for-rbac -n "http://mySP" --sdk-auth
91
98
```
92
99
93
-
This operation will return a series of key / value pairs.
100
+
This operation returns a series of key/value pairs:
94
101
95
102
```console
96
103
{
@@ -107,28 +114,32 @@ To add a secret to the vault, you just need to take a couple of additional steps
107
114
}
108
115
```
109
116
110
-
1. Run the following command to allow the service principal to access your key vault:
117
+
1. Run the following command to let the service principal access your key vault:
111
118
112
-
az keyvault set-policy -n <your-unique-keyvault-name> --spn <clientId-of-your-service-principal> --secret-permissions delete get list set --key-permissions create decrypt delete encrypt get list unwrapKey wrapKey
119
+
```
120
+
az keyvault set-policy -n <your-unique-keyvault-name> --spn <clientId-of-your-service-principal> --secret-permissions delete get list set --key-permissions create decrypt delete encrypt get list unwrapKey wrapKey
121
+
```
113
122
114
-
1. Add secrets for *clientId* and *clientSecret* to Secrets Manager. These commands must be executed in the same directory as the *.csproj* file.
123
+
1. In the following commands, add secrets in place of *clientId* and *clientSecret* to Secrets Manager. The commands must be run in the same directory as the *.csproj* file.
115
124
116
-
dotnet user-secrets set ConnectionStrings:KeyVaultClientId <clientId-of-your-service-principal>
117
-
dotnet user-secrets set ConnectionStrings:KeyVaultClientSecret <clientSecret-of-your-service-principal>
125
+
```
126
+
dotnet user-secrets set ConnectionStrings:KeyVaultClientId <clientId-of-your-service-principal>
127
+
dotnet user-secrets set ConnectionStrings:KeyVaultClientSecret <clientSecret-of-your-service-principal>
128
+
```
118
129
119
130
> [!NOTE]
120
131
> These Key Vault credentials are used only within your application. Your application authenticates directly to Key Vault with these credentials. They are never passed to the App Configuration service.
121
132
122
133
## Update your code to use a Key Vault reference
123
134
124
-
1. Open *Program.cs*, and add references to required packages.
135
+
1. Open *Program.cs*, and add references to the following required packages:
125
136
126
137
```csharp
127
138
using Microsoft.Azure.KeyVault;
128
139
using Microsoft.IdentityModel.Clients.ActiveDirectory;
129
140
```
130
141
131
-
1. Update the `CreateWebHostBuilder` method to use App Configuration by calling the `config.AddAzureAppConfiguration()` method. Include the `UseAzureKeyVault` option, passing in a new `KeyVaultClient` reference to your Key Vault.
142
+
1. Update the `CreateWebHostBuilder` method to use App Configuration by calling the `config.AddAzureAppConfiguration` method. Include the `UseAzureKeyVault` option to pass in a new `KeyVaultClient` reference to your Key Vault.
132
143
133
144
```csharp
134
145
public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
@@ -151,7 +162,9 @@ To add a secret to the vault, you just need to take a couple of additional steps
151
162
.UseStartup<Startup>();
152
163
```
153
164
154
-
1. Once you've passed the *KeyVaultClient* reference to the `UseAzureKeyVault` method when initializing the connection to App Config, you can access the values of Key Vault references in the same way you access the values of regular App Config keys. To see this process in action, open *Index.cshtml* in the Views > Home directory. Replace its content with the following code:
165
+
1. When you initialized the connection to App Configuration, you passed the `KeyVaultClient` reference to the `UseAzureKeyVault` method. After the initialization, you can access the values of Key Vault references in the same way you access the values of regular App Configuration keys.
166
+
167
+
To see this process in action, open *Index.cshtml* in the **Views** > **Home** folder. Replace its contents with the following code:
155
168
156
169
```html
157
170
@using Microsoft.Extensions.Configuration
@@ -171,30 +184,33 @@ To add a secret to the vault, you just need to take a couple of additional steps
171
184
and @Configuration["TestApp:Settings:KeyVaultMessage"]</h1>
172
185
```
173
186
174
-
You access the value of the Key Vault reference *TestApp:Settings:KeyVaultMessage* in the same way as the configuration value *TestApp:Settings:Message*
187
+
You access the value of the Key Vault reference **TestApp:Settings:KeyVaultMessage** in the same way as for the configuration value of **TestApp:Settings:Message**.
175
188
176
189
## Build and run the app locally
177
190
178
191
1. To build the app by using the .NET Core CLI, run the following command in the command shell:
179
192
180
-
dotnet build
181
-
182
-
2. After the build successfully completes, run the following command to run the web app locally:
193
+
```
194
+
dotnet build
195
+
```
183
196
184
-
dotnet run
197
+
1. After the build is complete, use the following command to run the web app locally:
185
198
186
-
3. Open a browser window, and go to `http://localhost:5000`, which is the default URL for the web app hosted locally.
In this tutorial, you added an Azure managed service identity to streamline access to App Configuration and improve credential management for your app. To learn more about how to use App Configuration, continue to the Azure CLI samples.
213
+
In this tutorial, you created an App Configuration key that references a value stored in Key Vault. To learn how to add an Azure-managed service identity that streamlines access to App Configuration and Key Vault, continue to the next tutorial.
0 commit comments