<style>p { margin: 0 0 10px; }h1, h2, h3 { margin: 20px 0 10px; }h4, h5, h6 { margin: 10px 0 10px; }</style><p>When authenticating in Halo, access tokens are signed with a key. We recommend encrypting this key with an X.509 certificate.</p>
<style>p { margin: 0 0 10px; }h1, h2, h3 { margin: 20px 0 10px; }h4, h5, h6 { margin: 10px 0 10px; }</style><h4 id="generate-a-self-signed-certificate">Generate a self-signed certificate</h4>
<p>First, you need to generate a self-signed certificate to use for encryption.</p>
<p>If you have not done this before, you can download a free tool to do this for you here;</p>
<p><a target="_blank" href="https://s3.amazonaws.com/pluralsight-free/keith-brown/samples/SelfCert.zip">https://s3.amazonaws.com/pluralsight-free/keith-brown/samples/SelfCert.zip</a></p>
<p>Run SelfCert.exe.</p>
<p>Under "save as PFX", enter a strong password for your certificate and press Save to PFX file.</p>
<p>This will generate a PFX.</p>
<p><em>Store the password you entered securely. If you lose this, your encrypted data can be permanently lost.</em></p>
<h4 id="install-the-certificate-on-the-halo-server">Install the certificate on the Halo server</h4>
<p>The certificate should be installed in both the Personal and Trusted Root stores of the local machine.</p>
<p>Open the certificate you generated on your Halo web application server.</p>
<p>Choose Store Location as Local Machine and enter the password for the certificate when prompted. No other settings need to be changed, navigate through the wizard and press Finish to install.</p>
<p>Install the certificate again using the same steps as above, but this time select "Place all certificates in the following store", and choose "Trused Root Certification Authorities".</p>
<p>Once installed, obtain the thumbprint of your certificate by opening Certificate Manager on the server. Find the certificate you added. Open it and view the thumbprint. It should look similar to the one below. Copy it as you'll need it for the next step.</p>
<pre><code>15ae61e07414a8b0f9f48c470b1dbd7ab8e0c5b0
</code></pre>
<p>NB: You must also ensure that the IIS_IUSRS local group has access to the private key. This can be done via heading to the certificate, right clicking and navigating to All Tasks > Manage Private Keys.</p>
<h4 id="configure-the-halo-website">Configure the Halo website</h4>
<p>On your Halo web application server, open the website files and open /api/appsettings.json.</p>
<p>Add a comma to the end of the second from the bottom line, insert a new line and add;</p>
<pre><code> "Signing_Certificate": "THUMBPRINT"
</code></pre>
<p>where THUMBPRINT is the thumbprint of your certificate.</p>
<p>This also needs to be added to /auth/appsettings.json in the same way;</p>
<p>Add a comma to the end of the second from the bottom line, insert a new line and add;</p>
<pre><code> "Signing_Certificate": "THUMBPRINT"
</code></pre>
<p>where THUMBPRINT is the thumbprint of your certificate.</p>
<p>Save and restart the Halo website.</p>
<p>To verify this is working, check that "Protect token signing keys with a certificate" is now ticked on the Security page.</p>
<p><em>The check does not test the change was made to auth/appsettings.json - so please double-check this manually.</em></p>
