Skip to content

Commit 83845c0

Browse files
itechedititechedit
authored
Merge pull request #96189 from msmbaldwin/avk-track2
Java quickstart (+ cleanup on other quickstarts)
2 parents 3b75607 + 1abc159 commit 83845c0

File tree

4 files changed

+325
-15
lines changed

4 files changed

+325
-15
lines changed

‎articles/key-vault/quick-create-java.md

Lines changed: 315 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,315 @@
1+
---
2+
title: Quickstart - Azure Key Vault client library for Java
3+
description: Provides format and content criteria for writing Quickstarts for Azure SDK client libraries.
4+
author: msmbaldwin
5+
ms.author: mbaldwin
6+
ms.date: 10/20/2019
7+
ms.service: key-vault
8+
ms.topic: quickstart
9+
10+
---
11+
12+
# Quickstart: Azure Key Vault client library for Java
13+
14+
Get started with the Azure Key Vault client library for Java. Follow the steps below to install the package and try out example code for basic tasks.
15+
16+
Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud applications and services. Use the Key Vault client library for Java to:
17+
18+
- Increase security and control over keys and passwords.
19+
- Create and import encryption keys in minutes.
20+
- Reduce latency with cloud scale and global redundancy.
21+
- Simplify and automate tasks for SSL/TLS certificates.
22+
- Use FIPS 140-2 Level 2 validated HSMs.
23+
24+
[Source code](https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/keyvault) | [API reference documentation](https://azure.github.io/azure-sdk-for-java) | [Product documentation](index.yml) | [Samples](https://github.com/Azure/azure-sdk-for-java/tree/master/sdk/keyvault/azure-security-keyvault-secrets/src/samples/java/com/azure/security/keyvault/secrets)
25+
26+
## Prerequisites
27+
28+
- An Azure subscription - [create one for free](https://azure.microsoft.com/free/?WT.mc_id=A261C142F).
29+
- [Java Development Kit (JDK)](/java/azure/jdk/?view=azure-java-stable) version 8 or above
30+
- [Apache Maven](https://maven.apache.org)
31+
- [Azure CLI](/cli/azure/install-azure-cli?view=azure-cli-latest) or [Azure PowerShell](/powershell/azure/overview)
32+
33+
This quickstart assumes you are running [Azure CLI](/cli/azure/install-azure-cli?view=azure-cli-latest) and [Apache Maven](https://maven.apache.org) in a Linux terminal window.
34+
35+
## Setting up
36+
37+
### Create new Java console app
38+
39+
In a console window, use the `mvn` command to create a new Java console app with the name `akv-java`.
40+
41+
```console
42+
mvn archetype:generate -DgroupId=com.keyvault.quickstart
43+
-DartifactId=akv-java
44+
-DarchetypeArtifactId=maven-archetype-quickstart
45+
-DarchetypeVersion=1.4
46+
-DinteractiveMode=false
47+
```
48+
49+
The output from generating the project will look something like this:
50+
51+
```console
52+
[INFO] ----------------------------------------------------------------------------
53+
[INFO] Using following parameters for creating project from Archetype: maven-archetype-quickstart:1.4
54+
[INFO] ----------------------------------------------------------------------------
55+
[INFO] Parameter: groupId, Value: com.keyvault.quickstart
56+
[INFO] Parameter: artifactId, Value: akv-java
57+
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
58+
[INFO] Parameter: package, Value: com.keyvault.quickstart
59+
[INFO] Parameter: packageInPathFormat, Value: com/keyvault/quickstart
60+
[INFO] Parameter: package, Value: com.keyvault.quickstart
61+
[INFO] Parameter: groupId, Value: com.keyvault.quickstart
62+
[INFO] Parameter: artifactId, Value: akv-java
63+
[INFO] Parameter: version, Value: 1.0-SNAPSHOT
64+
[INFO] Project created from Archetype in dir: /home/user/quickstarts/akv-java
65+
[INFO] ------------------------------------------------------------------------
66+
[INFO] BUILD SUCCESS
67+
[INFO] ------------------------------------------------------------------------
68+
[INFO] Total time: 38.124 s
69+
[INFO] Finished at: 2019-11-15T13:19:06-08:00
70+
[INFO] ------------------------------------------------------------------------
71+
```
72+
73+
Change your directory to the newly created akv-java/ folder.
74+
75+
```console
76+
cd akv-java
77+
```
78+
79+
### Install the package
80+
81+
Open the *pom.xml* file in your text editor. Add the following dependency elements to the group of dependencies.
82+
83+
```xml
84+
<dependency>
85+
<groupId>com.azure</groupId>
86+
<artifactId>azure-security-keyvault-secrets</artifactId>
87+
<version>4.0.0</version>
88+
</dependency>
89+
90+
<dependency>
91+
<groupId>com.azure</groupId>
92+
<artifactId>azure-identity</artifactId>
93+
<version>1.0.0</version>
94+
</dependency>
95+
```
96+
97+
### Create a resource group and key vault
98+
99+
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 run the Azure CLI commands below.
100+
101+
> [!Important]
102+
> Each key vault must have a unique name. Replace <your-unique-keyvault-name> with the name of your key vault in the following examples.
103+
104+
```azurecli
105+
az group create --name "myResourceGroup" -l "EastUS"
106+
107+
az keyvault create --name <your-unique-keyvault-name> -g "myResourceGroup"
108+
```
109+
110+
### Create a service principal
111+
112+
The simplest way to authenticate a cloud-based 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 quickstart creates a desktop application, which requires the use of a service principal and an access control policy.
113+
114+
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:
115+
116+
```azurecli
117+
az ad sp create-for-rbac -n "http://mySP" --sdk-auth
118+
```
119+
120+
This operation will return a series of key / value pairs.
121+
122+
```console
123+
{
124+
"clientId": "7da18cae-779c-41fc-992e-0527854c6583",
125+
"clientSecret": "b421b443-1669-4cd7-b5b1-394d5c945002",
126+
"subscriptionId": "443e30da-feca-47c4-b68f-1636b75e16b3",
127+
"tenantId": "35ad10f1-7799-4766-9acf-f2d946161b77",
128+
"activeDirectoryEndpointUrl": "https://login.microsoftonline.com",
129+
"resourceManagerEndpointUrl": "https://management.azure.com/",
130+
"activeDirectoryGraphResourceId": "https://graph.windows.net/",
131+
"sqlManagementEndpointUrl": "https://management.core.windows.net:8443/",
132+
"galleryEndpointUrl": "https://gallery.azure.com/",
133+
"managementEndpointUrl": "https://management.core.windows.net/"
134+
}
135+
```
136+
137+
Take note of the clientId, clientSecret, and tenantId, as we will use them in the next two steps.
138+
139+
#### Give the service principal access to your key vault
140+
141+
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.
142+
143+
```azurecli
144+
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
145+
```
146+
147+
#### Set environmental variables
148+
149+
The DefaultAzureCredential method in our application relies on three environmental variables: `AZURE_CLIENT_ID`, `AZURE_CLIENT_SECRET`, and `AZURE_TENANT_ID`. use set these variables to the clientId, clientSecret, and tenantId values you noted in the [Create a service principal](#create-a-service-principal) step, above. Use the `export VARNAME=VALUE` format to set your environmental variables. (This method only sets the variables for your current shell and processes created from the shell; to permanently add these variables to your environment, edit your `/etc/environment ` file.)
150+
151+
You will also need to save your key vault name as an environment variable called `KEY_VAULT_NAME`.
152+
153+
```console
154+
export AZURE_CLIENT_ID=<your-clientID>
155+
156+
export AZURE_CLIENT_SECRET=<your-clientSecret>
157+
158+
export AZURE_TENANT_ID=<your-tenantId>
159+
160+
export KEY_VAULT_NAME=<your-key-vault-name>
161+
````
162+
163+
## Object model
164+
165+
The Azure Key Vault client library for Java allows you to manage keys and related assets such as certificates and secrets. The code samples below will show you how to create a client, set a secret, retrieve a secret, and delete a secret.
166+
167+
The entire console app is available at https://github.com/Azure-Samples/key-vault-dotnet-core-quickstart/tree/master/key-vault-console-app.
168+
169+
## Code examples
170+
171+
### Add directives
172+
173+
Add the following directives to the top of your code:
174+
175+
```java
176+
import com.azure.identity.DefaultAzureCredentialBuilder;
177+
178+
import com.azure.security.keyvault.secrets.SecretClient;
179+
import com.azure.security.keyvault.secrets.SecretClientBuilder;
180+
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
181+
```
182+
183+
### Authenticate and create a client
184+
185+
Authenticating to your key vault and creating a key vault client depends on the environmental variables in the [Set environmental variables](#set-environmental-variables) step above. The name of your key vault is expanded to the key vault URI, in the format `https://<your-key-vault-name>.vault.azure.net`.
186+
187+
```java
188+
String keyVaultName = System.getenv("KEY_VAULT_NAME");
189+
String kvUri = "https://" + keyVaultName + ".vault.azure.net";
190+
191+
SecretClient secretClient = new SecretClientBuilder()
192+
.vaultUrl(kvUri)
193+
.credential(new DefaultAzureCredentialBuilder().build())
194+
.buildClient();
195+
```
196+
197+
### Save a secret
198+
199+
Now that your application is authenticated, you can put a secret into your keyvault using the `secretClient.setSecret` method. This requires a name for the secret -- we've assigned the value "mySecret" to the `secretName` variable in this sample.
200+
201+
```java
202+
secretClient.setSecret(new KeyVaultSecret(secretName, secretValue));
203+
```
204+
205+
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:
206+
207+
```azurecli
208+
az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret
209+
```
210+
211+
### Retrieve a secret
212+
213+
You can now retrieve the previously set value with the `secretClient.getSecret` method.
214+
215+
```java
216+
KeyVaultSecret retrievedSecret = secretClient.getSecret(secretName);
217+
```
218+
219+
You can now access the value of the retrieved secret with `retrievedSecret.getValue()`.
220+
221+
### Delete a secret
222+
223+
Finally, let's delete the secret from your key vault with the `secretClient.beginDeleteSecret` method.
224+
225+
```java
226+
secretClient.beginDeleteSecret(secretName);
227+
```
228+
229+
You can verify that the secret is gone with the [az keyvault secret show](/cli/azure/keyvault/secret?view=azure-cli-latest#az-keyvault-secret-show) command:
230+
231+
```azurecli
232+
az keyvault secret show --vault-name <your-unique-keyvault-name> --name mySecret
233+
```
234+
235+
## Clean up resources
236+
237+
When no longer needed, you can use the Azure CLI or Azure PowerShell to remove your key vault and the corresponding resource group.
238+
239+
```azurecli
240+
az group delete -g "myResourceGroup" -l "EastUS"
241+
```
242+
243+
```azurepowershell
244+
Remove-AzResourceGroup -Name "myResourceGroup"
245+
```
246+
247+
## Sample code
248+
249+
```java
250+
package com.keyvault.quickstart;
251+
252+
import java.io.Console;
253+
254+
import com.azure.identity.DefaultAzureCredentialBuilder;
255+
256+
import com.azure.security.keyvault.secrets.SecretClient;
257+
import com.azure.security.keyvault.secrets.SecretClientBuilder;
258+
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
259+
260+
public class App {
261+
262+
public static void main(String[] args) throws InterruptedException, IllegalArgumentException {
263+
264+
String keyVaultName = System.getenv("KEY_VAULT_NAME");
265+
String kvUri = "https://" + keyVaultName + ".vault.azure.net";
266+
267+
System.out.printf("key vault name = %s and kv uri = %s \n", keyVaultName, kvUri);
268+
269+
SecretClient secretClient = new SecretClientBuilder()
270+
.vaultUrl(kvUri)
271+
.credential(new DefaultAzureCredentialBuilder().build())
272+
.buildClient();
273+
274+
275+
Console con = System.console();
276+
277+
String secretName = "mySecret";
278+
279+
System.out.println("Input the value of your secret > ");
280+
String secretValue = con.readLine();
281+
282+
System.out.print("Creating a secret in " + keyVaultName + " called '" + secretName + "' with the value '" + secretValue + "` ... ");
283+
284+
secretClient.setSecret(new KeyVaultSecret(secretName, secretValue));
285+
286+
System.out.println("done.");
287+
288+
System.out.println("Forgetting your secret.");
289+
secretValue = "";
290+
System.out.println("Your secret is '" + secretValue + "'.");
291+
292+
System.out.println("Retrieving your secret from " + keyVaultName + ".");
293+
294+
KeyVaultSecret retrievedSecret = secretClient.getSecret(secretName);
295+
296+
System.out.println("Your secret is '" + retrievedSecret.getValue() + "'.");
297+
System.out.print("Deleting your secret from " + keyVaultName + " ... ");
298+
299+
secretClient.beginDeleteSecret(secretName);
300+
301+
System.out.println("done.");
302+
303+
304+
}
305+
}
306+
```
307+
308+
## Next steps
309+
310+
In this quickstart you created a key vault, stored a secret, and retrieved that secret. To learn more about Key Vault and how to integrate it with your applications, continue on to the articles below.
311+
312+
- Read an [Overview of Azure Key Vault](key-vault-overview.md)
313+
- See the [Azure Key Vault developer's guide](key-vault-developers-guide.md)
314+
- Learn about [keys, secrets, and certificates](about-keys-secrets-and-certificates.md)
315+
- Review [Azure Key Vault best practices](key-vault-best-practices.md)

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

Lines changed: 3 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -42,9 +42,7 @@ This quickstart assumes you are running `dotnet`, [Azure CLI](/cli/azure/install
4242

4343
### Create new .NET console app
4444

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`.
45+
In a console window, use the `dotnet new` command to create a new .NET console app with the name `akv-dotnet`.
4846

4947

5048
```console
@@ -96,7 +94,7 @@ az keyvault create --name <your-unique-keyvault-name> -g "myResourceGroup"
9694

9795
### Create a service principal
9896

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.
97+
The simplest way to authenticate a 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 quickstart creates a .NET console application. Authenticating a desktop application with Azure requires the use of a service principal and an access control policy.
10098

10199
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:
102100

@@ -165,7 +163,7 @@ Assign these environment variables to strings in your code, and then authenticat
165163

166164
### Save a secret
167165

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.
166+
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".
169167

170168
[!code-csharp[Set secret](~/samples-key-vault-dotnet-quickstart/akvdotnet/Program.cs?name=setsecret)]
171169

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

Lines changed: 3 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -21,7 +21,7 @@ Azure Key Vault helps safeguard cryptographic keys and secrets used by cloud app
2121
- Simplify and automate tasks for SSL/TLS certificates.
2222
- Use FIPS 140-2 Level 2 validated HSMs.
2323

24-
[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/Azure.Security.KeyVault.Secrets/)
24+
[API reference documentation](/dotnet/api/azure.security.keyvault.secrets?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/Azure.Security.KeyVault.Secrets/)
2525

2626
## Prerequisites
2727

@@ -35,10 +35,7 @@ This quickstart assumes you are running `dotnet`, [Azure CLI](/cli/azure/install
3535

3636
### Create new .NET console app
3737

38-
Create a new .NET Core application in your preferred editor or IDE.
39-
40-
In a console window, use the `dotnet new` command to create a new console app with the name `akv-dotnet`.
41-
38+
In a console window, use the `dotnet new` command to create a new .NET console app with the name `akv-dotnet`.
4239

4340
```console
4441
dotnet new console -n key-vault-console-app
@@ -87,7 +84,7 @@ az keyvault create --name <your-unique-keyvault-name> -g "myResourceGroup"
8784

8885
### Create a service principal
8986

90-
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.
87+
The simplest way to authenticate a 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 quickstart creates a .NET console application. Authenticating a desktop application with Azure requires the use of a service principal and an access control policy.
9188

9289
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:
9390

0 commit comments

Comments
 (0)