Integration

Integration Testing

This project doesn't yet have automated tests for integration, so here is how to manually test.

Testing in development using ngrok

To test this project, 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 v2 by running ngrok http -bind-tls=false 5000 or ngrok v3 by ngrok http --scheme=http 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. Set your app to use Let's Encrypt staging environment so you don't hit rate limits in generating certificates.

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

        o.AcceptTermsOfService = true;
        o.EmailAddress = "admin@example.com";
    });

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.AddLettuceEncrypt()
        .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.AddLettuceEncrypt()
        .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 test certs

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.