Skip to content

Commit

Permalink
Update docs metadata
Browse files Browse the repository at this point in the history
  • Loading branch information
@azure-sdk
azure-sdk committed Jan 14, 2022
1 parent 99db261 commit f98ee84
Show file tree
Hide file tree
Showing 2 changed files with 67 additions and 92 deletions.
155 changes: 65 additions & 90 deletions docs-ref-services/latest/security-keyvault-secrets-readme.md
View file
Original file line number Diff line number Diff line change
@@ -1,17 +1,16 @@
---
title: Azure Key Vault Secret client library for Java
keywords: Azure, java, SDK, API, azure-security-keyvault-secrets, keyvault
author: maggiepint
ms.author: magpint
ms.date: 11/15/2021
author: vcolin7
ms.author: vcolin7
ms.date: 01/14/2022
ms.topic: reference
ms.prod: azure
ms.technology: azure
ms.devlang: java
ms.service: keyvault
---

# Azure Key Vault Secret client library for Java - Version 4.3.5
# Azure Key Vault Secret client library for Java - Version 4.3.6

Azure Key Vault is a cloud service that provides secure storage for secrets, such as passwords and database connection strings.

Expand All @@ -30,7 +29,7 @@ Maven dependency for the Azure Key Vault Secrets client library. Add it to your
<dependency>
<groupId>com.azure</groupId>
<artifactId>azure-security-keyvault-secrets</artifactId>
<version>4.3.5</version>
<version>4.3.6</version>
</dependency>
```
[//]: # ({x-version-update-end})
Expand All @@ -41,9 +40,9 @@ Maven dependency for the Azure Key Vault Secrets client library. Add it to your
- [Azure Subscription][azure_subscription]
- An existing [Azure Key Vault][azure_keyvault]. If you need to create a Key Vault, you can use the [Azure Cloud Shell][azure_cloud_shell] to create one with this Azure CLI command. Replace `<your-resource-group-name>` and `<your-key-vault-name>` with your own, unique names:

```Bash
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```
```bash
az keyvault create --resource-group <your-resource-group-name> --name <your-key-vault-name>
```

### Authenticate the client
In order to interact with the Key Vault service, you'll need to create an instance of the [SecretClient](#create-secret-client) class. You would need a **vault url** and **client secret credentials (client id, client secret, tenant id)** to instantiate a client object using the `DefaultAzureCredential` examples shown in this document.
Expand All @@ -57,55 +56,51 @@ Here is an [Azure Cloud Shell][azure_cloud_shell] snippet below to

* Create a service principal and configure its access to Azure resources:

```Bash
az ad sp create-for-rbac -n <your-application-name> --skip-assignment
```
```bash
az ad sp create-for-rbac -n <your-application-name> --skip-assignment
```

Output:
Output:

```json
{
"appId": "generated-app-ID",
"displayName": "dummy-app-name",
"name": "http://dummy-app-name",
"password": "random-password",
"tenant": "tenant-ID"
}
```
```json
{
"appId": "generated-app-ID",
"displayName": "dummy-app-name",
"name": "http://dummy-app-name",
"password": "random-password",
"tenant": "tenant-ID"
}
```

* Use the above returned credentials information to set **AZURE_CLIENT_ID** (appId), **AZURE_CLIENT_SECRET** (password), and **AZURE_TENANT_ID** (tenant) environment variables. The following example shows a way to do this in Bash:

```Bash
export AZURE_CLIENT_ID="generated-app-ID"
export AZURE_CLIENT_SECRET="random-password"
export AZURE_TENANT_ID="tenant-ID"
```
```bash
export AZURE_CLIENT_ID="generated-app-ID"
export AZURE_CLIENT_SECRET="random-password"
export AZURE_TENANT_ID="tenant-ID"
````

* Grant the aforementioned application authorization to perform secret operations on the Key Vault:

```Bash
az keyvault set-policy --name <your-key-vault-name> --spn $AZURE_CLIENT_ID --secret-permissions backup delete get list set
```
```bash
az keyvault set-policy --name <your-key-vault-name> --spn $AZURE_CLIENT_ID --secret-permissions backup delete get list set
```

> --secret-permissions:
> Accepted values: backup, delete, get, list, purge, recover, restore, set
> --secret-permissions:
> Accepted values: backup, delete, get, list, purge, recover, restore, set

If you have enabled role-based access control (RBAC) for Key Vault instead, you can find roles like "Key Vault Secrets Officer" in our [RBAC guide][rbac_guide].
If you have enabled role-based access control (RBAC) for Key Vault instead, you can find roles like "Key Vault Secrets Officer" in our [RBAC guide][rbac_guide].

* Use the aforementioned Key Vault name to retrieve details of your Vault, which also contain your Key Vault URL:

```Bash
az keyvault show --name <your-key-vault-name>
```
```bash
az keyvault show --name <your-key-vault-name>
```

