Skip to content

Commit ca23d23

Browse files
author
Aditya Abhishek
committed
add doc
1 parent aecef69 commit ca23d23

2 files changed

Lines changed: 170 additions & 0 deletions

File tree

‎website/docs/guides/0010-command-line.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -17,6 +17,7 @@ on the system.
1717
| [**Deprecating with --logger**]--eh, --eventhub, --event-hub=\<authtoken\> | No | string/connection string | A full connection description for an [Azure Event Hub namespace](./0610-integration-event-hub.md) to send/upload telemetry data from the operations of the Virtual Client.<br/><br/>The following are supported identifiers for this option:<br/><ul><li>Event Hub namespace shared access policies</li><li>Microsoft Entra ID/Apps using a certificate</li><li>Microsoft Azure managed identities</li></ul>See [Azure Event Hub Integration](./0610-integration-event-hub.md) for additional details on supported identifiers.<br/><br/><mark>Always surround connection descriptions with quotation marks.</mark> |
1818
| --e, --experiment, --experiment-id=\<guid\> | No | guid | A unique identifier that defines the ID of the experiment for which the Virtual Client workload is associated. |
1919
| --ff, --fail-fast | No | | Flag indicates that the application should exit immediately on first/any errors regardless of their severity. This applies to 'Actions' in the profile only. 'Dependencies' are ALWAYS implemented to fail fast. 'Monitors' are generally implemented to handle transient issues and to keep running/trying in the background. |
20+
| --kv, --keyvault, --key-vault=\<authtoken\> | No | uri string/connection string | A full connection description for an [Azure Key Vault](./0620-integration-key-vault.md) to use for referencing secrets and certificates from azure keyvault.<br/><br/>The following are supported identifiers for this option:<br/><ul><li>Microsoft Entra ID/Apps using a certificate</li><li>Microsoft Azure managed identities</li></ul>See [Azure Key Vault Integration](./0620-integration-key-vault.md) for additional details on supported identifiers.<br/><br/><mark>Always surround connection descriptions with quotation marks.</mark> |
2021
| --lp, --layout, --layout-path=\<path\> | No | string/path | A path to a environment layout file that provides additional metadata about the system/hardware on which the Virtual Client will run and information required to support client/server advanced topologies. See [Client/Server Support](./0020-client-server.md). |
2122
| --logger=\<logger definition\> | No | string/path | One or more logger definition string. Allows defining multiple loggers and their definitions on command line. Defaults to console logger and file logger. |
2223
| --ldir, --log-dir=\<path\> | No | string/path | Defines an alternate directory to which log files should be written. |

‎website/docs/guides/0620-integration-key-vault.md‎

