Skip to content

Commit f5e02f2

Browse files
stijnmoreelsstijnmoreels
authoredMay 7, 2024··
docs: publish v2.0.0 feature docs (#429)
1 parent 143aaa8 commit f5e02f2

21 files changed

+1804
-0
lines changed
 

‎docs/versioned_docs/version-v2.0.0/02-Guides/add-secret-store-with-keyvault-integration.md

+139
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,139 @@
1+
---
2+
title: "Add secret store with Azure Key Vault integration"
3+
layout: default
4+
---
5+
6+
# Add secret store with Azure Key Vault integration
7+
The Arcus secret store is a alternative on the general usage of storing secrets in the application configuration (`IConfiguration`). It is important in application development to differentiate between configuration data and sensitive information like secrets. The Arcus secret store is extremely flexible and can be extended to support several secret providers to retrieve its secrets - both built-in as well as custom.
8+
9+
The secret store can be added during any part of de application lifetime. Once added, you can benefit from the safe and convenient way of secret retrieval that is the Arcus secret store.
10+
11+
This user guide will cover how the Arcus secret store can be added to an existing API application in order to retrieve secrets from Azure Key Vault.
12+
13+
## Terminology
14+
To fully understand the power of the secret store, some terminology has to be understood:
15+
- **Secret**: piece of sensitive information like access keys or connection strings; anything that is private and cannot be made public
16+
- **Secret store**: central place where the application retrieve its secrets.
17+
- **Secret provider**: implementation that provides secrets to the secret store (ex.: Azure Key Vault secret provider), many secret providers can be configured within a secret store.
18+
19+
## Sample application
20+
In this user guide, a fictive API application will be used to add the secret store to. We will be working with two major parts.
21+
22+
The initial place where the application will be started:
23+
```csharp
24+
public class Program
25+
{
26+
public static void Main(string[] args)
27+
{
28+
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
29+
builder.Configuration.AddJsonFile("appsettings.json");
30+
31+
WebApplication app = builder.Build();
32+
app.UseRouting();
33+
app.Run();
34+
}
35+
}
36+
```
37+
38+
And the API controller where a secret is being used:
39+
```csharp
40+
[ApiController]
41+
public class OrderController : ControllerBase
42+
{
43+
private readonly IConfiguration _configuration;
44+
45+
public OrderController(IConfiguration configuration)
46+
{
47+
_configuration = configuration;
48+
}
49+
50+
[HttpPost]
51+
public async Task Post([FromBody] Order order)
52+
{
53+
string connectionString = _configuration["Azure:ServiceBus:ConnectionString"];
54+
55+
// Post Order to Azure Service Bus...
56+
}
57+
}
58+
```
59+
60+
> Note that in this example, we use the application configuration to retrieve the Azure Service Bus connection string to post the incoming order to Azure Service Bus and not the Arcus secret store.
61+
62+
## Use Arcus secret store
63+
For us to move away from the application configuration, we need to make use of the Arcus secret store. The following step instructions will guide you in this process:
64+
65+
### 1. Install Arcus security
66+
For this example, we will be using Azure Key Vault as our single secret provider in the secret store, so we can install this directly:
67+
```shell
68+
PM > Install-Package Arcus.Security.Providers.AzureKeyVault
69+
```
70+
71+
> Note that this package depends on the `Arcus.Security.Core` package, where the secret store exists.
72+
73+
### 2. Add Arcus secret store to application
74+
Once the package is installed, add the secret store via extensions to the API application:
75+
* 2.1 Use the `.ConfigureSecretStore` to setup the secret store with necessary secret providers
76+
* 2.2 Use the the `.AddAzureKeyVaultWithManagedIdentity` to add the Azure Key Vault secret provider to the secret store
77+
78+
```csharp
79+
using Arcus.Security.Core.Caching.Configuration;
80+
81+
public class Program
82+
{
83+
public static void Main(string[] args)
84+
{
85+
WebApplicationBuilder builder = WebApplication.CreateBuilder(args);
86+
builder.Configuration.AddJsonFile("appsettings.json");
87+
88+
builder.Host.ConfigureSecretStore((configuration, stores) =>
89+
{
90+
string vaultUri = configuration["Azure:KeyVault:VaultUri"];
91+
stores.AddAzureKeyVaultWithManagedIdentity(vaultUri, CacheConfiguration.Default);
92+
});
93+
94+
WebApplication app = builder.Build();
95+
app.UseRouting();
96+
app.Run();
97+
}
98+
}
99+
```
100+
101+
> Note that during the configuration of the secret store, you will be able to access the application configuration; in this case it is used to retrieve the URI where the Azure Key Vault is located.
102+
103+
### 3. Inject the Arcus secret store in application
104+
Now that the Arcus secret store is added and configured to the application, the application can use it to retrieve it secrets. The Arcus secret store is accessible throughout the application via the `ISecretProvider` interface - combining all the configured secret providers.
105+
106+
In the `OrderController`, inject the `ISecretProvider` interface via the constructor. The `ISecretProvider` will allow you to retrieve the Azure Service Bus connection string from the secret store.
107+
```csharp
108+
using Arcus.Security.Core;
109+
110+
[ApiController]
111+
public class OrderController : ControllerBase
112+
{
113+
private readonly ISecretProvider _secretProvider;
114+
115+
public OrderController(ISecretProvider secretProvider)
116+
{
117+
_secretProvider = secretProvider;
118+
}
119+
120+
[HttpPost]
121+
public async Task Post([FromBody] Order order)
122+
{
123+
string connectionString = await _secretProvider.GetRawSecretAsync("Azure_ServiceBus_ConnectionString");
124+
125+
// Post Order to Azure Service Bus...
126+
}
127+
}
128+
```
129+
130+
## Conclusion
131+
In this user guide, you've seen how the Arcus secret store can be added to an existing application to retrieve secrets. The Arcus secret store is a very wide topic and can be configured with many different options. See [this documentation page](../03-Features/secret-store/index.md) to learn more about the Arcus secret store.
132+
133+
## Further reading
134+
- [Arcus secret store documentation](../03-Features/secret-store/index.md)
135+
- [Azure Key Vault secret provider](../03-Features/secret-store/provider/key-vault.md)
136+
- [Create your own secret provider](../03-Features/secret-store/create-new-secret-provider.md)
137+
- [Introducing Arcus secret store](https://www.codit.eu/blog/introducing-secret-store-net-core/)
138+
- [The power of the Arcus secret store](https://www.codit.eu/blog/the-power-of-the-arcus-secret-store/)
139+
- [Role-based authorization by low-level customization of the Arcus secret store](https://www.codit.eu/blog/role-based-authorization-low-level-customization-arcus-secret-store/)

‎docs/versioned_docs/version-v2.0.0/03-Features/secret-store/_category_.yml

+1
Original file line numberDiff line numberDiff line change
@@ -0,0 +1 @@
1+
label: 'Secret store'

‎docs/versioned_docs/version-v2.0.0/03-Features/secret-store/azure-functions.md

+110
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
---
2+
title: "Azure Functions support"
3+
layout: default
4+
---
5+
6+
# Using secret store within Azure Functions
7+
This separate documentation section explains how the Arcus secret store can be used within Azure Functions environments (both in-process and isolated).
8+
9+
## Using secret store within in-process Azure Functions
10+
To more easily configure the secret store, we provided a dedicated package that builds on top of the `IFunctionsHostBuilder`:
11+
12+
## Installation
13+
For this feature, the following package needs to be installed:
14+
15+
```shell
16+
PM > Install-Package Arcus.Security.AzureFunctions
17+
```
18+
19+
### Usage
20+
The secret stores are configured during the initial application build-up in the `Startup.cs`:
21+
```csharp
22+
using Microsoft.Azure.Functions.Extensions.DependencyInjection;
23+
using Microsoft.Extensions.Configuration;
24+
using Microsoft.Extensions.DependencyInjection;
25+
26+
[assembly: FunctionsStartup(typeof(Startup))]
27+
28+
namespace MyHttpAzureFunction
29+
{
30+
public class Startup : FunctionsStartup
31+
{
32+
public override void Configure(IFunctionsHostBuilder builder)
33+
{
34+
builder.ConfigureSecretStore((FunctionsHostBuilderContext context, IConfiguration config, SecretStoreBuilder stores) =>
35+
{
36+
var keyVaultName = config["KeyVault_Name"];
37+
stores.AddEnvironmentVariables()
38+
.AddAzureKeyVaultWithManagedIdentity($"https://{keyVaultName}.vault.azure.net");
39+
})
40+
}
41+
}
42+
}
43+
```
44+
45+
Once the secret providers are defined, the `ISecretProvider` can be used as any other registered service:
46+
```csharp
47+
using Arcus.Security.Core;
48+
49+
namespace Application
50+
{
51+
public class MyHttpTrigger
52+
{
53+
public MyHttpTrigger(ISecretProvider secretProvider)
54+
{
55+
}
56+
57+
[FunctionName("MyHttpTrigger")]
58+
public async Task<IActionResult> Run(
59+
[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequest req,
60+
ILogger log)
61+
{
62+
return new OkObjectResult("Response from function with injected dependencies.");
63+
}
64+
}
65+
}
66+
```
67+
68+
## Using secret store within isolated Azure Functions
69+
Since isolated Azure Functions are built with the default `HostBuilder`, the general secret store packages can be used in this environment. No need to install the dedicated `Arcus.Security.AzureFunctions` package.
70+
71+
### Usage
72+
Using the available extensions on the `HostBuilder` or `IServiceCollection`, the secret store can be added, just like a Web API or console application.
73+
74+
```csharp
75+
var host = new HostBuilder()
76+
.ConfigureFunctionsWorkerDefaults(builder =>
77+
{
78+
79+
})
80+
.ConfigureSecretStore((context, config, stores) =>
81+
{
82+
builder.AddEnvironmentVariables()
83+
.AddAzureKeyVaultWithManagedIdentity($"https://{keyVaultName}.vault.azure.net");
84+
})
85+
.Build();
86+
```
87+
88+
Once the secret providers are defined, the `ISecretProvider` can be used as any other registered service:
89+
```csharp
90+
using Arcus.Security.Core;
91+
92+
namespace Application
93+
{
94+
public class MyHttpTrigger
95+
{
96+
public MyHttpTrigger(ISecretProvider secretProvider)
97+
{
98+
}
99+
100+
[Function("MyHttpTrigger")]
101+
public HttpResponseData Run(
102+
[HttpTrigger(AuthorizationLevel.Function, "get", "post", Route = null)] HttpRequestData req,
103+
ILogger log)
104+
{
105+
var response = req.CreateResponse(HttpStatusCode.OK);
106+
return response;
107+
}
108+
}
109+
}
110+
```

0 commit comments

Comments
 (0)
Please sign in to comment.