#### Create secret client
Once you've populated the **AZURE_CLIENT_ID**, **AZURE_CLIENT_SECRET**, and **AZURE_TENANT_ID** environment variables and replaced **your-key-vault-url** with the URI returned above, you can create the SecretClient:
```Java
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
```java readme-sample-createSecretClient
SecretClient secretClient = new SecretClientBuilder()
.vaultUrl("<your-key-vault-url>")
.credential(new DefaultAzureCredentialBuilder().build())
Expand Down Expand Up @@ -139,33 +134,23 @@ The following sections provide several code snippets covering some of the most c
Create a secret to be stored in the Azure Key Vault.
- `setSecret` creates a new secret in the Azure Key Vault. If a secret with the given name already exists then a new version of the secret is created.

```Java
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretClient;
import com.azure.security.keyvault.secrets.SecretClientBuilder;
import com.azure.security.keyvault.secrets.models.KeyVaultSecret;
SecretClient secretClient = new SecretClientBuilder()
.vaultUrl("<your-key-vault-url>")
.credential(new DefaultAzureCredentialBuilder().build())
.buildClient();
```java readme-sample-createSecret
KeyVaultSecret secret = secretClient.setSecret("<secret-name>", "<secret-value>");
System.out.printf("Secret created with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());
```
### Retrieve a secret
Retrieve a previously stored secret by calling `getSecret`.
```Java
```java readme-sample-retrieveSecret
KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue());
```
### Update an existing secret
Update an existing secret by calling `updateSecretProperties`.
```Java
```java readme-sample-updateSecret
// Get the secret to update.
KeyVaultSecret secret = secretClient.getSecret("<secret-name>");
// Update the expiry time of the secret.
Expand All @@ -177,7 +162,7 @@ System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.
### Delete a secret
Delete an existing secret by calling `beginDeleteSecret`.
```Java
```java readme-sample-deleteSecret
SyncPoller<DeletedSecret, Void> deletedSecretPoller = secretClient.beginDeleteSecret("<secret-name>");
// Deleted secret is accessible as soon as polling begins.
Expand All @@ -193,7 +178,7 @@ deletedSecretPoller.waitForCompletion();
### List secrets
List the secrets in the Azure Key Vault by calling `listPropertiesOfSecrets`.
```Java
```java readme-sample-listSecrets
// List operations don't return the secrets with value information. So, for each returned secret we call getSecret to
// get the secret with its value information.
for (SecretProperties secretProperties : secretClient.listPropertiesOfSecrets()) {
Expand All @@ -217,48 +202,38 @@ The following sections provide several code snippets covering some of the most c
Create a secret to be stored in the Azure Key Vault.
- `setSecret` creates a new secret in the Azure Key Vault. If a secret with the given name already exists then a new version of the secret is created.
```Java
import com.azure.identity.DefaultAzureCredentialBuilder;
import com.azure.security.keyvault.secrets.SecretAsyncClient;
import com.azure.security.keyvault.secrets.models.Secret;
SecretAsyncClient secretAsyncClient = new SecretClientBuilder()
.vaultUrl("<your-key-vault-url>")
.credential(new DefaultAzureCredentialBuilder().build())
.buildAsyncClient();
```java readme-sample-createSecretAsync
secretAsyncClient.setSecret("<secret-name>", "<secret-value>")
.subscribe(secret ->
System.out.printf("Created secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue()));
.subscribe(secret -> System.out.printf("Created secret with name \"%s\" and value \"%s\"%n",
secret.getName(), secret.getValue()));
```
### Retrieve a secret asynchronously
Retrieve a previously stored secret by calling `getSecret`.
```Java
```java readme-sample-retrieveSecretAsync
secretAsyncClient.getSecret("<secret-name>")
.subscribe(secret ->
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secret.getName(), secret.getValue()));
.subscribe(secret -> System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n",
secret.getName(), secret.getValue()));
```
### Update an existing secret asynchronously
Update an existing secret by calling `updateSecretProperties`.
```Java
```java readme-sample-updateSecretAsync
secretAsyncClient.getSecret("<secret-name>")
.subscribe(secret -> {
.flatMap(secret -> {
// Update the expiry time of the secret.
secret.getProperties().setExpiresOn(OffsetDateTime.now().plusDays(50));
secretAsyncClient.updateSecretProperties(secret.getProperties())
.subscribe(updatedSecretProperties ->
System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn()));
});
return secretAsyncClient.updateSecretProperties(secret.getProperties());
}).subscribe(updatedSecretProperties ->
System.out.printf("Secret's updated expiry time: %s%n", updatedSecretProperties.getExpiresOn()));
```
### Delete a secret asynchronously
Delete an existing secret by calling `beginDeleteSecret`.
```Java
```java readme-sample-deleteSecretAsync
secretAsyncClient.beginDeleteSecret("<secret-name>")
.subscribe(pollResponse -> {
System.out.printf("Deletion status: %s%n", pollResponse.getStatus());
Expand All @@ -270,24 +245,24 @@ secretAsyncClient.beginDeleteSecret("<secret-name>")
### List secrets asynchronously
List the secrets in the Azure Key Vault by calling `listPropertiesOfSecrets`.
```Java
```java readme-sample-listSecretsAsync
// The List secrets operation returns secrets without their value, so for each secret returned we call `getSecret`
// to get its value as well.
secretAsyncClient.listPropertiesOfSecrets()
.subscribe(secretProperties ->
secretAsyncClient.getSecret(secretProperties.getName(), secretProperties.getVersion())
.subscribe(secretResponse ->
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretResponse.getName(),
secretResponse.getValue())));
.flatMap(secretProperties ->
secretAsyncClient.getSecret(secretProperties.getName(), secretProperties.getVersion()))
.subscribe(secretResponse ->
System.out.printf("Retrieved secret with name \"%s\" and value \"%s\"%n", secretResponse.getName(),
secretResponse.getValue()));
```
## Troubleshooting
### General
Azure Key Vault Secret clients raise exceptions. For example, if you try to retrieve a secret after it is deleted a `404` error is returned, indicating the resource was not found. In the following snippet, the error is handled gracefully by catching the exception and displaying additional information about the error.
```java
```java readme-sample-troubleshooting
try {
secretClient.getSecret("<deleted-secret-name>")
secretClient.getSecret("<deleted-secret-name>");
} catch (ResourceNotFoundException e) {
System.out.println(e.getMessage());
}
Expand Down Expand Up @@ -316,9 +291,9 @@ When you submit a pull request, a CLA-bot will automatically determine whether y
This project has adopted the [Microsoft Open Source Code of Conduct][microsoft_code_of_conduct]. For more information see the Code of Conduct FAQ or contact <opencode@microsoft.com> with any additional questions or comments.
<!-- LINKS -->
[source_code]: https://github.com/Azure/azure-sdk-for-java/blob/azure-security-keyvault-secrets_4.3.5/sdk/keyvault/azure-security-keyvault-secrets/src
[source_code]: https://github.com/Azure/azure-sdk-for-java/blob/azure-security-keyvault-secrets_4.3.6/sdk/keyvault/azure-security-keyvault-secrets/src
[api_documentation]: https://azure.github.io/azure-sdk-for-java
[azure_identity]: https://github.com/Azure/azure-sdk-for-java/tree/azure-security-keyvault-secrets_4.3.5/sdk/identity/azure-identity
[azure_identity]: https://github.com/Azure/azure-sdk-for-java/tree/azure-security-keyvault-secrets_4.3.6/sdk/identity/azure-identity
[azkeyvault_docs]: https://docs.microsoft.com/azure/key-vault/
[maven]: https://maven.apache.org/
[azure_subscription]: https://azure.microsoft.com/
Expand All @@ -329,8 +304,8 @@ This project has adopted the [Microsoft Open Source Code of Conduct][microsoft_c
[azure_create_application_in_portal]: https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
[azure_keyvault_cli]: https://docs.microsoft.com/azure/key-vault/quick-create-cli
[azure_keyvault_cli_full]: https://docs.microsoft.com/cli/azure/keyvault?view=azure-cli-latest
[secrets_samples]: https://github.com/Azure/azure-sdk-for-java/blob/azure-security-keyvault-secrets_4.3.5/sdk/keyvault/azure-security-keyvault-secrets/src/samples/java/com/azure/security/keyvault/secrets
[samples]: https://github.com/Azure/azure-sdk-for-java/blob/azure-security-keyvault-secrets_4.3.5/sdk/keyvault/azure-security-keyvault-secrets/src/samples/README.md
[secrets_samples]: https://github.com/Azure/azure-sdk-for-java/blob/azure-security-keyvault-secrets_4.3.6/sdk/keyvault/azure-security-keyvault-secrets/src/samples/java/com/azure/security/keyvault/secrets
[samples]: https://github.com/Azure/azure-sdk-for-java/blob/azure-security-keyvault-secrets_4.3.6/sdk/keyvault/azure-security-keyvault-secrets/src/samples/README.md
[performance_tuning]: https://github.com/Azure/azure-sdk-for-java/wiki/Performance-Tuning
[jdk_link]: https://docs.microsoft.com/java/azure/jdk/?view=azure-java-stable
[azure_cloud_shell]: https://shell.azure.com/bash
Expand Down
4 changes: 2 additions & 2 deletions metadata/latest/azure-security-keyvault-secrets.json
View file
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
{
"Name": "azure-security-keyvault-secrets",
"Version": "4.3.5",
"Version": "4.3.6",
"DevVersion": null,
"DirectoryPath": "sdk/keyvault/azure-security-keyvault-secrets",
"ServiceDirectory": "keyvault",
Expand All @@ -10,5 +10,5 @@
"SdkType": "client",
"IsNewSdk": true,
"ArtifactName": "azure-security-keyvault-secrets",
"ReleaseStatus": "2021-11-12"
"ReleaseStatus": "2022-01-12"
}

0 comments on commit f98ee84

Please sign in to comment.