Provide documentation how to consume secrets (#54)

* Provide documentation how to consume secrets

Signed-off-by: Tom Kerkhove <[email protected]>

* Remove unused variable in test

Signed-off-by: Tom Kerkhove <[email protected]>

* Remove specific version from README

* Be more explicit about the installation

* Fix formating

* Highlight default cache duration

README.md

@@ -9,7 +9,7 @@ Security for Azure development in a breeze.
 Soon you will be able to install it via NuGet:
 
 ```shell
-PM > Install-Package Arcus.Security.Secrets.AzureKeyVault -Version 0.1.0-alpha
+PM > Install-Package Arcus.Security.Secrets.AzureKeyVault
 ```
 
 # Documentation

docs/auth/azure-key-vault.md

@@ -0,0 +1,33 @@
+---
+title: "Authentication for Azure Key Vault"
+layout: default
+---
+
+## Authentication
+
+As of today we support a few  authentication mechanisms.
+
+### Managed Service Identity
+You can use [Managed Service Identity](https://docs.microsoft.com/en-us/azure/active-directory/managed-identities-azure-resources/overview) to delegate the authentication to Azure via `ManagedServiceIdentityAuthenticator`.
+
+```csharp
+var vaultAuthenticator = new ManagedServiceIdentityAuthenticator();
+var vaultConfiguration = new KeyVaultConfiguration(keyVaultUri);
+var keyVaultSecretProvider = new KeyVaultSecretProvider(vaultAuthenticator, vaultConfiguration);
+```
+
+This is the recommended approach to interact with Azure Key Vault.
+
+### Service Principle
+Authentication via username and password is supported with the `ServicePrincipalAuthenticator`.
+
+```csharp
+var clientId = Configuration.GetValue<string>("Arcus:ServicePrincipal:ClientId");
+var clientKey = Configuration.GetValue<string>("Arcus:ServicePrincipal:AccessKey");
+
+var vaultAuthenticator = new ServicePrincipalAuthenticator(clientId, clientKey);
+var vaultConfiguration = new KeyVaultConfiguration(keyVaultUri);
+var keyVaultSecretProvider = new KeyVaultSecretProvider(vaultAuthenticator, vaultConfiguration);
+```
+
+[&larr; back](/)

docs/features/secrets/consume-from-key-vault.md

@@ -0,0 +1,17 @@
+---
+title: "Consuming Azure Key Vault secrets"
+layout: default
+---
+
+## Consuming Azure Key Vault secrets
+You can easily create a Key Vault secret provider - The only thing you need to do is specify how you want to configure and to what vault.
+
+```csharp
+var vaultAuthenticator = new ManagedServiceIdentityAuthenticator();
+var vaultConfiguration = new KeyVaultConfiguration(keyVaultUri);
+var keyVaultSecretProvider = new KeyVaultSecretProvider(vaultAuthenticator, vaultConfiguration)
+```
+
+You can find a list of supported authentication schemes for Azure Key Vault [here](./../../auth/azure-key-vault).
+
+[← back](/)

docs/features/secrets/general.md

@@ -0,0 +1,52 @@
+---
+title: "Consuming Secrets"
+layout: default
+---
+
+## Consuming secrets
+Every provider implements `ISecretProvider` which makes it easy to use a consistent flow, regardless of the provider.
+
+You can easily retrieve secrets as following:
+
+```csharp
+var secret = await secretProvider.Get("EventGrid-AuthKey");
+```
+
+## Caching Secrets
+Some secret providers recommend to cache secrets for a while to avoid hitting the service limitations.
+
+We provide a `CachedSecretProvider` which allows them to be cached in memory for a certain amount of time.
+
+```csharp
+var cachedSecretProvider = new CachedSecretProvider(secretProvider);
+var secret = await cachedSecretProvider.Get("EventGrid-AuthKey");
+```
+
+If you prefer a more fluent approach you can also use our `WithCaching` extension.
+
+```csharp
+var cachedSecretProvider = new KeyVaultSecretProvider(vaultAuthenticator, vaultConfiguration)
+                                    .WithCaching();
+var secret = await cachedSecretProvider.Get("EventGrid-AuthKey");
+```
+
+### Configuring the cache
+By default we only keep them around for **5 minutes**, but you can configure this yourself.
+
+```csharp
+var cacheConfiguration = new CacheConfiguration(TimeSpan.FromMinutes(10)); // Optional: Default is 5 min
+var cachedSecretProvider = new CachedSecretProvider(secretProvider, cacheConfiguration);
+var secret = await cachedSecretProvider.Get("EventGrid-AuthKey");
+```
+
+### Forcing a secret refresh
+In some scenarios you'd like to skip the cache and do a hard refresh by looking it up in the provider.
+
+This is important because in certain scenarios your secrets can be rolled and thus you will be revoked access.
+After a hard refresh you can use the latest secret again and proceed your work.
+
+```csharp
+var secret = await cachedSecretProvider.Get("EventGrid-AuthKey", ignoreCache: true);
+```
+
+[← back](/)

docs/index.md

@@ -8,12 +8,19 @@ redirect_from:
 
 # Installation
 
+We provide a NuGet package per provider and area. 
+
+Here is how you consume secrets for Azure Key Vault:
 ```shell
-PM > Install-Package Arcus.Security.Secrets.AzureKeyVault -Version 0.1.0-alpha
+PM > Install-Package Arcus.Security.Secrets.AzureKeyVault
 ```
 
 # Features
-No features are supported yet.
+- **Interacting with Secrets**
+    - [General](features/secrets/general)
+    - [Consume from Azure Key Vault](features/secrets/consume-from-key-vault)
+- **Authentication**
+    - [Azure Key Vault](auth/azure-key-vault)
 
 # License
 This is licensed under The MIT License (MIT). Which means that you can use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the web application. But you always need to state that Codit is the original author of this web application.

src/Arcus.Security.Tests.Unit/KeyVault/Configuration/KeyVaultConfigurationTests.cs

@@ -40,7 +40,6 @@ public void Constructor_RawUriWithHttp_ThrowsUriFormatException()
         {
             // Arrange
             string vaultUri = $"http://{Guid.NewGuid():N}.vault.azure.net/";
-            var expectedVaultUri = new Uri(vaultUri);
 
             // Act & Assert
             Assert.Throws<UriFormatException>(() => new KeyVaultConfiguration(vaultUri));