Thumbnail Using custom certificates when debugging SPFx Solutions

Using custom certificates when debugging SPFx Solutions

Using the available gulp trust-dev-cert command, we can generate a certificate for use when debugging SPFx solutions. When running in a devcontainer on Windows though, it’s actually easier to use your own localhost certificate. This is how you can do that.

Executing gulp trust-dev-cert in SPFx solutions running on Windows is a breeze. It creates a certificate and installs it for you into your Windows certificate store. If you are a fan of Docker and devcontainers, like me, it’s a bit more complex. The gulp command will generate a certificate in the following folder: $home/.rushstack/, but as it is running within a linux context, it will not be able to auto-install it in your Windows certificate store. The idea is that you can execute a few steps to still do that:

  1. Run gulp trust-dev-cert
  2. Run cp $HOME/.rushstack/rushstack-serve.pem rushstack-serve.pem to copy the certificate file into your SPFx solution root folder.
  3. Download the file to your Windows machine using the VS code context menu.
  4. Open your Windows certificate manager and manually import the certificate into the ‘Trusted Root Certification Authorities’ folder.

This however is a a lot of steps that you have to repeat for every new SPFx solution. Oh, and a minor point: it does not work on my machine! I still get the dreaded certificate error:


It’s actually a lot easier to generate your own certificate and copy that into your SPFx solutions. This involves a few one-time steps to create the certificate. After that you can re-use it for every SPFx solution you create. 💪 Easy-peasy!

For this occasion I found a great gist guide to create a custom localhost certificate with root CA.

Note: You'll need to install the OpenSSL toolkit to get this working. The easiest way to install it is through winget or chocolatey.

This is how it works:

First you create your own CA root certificate:

openssl req -x509 -nodes -new -sha256 -days 1024 -newkey rsa:2048 -keyout RootCA.key -out RootCA.pem -subj "/C=NL/CN=Blimped Root CA DEV"
openssl x509 -outform pem -in RootCA.pem -out RootCA.crt

You’ll see three RootCA certificate files have been created on your disk. Right click the RootCA.crt file and click install. Follow the wizard and install the certificate into the ‘Trusted Root Certificate Authorities’ folder.

First create a text-file called domains.ext with the following contents. Save it on your disk to the location where your RootCA files have just been created.

keyUsage = digitalSignature, nonRepudiation, keyEncipherment, dataEncipherment
subjectAltName = @alt_names
DNS.1 = localhost

Now execute the following OpenSSL commands to create a localhost certificate based on the domains.ext file and the Root certificate:

openssl req -new -nodes -newkey rsa:2048 -keyout localhost.key -out localhost.csr -subj "/C=NL/ST=CloudState/L=CloudCity/O=Blimped/CN=localhost.local"
openssl x509 -req -sha256 -days 1024 -in localhost.csr -CA RootCA.pem -CAkey RootCA.key -CAcreateserial -extfile domains.ext -out localhost.pem

The last step is to copy the certificate to the exact location in your SPFx solution where gulp trust-dev-cert normally creates them. The easiest way to do this is to copy the contents in the following way:

$dataPem = Get-Content .\localhost.pem -Raw
$dataKey = Get-Content .\localhost.key -Raw

$script = @"
echo '$dataKey' > `$HOME/.rushstack/rushstack-serve.key
echo '$dataPem' > `$HOME/.rushstack/rushstack-serve.pem
$script | Set-Clipboard    

Now head over to your VS Code devcontainer instance, open the terminal and just hit Ctrl + V to paste the script you’ve got on your clipboard. And hit enter one last time. The certificate contents are now saved to the correct files in your .rushstack folder. You can now hit gulp serve and start debugging safely and securely. If all is well, you’ll now see your own certificate featured:


Using your own certificates in an SPFx devcontainer is much easier than generating them using the gulp tool. Step 1 + 2 written above need only be executed once. you can save your localhost certificates somewhere safe. Everytime you start a new SPFx project, just run step 3 again, copying the certificate into your new devcontainer.

🌤️ Happy serving!

spfx docker
Support me by sharing this


More blogs

SharePoint Framework, Docker, Dev Containers and NPM linking
SharePoint Framework, Docker, Dev Containers and NPM linking

When using SPFx Library Components we are instructed to execute npm link when debugging our webparts. But what if we are using dev containers?

Read more
How to copy views in SharePoint
How to copy views in SharePoint

There's currently no way to copy list and library views in the SharePoint UI. I've created a SPFx sample demonstrating how it can be done using code.

Read more
Contributing as a holiday season present
Contributing as a holiday season present

Last month I contributed to an Open Source project: CLI for Microsoft 365. I did that both because I love using CLI's and because I love not reinventing wheels.

Read more


Thanks for reading

Thanks for reading my blog, I hope you got what you came for. Blogs of others have been super important during my work. This site is me returning the favor. If you read anything you do not understand because I failed to clarify it enough, please drop me a post using my socials or the contact form.

Warm regards,

Microsoft MVP | Microsoft 365 Architect

Microsoft MVP horizontal