2019-03 on Funky Si's Blog (Dev)

Documenting your API

funkysi1701@gmail.com (funkysi1701) — Wed, 27 Mar 2019 20:00:45 +0000

So you have created a super API that does something amazing. How do you document it so people will use it?

One way of easily documenting your API is to install the Swashbuckle package.

Install-Package Swashbuckle.AspNetCore
Install-Package Swashbuckle.AspNetCore.Swagger

Then in you startup.cs add the following lines

//In ConfigureServices

services.AddSwaggerGen(c =>
{
 c.SwaggerDoc("v1", new Info { Title = "API", Version = "v1", Description = "An API Description" });
 c.IncludeXmlComments(string.Format(@"{0}\API.xml", System.AppDomain.CurrentDomain.BaseDirectory));
});

//In Configure

app.UseSwagger();

app.UseSwaggerUI(c =>
{
 c.SwaggerEndpoint("/swagger/v1/swagger.json", "API V1");
 c.RoutePrefix = string.Empty;
});

Now when you browse to your API you will see the swagger documentation system.

The RoutePrefix setting controls the path in which swagger will display. I have my docs at the root, but you might want them under the /docs or similar path.

The IncludeXmlComments setting from the ConfigureServices method allows you to load in any XML comments you have added to methods. For this to work you need to enable a setting to your build.

The XML documentation file must be ticked and contain a path. Everytime you do a build, a XML file will be generated which contains all the comment blocks you have added to your code.

Swagger will then use this XML documentation file to produce lovely looking documentation without you having to do anything extra.

Azure Key Vault

funkysi1701@gmail.com (funkysi1701) — Tue, 19 Mar 2019 20:00:45 +0000

Azure Key Vault is a secure way of storing your keys, certificates and secrets so your application can access everything it needs to but you don’t have them being stored insecurely anywhere such as in source control.

I have been wanting to give Azure Key Vault a try for a while now as it can make use of Azure Active Directory to give your web app an identity so it can authenticate itself into the key vault to access secrets. Pretty clever but with a lot of moving parts a bit complex.

For my example I am just going to connect to my Key Vault and get a secret and display it somewhere on a web page. This is of course not what you want to do as secrets are secret and shouldn’t be displayed just used to authenticate into whatever, however it is an easy way to prove I am connecting to the Key Vault and everything is working.

Lets look at some code. I have a .net core application and to start with lets install three nuget packages.

Microsoft.Azure.KeyVault
Microsoft.Azure.Services.AppAuthentication
Microsoft.Extensions.Configuration.AzureKeyVault

I’ve not include version numbers as these will no doubt get updated over time but hopefully it will still work.

Now in your Program.cs add the following code, replacing [KeyVaultName] with the name of your Key Vault.

 public class Program
 {
 public static void Main(string[] args)
 {
 CreateWebHostBuilder(args).Build().Run();
 }

 public static IWebHostBuilder CreateWebHostBuilder(string[] args) =>
 WebHost.CreateDefaultBuilder(args)
 .ConfigureAppConfiguration((context, config) =>
 {
 var builtConfig = config.Build();

 var azureServiceTokenProvider = new AzureServiceTokenProvider();
 var keyVaultClient = new KeyVaultClient(
 new KeyVaultClient.AuthenticationCallback(
 azureServiceTokenProvider.KeyVaultTokenCallback));

 config.AddAzureKeyVault(
 $"https://[KeyVaultName].vault.azure.net/",
 keyVaultClient,
 new DefaultKeyVaultSecretManager());
 })
 .UseApplicationInsights()
 .UseStartup<Startup>();
 }

Now all you need to do is look at your configuration to pull out secrets from your Azure Key Vault. If you have a secret called AppSecret then you can use the following code snippet to retrieve its value, assuming _configuration is an implementation of Microsoft.Extensions.Configuration.IConfiguration.

_configuration["AppSecret"];

Now if you do all of this and run from an Azure Web App or run locally it will fail to pull anything from the Key Vault. You need to give your web app an identity and configure your key vault to allow access from that identity.

Once my code has been deployed to an Azure Web App I get the following error.

Lets look at fixing that, first lets give my web app an Identity. Open up the Azure portal and find the identity section of your web app and turn the setting on.

Now you need to grant that identity permission to your key vault. In the portal open up Access Policies in your key vault and click add Policy, select the identity of your web app in the principal box and select the following settings to grant access to your secret.

Now you have a website that can pull secrets out of Key Vault but only that unique identity. Anyone who has access to your source code will not have access to your secrets, even if they push your code to a different Azure Web App.

Tech I want to learn more about

funkysi1701@gmail.com (funkysi1701) — Tue, 05 Mar 2019 20:00:45 +0000

While at Microsoft Ignite I heard about a lot of cool tech that I want to know more about. The best way to learn something is use it to solve a problem.

So what can I build that is both useful and will let me play with some new tech?

I have a Xamarin Forms app Pwned Pass that has over 500 downloads on Google Play and over 80 downloads on the Microsoft Store. This has given me a small user base that I can use to make use of whatever I build.

My app makes use of the HIBP API created by Troy Hunt. I am going to build my own API, initially it will just make calls to the HIBP API. Building this will give me experience of building something with .net Core from design to deployment. I have made a start already on doing this, I have an empty .net core API project which deploys to an Azure web app using the build and release pipelines from Azure DevOps.

You may be wondering why I am not making use of Azure Functions to build this API. Azure functions is certainly a great technology that is worth learning about. However I have done a little bit with them in the past and I don’t believe I would be able to learn all the things I want to if I used Azure Functions. My primary goal is learning and sharing that learning via this blog. It may well be I move to using Azure Functions later on.

Another tech I am keen to learn more about is Azure Key Vault . This is a technology that allows the securing of keys, connection strings and certificates. I want my app to securely get keys and security information without any of it having to be committed to source code or shared insecurely.

Monitoring my app is also a key learning from me. I use application insights already, but I would like to extend my understanding of this so telemetry can be fed back into the build and bad deployments stopped.

Below is my complete list of learning and tech I want to touch on. It is a long list and I imagine it will get longer as I work through it. I want to regularly blog and share what I have been working on. I currently have a working build and release pipeline but nothing of note to build or release. I know Key Vault needs looking at early as the identity of the website in Azure is key to getting that tech working correctly.

Build API with .net core
Add build and release pipeline
Make use of Azure KeyVault for secrets, connection strings etc
Plugin My Xamarin app to make use of it
Monitor my API with Application Insights
Secure it with CSPs and log this into Report URI
Consider building a web frontend to my API using a javascript library or framework. Maybe react but this can be decided later.
Dockerize the API and add the creation of docker images to the build/release pipeline