Skip to content

Commit 0eac6c1

Browse files
American-DipperAmerican-Dipper
authored
Merge pull request #93517 from msmbaldwin/avk-track2
Track-2 SDK quickstart updates
2 parents 693aea0 + 2ef4b46 commit 0eac6c1

File tree

4 files changed

+564
-39
lines changed

4 files changed

+564
-39
lines changed

‎articles/key-vault/quick-create-net-v3.md

Lines changed: 208 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,208 @@
1+
---
2+
title: Quickstart - Azure Key Vault client library for .NET (SDK v3)
3+
description: Learn how to create, retrieve, and delete secrets from an Azure key vault using the .NET client library (v3)
4+
author: msmbaldwin
5+
ms.author: mbaldwin
6+
ms.date: 11/05/2019
7+
ms.service: key-vault
8+
ms.topic: quickstart
9+
10+
---
11+
12+
# Quickstart: Azure Key Vault client library for .NET (SDK v3)
13+
14+
Get started with the Azure Key Vault client library for .NET. Follow the steps below to install the package and try out example code for basic tasks.
15+
16+
> [!NOTE]
17+
> This quickstart uses the v3.0.4 version of the Microsoft.Azure.KeyVault client library. To use the most up-to-date version of the Key Vault client library, see [Azure Key Vault client library for .NET (SDK v4)](quick-create-net.md).
18+
19+
Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. Use the Key Vault client library for .NET to:
20+
21+
- Increase security and control over keys and passwords.
22+
- Create and import encryption keys in minutes.
23+
- Reduce latency with cloud scale and global redundancy.
24+
- Simplify and automate tasks for SSL/TLS certificates.
25+
- Use FIPS 140-2 Level 2 validated HSMs.
26+
27+
[API reference documentation](/dotnet/api/overview/azure/key-vault?view=azure-dotnet) | [Library source code](https://github.com/Azure/azure-sdk-for-net/tree/master/sdk/keyvault) | [Package (NuGet)](https://www.nuget.org/packages/Microsoft.Azure.KeyVault/)
28+
29+
> [!NOTE]
30+
> Each key vault must have a unique name. Replace <your-unique-keyvault-name> with the name of your key vault in the following examples.
31+
32+
33+
## Prerequisites
34+
35+
* An Azure subscription - [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
36+
* The [.NET Core 2.1 SDK or later](https://dotnet.microsoft.com/download/dotnet-core/2.1).
37+
* [Azure CLI](/cli/azure/install-azure-cli?view=azure-cli-latest) or [Azure PowerShell](/powershell/azure/overview)
38+
39+
This quickstart assumes you are running `dotnet`, [Azure CLI](/cli/azure/install-azure-cli?view=azure-cli-latest), and Windows commands in a Windows terminal (such as [PowerShell Core](/powershell/scripting/install/installing-powershell-core-on-windows?view=powershell-6), [Windows PowerShell](/powershell/scripting/install/installing-windows-powershell?view=powershell-6), or the [Azure Cloud Shell](https://shell.azure.com/)).
40+
41+
## Setting up
42+
43+
### Create new .NET console app
44+
45+
Create a new .NET Core application in your preferred editor or IDE.
46+
47+
In a console window, use the `dotnet new` command to create a new console app with the name `akv-dotnet`.
48+
49+
50+
```console
51+
dotnet new console -n akvdotnet
52+
```
53+
54+
Change your directory to the newly created app folder. You can build the application with:
55+
56+
```console
57+
dotnet build
58+
```
59+
60+
The build output should contain no warnings or errors.
61+
62+
```console
63+
Build succeeded.
64+
0 Warning(s)
65+
0 Error(s)
66+
```
67+
68+
### Install the package
69+
70+
From the console window, install the Azure Key Vault client library for .NET:
71+
72+
```console
73+
dotnet add package Microsoft.Azure.KeyVault
74+
```
75+
76+
For this quickstart, you will need to install the following packages as well:
77+
78+
```console
79+
dotnet add package System.Threading.Tasks
80+
dotnet add package Microsoft.IdentityModel.Clients.ActiveDirectory
81+
dotnet add package Microsoft.Azure.Management.ResourceManager.Fluent
82+
```
83+
84+
### Create a resource group and key vault
85+
86+
This quickstart uses a pre-created Azure key vault. You can create a key vault by following the steps in the [Azure CLI quickstart](quick-create-cli.md), [Azure PowerShell quickstart](quick-create-powershell.md), or [Azure portal quickstart](quick-create-portal.md). Alternatively, you can simply run the Azure CLI commands below.
87+
88+
> [!Important]
89+
> Each key vault must have a unique name. Replace <your-unique-keyvault-name> with the name of your key vault in the following examples.
90+
91+
```azurecli
92+
az group create --name "myResourceGroup" -l "EastUS"
93+
94+
az keyvault create --name <your-unique-keyvault-name> -g "myResourceGroup"
95+
```
96+
97+
### Create a service principal
98+
99+
The simplest way to authenticate an cloud-based .NET application is with a managed identity; see [Use an App Service managed identity to access Azure Key Vault](managed-identity.md) for details. For the sake of simplicity however, this quickstarts creates a .NET console application. Authenticating a desktop application with Azure requires the use of a service principal and an access control policy.
100+
101+
Create a service principle using the Azure CLI [az ad sp create-for-rbac](/cli/azure/ad/sp?view=azure-cli-latest#az-ad-sp-create-for-rbac) command:
102+
103+
```azurecli
104+
az ad sp create-for-rbac -n "http://mySP" --sdk-auth
105+
```
106+
107+
This operation will return a series of key / value pairs.
108+
109+
```console
110+
{
111+
"clientId": "7da18cae-779c-41fc-992e-0527854c6583",
112+
"clientSecret": "b421b443-1669-4cd7-b5b1-394d5c945002",
113+
"subscriptionId": "443e30da-feca-47c4-b68f-1636b75e16b3",
114+
"tenantId": "35ad10f1-7799-4766-9acf-f2d946161b77",
115+
"activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
116+
"resourceManagerEndpointUrl": "https://management.azure.com/",
117+
"activeDirectoryGraphResourceId": "https://graph.windows.net/",
118+
"sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
119+
"galleryEndpointUrl": "https://gallery.azure.com/",
120+
"managementEndpointUrl": "https://management.core.windows.net/"
121+
}
122+
```
123+
124+
Take note of the clientId and clientSecret, as we will use them in the [Authenticate to your key vault](#authenticate-to-your-key-vault) step below.
125+
126+
#### Give the service principal access to your key vault
127+
128+
Create an access policy for your key vault that grants permission to your service principal by passing the clientId to the [az keyvault set-policy](/cli/azure/keyvault?view=azure-cli-latest#az-keyvault-set-policy) command. Give the service principal get, list, and set permissions for both keys and secrets.
129+
130+
```azurecli
131+
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
132+
```
133+
134+
## Object model
135+
136+
The Azure Key Vault client library for .NET allows you to manage keys and related assets such as certificates and secrets. The code samples below will show you how to set a secret and retrieve a secret.
137+
138+
The entire console app is available at https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/akvdotnet.
139+
140+
## Code examples
141+
142+
### Add directives
143+
144+
Add the following directives to the top of your code:
145+
146+
[!code-csharp[Directives](~/samples-key-vault-dotnet-quickstart/akvdotnet/Program.cs?name=directives)]
147+
148+
### Authenticate to your key vault
149+
150+
This .NET quickstart relies on environment variables to store credentials that should not be put in code.
151+
152+
Before you build and run your app, use the `setx` command to set the `akvClientId`, `akvClientSecret`, `akvTenantId`, and `akvSubscriptionId` environment variables to the values you noted above.
153+
154+
```console
155+
setx akvClientId <your-clientID>
156+
157+
setx akvClientSecret <your-clientSecret>
158+
````
159+
160+
Each time you call `setx`, you should get a response of "SUCCESS: Specified value was saved."
161+
162+
Assign these environment variables to strings in your code, and then authenticate your application by passing them to the [KeyVaultClient class](/dotnet/api/microsoft.azure.keyvault.keyvaultclient):
163+
164+
[!code-csharp[Authentication](~/samples-key-vault-dotnet-quickstart/akvdotnet/Program.cs?name=authentication)]
165+
166+
### Save a secret
167+
168+
Now that your application is authenticated, you can put a secret into your keyvault using the [SetSecretAsync method](/dotnet/api/microsoft.azure.keyvault.keyvaultclientextensions.setsecretasync) This requires the URL of your key vault, which is in the form `https://<your-unique-keyvault-name>.vault.azure.net/secrets/`. It also requires a name for the secret -- we're using "mySecret". You may wish to assign these strings to a variables for reuse.
169+
170+
[!code-csharp[Set secret](~/samples-key-vault-dotnet-quickstart/akvdotnet/Program.cs?name=setsecret)]
171+
172+
You can verify that the secret has been set with the [az keyvault secret show](/cli/azure/keyvault/secret?view=azure-cli-latest#az-keyvault-secret-show) command:
173+
174+
```azurecli
175+
az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret
176+
```
177+
178+
### Retrieve a secret
179+
180+
You can now retrieve the previously set value with the [GetSecretAsync method](/dotnet/api/microsoft.azure.keyvault.keyvaultclientextensions.getsecretasync)
181+
182+
[!code-csharp[Get secret](~/samples-key-vault-dotnet-quickstart/akvdotnet/Program.cs?name=getsecret)]
183+
184+
Your secret is now saved as `keyvaultSecret.Value;`.
185+
186+
## Clean up resources
187+
188+
When no longer needed, you can use the Azure CLI or Azure PowerShell to remove your key vault and the corresponding resource group.
189+
190+
```azurecli
191+
az group delete -g "myResourceGroup" -l "EastUS"
192+
```
193+
194+
```azurepowershell
195+
Remove-AzResourceGroup -Name "myResourceGroup"
196+
```
197+
198+
## Next steps
199+
200+
In this quickstart you created a key vault, stored a secret, and retrieved that secret. See the [entire console app in GitHub](https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/akvdotnet).
201+
202+
To learn more about Key Vault and how to integrate it with your applications, continue on to the articles below.
203+
204+
- Implement [Service-to-service authentication to Azure Key Vault using .NET](service-to-service-authentication.md)
205+
- Read an [Overview of Azure Key Vault](key-vault-overview.md)
206+
- See the [Azure Key Vault developer's guide](key-vault-developers-guide.md)
207+
- Learn about [keys, secrets, and certificates](about-keys-secrets-and-certificates.md)
208+
- Review [Azure Key Vault best practices](key-vault-best-practices.md)

0 commit comments

Comments
 (0)