README.md

Integration Testing

This project has automated tests for integration, but you can test it manually if you choose.

Testing in development using ngrok

To test that the Let's Encrypt API is working correctly, I recommend the following steps.

1. Download and install ngrok, a command-line tool for creating a publically accessible tunnel to your computer.

2. Start ngrok by running ngrok http -bind-tls=false 5000. This will create a temporary, public URL http://TMP.ngrok.io

3. Edit your hosts file to redirect http://TMP.ngrok.io to localhost

   sudo vim /etc/hosts
   

   Add a new line for "127.0.0.1 TMP.ngrok.io"

4. Update Let's Encrypt Set your app to use Let's Encrypt staging environment so you don't hit rate limits in generating certificates.

    .UseLetsEncrypt(o =>
    {
        o.DomainNames = new[] { "TMP.ngrok.io" };
        o.UseStagingServer = true; // <--- use staging

        o.AcceptTermsOfService = true;
        o.EmailAddress = "[email protected]";
    })

5. dotnet run your application.

And voila! The API should automatically provision and create an HTTPs certificate for TMP.ngrok.io.

Testing Azure KeyVault

In order to test KeyVault storage/retrieval, follow these steps:

1. Follow the ngrok steps above.

2. Create a key vault instance in Azure (see docs for details)

3. Add an account you have credentials for to the access policies for Certificates with the Get and Import permissions.

4. Update ConfigureServices method to set up Azure KeyVault access:

public void ConfigureServices(IServiceCollection services)
{
    services.AddLetsEncrypt()
        .AddAzureKeyVaultCertificateSource(o =>
        {
            o.AzureKeyVaultEndpoint = "https://[url].vault.azure.net/";
        })
        .PersistCertificatesToAzureKeyVault();
}

1. dotnet run your application. Azure.Identity will attempt to use default credentials to log into the configured KeyVault. If there are issues with using default credentials, consult the documentation for details. This can be set with the following:

public void ConfigureServices(IServiceCollection services)
{
    services.AddLetsEncrypt()
        .AddAzureKeyVaultCertificateSource(o =>
        {
            o.Credentials = new SomeCredentials();
            o.AzureKeyVaultEndpoint = "https://[url].vault.azure.net/";
        })
        .PersistCertificatesToAzureKeyVault();
}

The certificate should now be persisted to KeyVault and will be retrieved at startup.

Trusting dev certs from Let's Encrypt

By default, certificates generated by Let's Encrypt's staging certificates will not appear as a trusted certificate.

To trust a test certificate, on macOS

1. Open up "Keychain Access" and search for your certificate.

2. Right click on the certificate on click "Get Info"

3. Under the "Trust" section, change the drop-down to "Trust" and close the info window. This should prompt you for a password.

4. Refresh your browser.

CI/CD With Docker

Automated tests run on each pull request to build all .csproj files in this repository using GitHub Actions and Ansible scripts to deploy a container to a public facing Docker host. Following deployment, the page on the deployed container is checked for a matching GITHUB_SHA value that matches the commit that triggered the container build.