Lines changed: 169 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,169 @@
1+
# Azure Key Vault Integration
2+
3+
Azure Key Vault is a secure cloud service for storing and accessing secrets, keys, and certificates. Virtual Client supports integration with Azure Key Vault, allowing you to retrieve secrets and certificates for use in your workloads, monitors, automation, and telemetry scenarios.
4+
5+
This guide covers the requirements, supported authentication methods, command-line options, and usage examples for integrating Azure Key Vault with Virtual Client.
6+
7+
---
8+
9+
## Table of Contents
10+
11+
- [Overview](#overview)
12+
- [Authentication Preliminaries](#authentication-preliminaries)
13+
- [Certificates on Linux](#referencing-certificates-on-linux)
14+
- [Certificates on Windows](#referencing-certificates-on-windows)
15+
- [Key Vault Integration](#key-vault-integration)
16+
- [Supported Reference Styles](#supported-reference-styles)
17+
- [URI-Style References](#uri-style-references)
18+
- [Connection String-Style References](#connection-string-style-references)
19+
- [Command-Line Options](#command-line-options)
20+
- [Usage Examples](#usage-examples)
21+
- [Error Handling](#error-handling)
22+
- [Best Practices](#best-practices)
23+
- [References](#references)
24+
25+
---
26+
27+
## Overview
28+
29+
Virtual Client can retrieve secrets and certificates from Azure Key Vault for use in authentication, secure configuration, and workload execution. You can specify a Key Vault endpoint or connection string using command-line options. Virtual Client supports both Microsoft Entra ID (formerly Azure AD) and Managed Identity authentication.
30+
31+
---
32+
33+
## Authentication Preliminaries
34+
35+
### Referencing Certificates on Linux
36+
37+
Virtual Client is a .NET application. Certificates used on a Linux system must be X.509 certificates containing a private key (e.g., PKCS#12, *.pfx). Certificates must be installed in the expected location for the user running Virtual Client:
38+
39+
- **Root:** `/root/.dotnet/corefx/cryptography/x509stores/my/`
40+
- **Specific User:** `/home/{user}/.dotnet/corefx/cryptography/x509stores/my/`
41+
42+
Ensure the user has read/write access to this directory and the certificate files. Set permissions as follows:
43+
44+
sudo chmod -R 700 /home/{user}/.dotnet/corefx/cryptography/x509stores/my/
45+
46+
### Referencing Certificates on Windows
47+
48+
Virtual Client will look for certificates in these stores:
49+
50+
- **CurrentUser/Personal:** The personal certificate store for the current user.
51+
- **LocalMachine/Personal:** The local machine certificate store.
52+
53+
It is recommended to install certificates into the user-specific store.
54+
55+
---
56+
57+
## Key Vault Integration
58+
59+
Virtual Client supports referencing Azure Key Vault using both URI-style and connection string-style formats. The Key Vault can be used to retrieve secrets (e.g., API keys, passwords) and certificates for use in your workloads.
60+
61+
### Supported Reference Styles
62+
63+
#### URI-Style References
64+
65+
You can specify the Key Vault endpoint as a URI, optionally with authentication parameters:
66+
67+
- **Microsoft Entra ID/App with Certificate (by thumbprint):**
68+
69+
``` bash
70+
--keyvault="https://myvault.vault.azure.net?cid={clientId}&tid={tenantId}&crtt={certificateThumbprint}"
71+
```
72+
73+
- **Microsoft Entra ID/App with Certificate (by issuer and subject):**
74+
75+
``` bash
76+
--keyvault="https://myvault.vault.azure.net?cid={clientId}&tid={tenantId}&crti={issuer}&crts={subject}"
77+
```
78+
79+
- **Managed Identity:**
80+
81+
``` bash
82+
--keyvault="https://myvault.vault.azure.net?miid={managedIdentityClientId}"
83+
```
84+
85+
#### Connection String-Style References
86+
87+
You can also use a connection string format:
88+
89+
- **Microsoft Entra ID/App with Certificate (by thumbprint):**
90+
91+
``` bash
92+
--keyvault="EndpointUrl=https://myvault.vault.azure.net;ClientId={clientId};TenantId={tenantId};CertificateThumbprint={certificateThumbprint}"
93+
```
94+
95+
- **Microsoft Entra ID/App with Certificate (by issuer and subject):**
96+
97+
``` bash
98+
--keyvault="EndpointUrl=https://myvault.vault.azure.net;ClientId={clientId};TenantId={tenantId};CertificateIssuer={issuer};CertificateSubject={subject}"
99+
```
100+
101+
- **Managed Identity:**
102+
103+
``` bash
104+
--keyvault="EndpointUrl=https://myvault.vault.azure.net;ManagedIdentityId={managedIdentityClientId}"
105+
```
106+
107+
---
108+
109+
## Command-Line Options
110+
111+
The following options are available for Key Vault integration:
112+
113+
- `--kv`, `--keyvault`, `--key-vault`, `--keyVault`, `--key-Vault`
114+
- **Description:** Specifies the Azure Key Vault endpoint or connection string.
115+
- **Example:** `--keyvault="https://myvault.vault.azure.net"`
116+
117+
Other options may be used depending on your authentication method (see above).
118+
119+
---
120+
121+
## Usage Examples
122+
123+
### Retrieve a Secret Using Managed Identity
124+
125+
``` bash
126+
VirtualClient --keyvault="https://myvault.vault.azure.net?miid=6d3c5db8-e14b-44b7-9887-d168b5f659f6" --other-options
127+
```
128+
129+
### Retrieve a Secret Using Microsoft Entra ID and Certificate Thumbprint
130+
131+
``` bash
132+
VirtualClient --keyvault="EndpointUrl=https://myvault.vault.azure.net;ClientId=08331e3b-1458-4de2-b1d6-7007bc7221d5;TenantId=573b5dBbe-c477-4a10-8986-a7fe10e2d79B;CertificateThumbprint=f5b114e61c6a81b40c1e7a5e4d11ac47da6e445f" --other-options
133+
```
134+
135+
### Retrieve a Secret Using Microsoft Entra ID and Certificate Issuer/Subject
136+
137+
``` bash
138+
VirtualClient --keyvault="EndpointUrl=https://myvault.vault.azure.net;ClientId=08331e3b-1458-4de2-b1d6-7007bc7221d5;TenantId=573b5dBbe-c477-4a10-8986-a7fe10e2d79B;CertificateIssuer=CN=ABC CA 01, DC=ABC, DC=COM;CertificateSubject=CN=any.domain.com" --other-options
139+
```
140+
141+
---
142+
143+
## Error Handling
144+
145+
Virtual Client will report errors if:
146+
147+
- The Key Vault endpoint or credentials are invalid.
148+
- The specified secret or certificate is not found.
149+
- Permissions are insufficient (e.g., forbidden).
150+
- The certificate is missing or inaccessible.
151+
152+
Refer to the logs for detailed error messages. See unit tests in `KeyVaultManagerTests.cs` for expected error handling scenarios.
153+
154+
---
155+
156+
## Best Practices
157+
158+
- Use Managed Identity where possible for secure, passwordless authentication.
159+
- Store certificates securely and restrict access to certificate files.
160+
- Grant only necessary permissions to the Key Vault and its secrets/certificates.
161+
- Test your Key Vault integration using the provided unit tests and error scenarios.
162+
163+
---
164+
165+
## References
166+
167+
- [Azure Key Vault Documentation](https://learn.microsoft.com/en-us/azure/key-vault/)
168+
- [Virtual Client Command-Line Reference](https://microsoft.github.io/VirtualClient/docs/guides/0010-command-line/)
169+

0 commit comments

Comments
 (0)