Preparing an SSL certificate for upload to Zendesk

<div class="article-banners">
<div id="docs-wmp-link"><a href="https://support.zendesk.com/hc/en-us/articles/5411234991258-plan" target="_blank" rel="noopener noreferrer">What's my plan?</a></div>
<div class="article-banner" id="support_all"><figure class="wysiwyg-table wysiwyg-table-align-left"><table><tbody><tr>
<td><strong>Support</strong></td>
<td>Team, Professional, or Enterprise</td>
</tr></tbody></table></figure></div>
</div><div class="note">
<span class="notetitle">Note:</span> Zendesk can provide a free SSL certificate for your host-mapped domain or domains on Team, Professional, or Enterprise plans, see <a href="https://support.zendesk.com/hc/en-us/articles/4408838571930#topic_zvd_zbk_rw">Getting a Zendesk-provisioned SSL certificate</a>.</div><p>You can buy an SSL certificate and upload it to your Zendesk account to configure host mapping. Host mapping is the process of mapping a subdomain of your own domain (such as support.mycompany.com), to your default Zendesk address, see <a href="https://support.zendesk.com/hc/en-us/articles/4408838571930">Changing the address of your support website on Zendesk</a>.</p><p>Zendesk only supports SNI-based SSL certificates, and not support IP-based SSL certificates. The certificate must <em>not</em> be password protected and must be one of the supported certificate types:</p><ul>
<li data-list-item-id="ed1cf84a72baf4dfad0e38987eb172c58"><code>ECDSAWithSHA256</code></li>
<li data-list-item-id="e73bb9e18a4473993ffcffa0e73ed0312"><code>SHA256WithRSA</code></li>
<li data-list-item-id="e263bb33000cd4c3579ca42960d9b7e89">
<code>SHA1WithRSA</code> (not recommended)</li>
</ul><p>Before you buy, make sure your certificate authority supports SHA-2 encryption and that the CSR file generated uses SHA-2 encryption. This is also applicable to an intermediate certificate if used.</p><p>After purchasing an SNI-based SSL certificate, in most cases, the certificate authority will send you an email or direct you to a location where you can download your certificate. The email or download location may contain a single SSL certificate or multiple SSL certificates.</p><p>The certificate authority's instructions are often unclear about which files you really need and whether you should prepare them before uploading them to Zendesk. This article helps you determine which files to upload to Zendesk.</p><p>The following steps help you determine which files to upload to Zendesk:</p><ol>
<li data-list-item-id="ea6f8ada192b518d1525e47a1c19fc2ac"><a href="#step1">Identifying your certificate files</a></li>
<li data-list-item-id="e011eda9200a62ce9da3be6bc38c71f1b"><a href="#step2">Creating a certificate bundle for upload</a></li>
<li data-list-item-id="e7f518d55a6f334bdb63d85fd655962d2"><a href="#step3">Getting a key file for upload</a></li>
</ol><h2 id="h_01HJ6X7D60PZKEH3RDHT6TXCWA"><span id="step1">Step 1: Identifying your certificate files</span></h2><p>You purchased a SSL certificate and received an email or download location. Here's what you should do next.</p><ol>
<li data-list-item-id="e1517bea92e1a7022a10d1b115470f9b8">
<p>Read the instructions provided by the certificate authority.</p>
<p>These instructions should help you identify what files are attached or downloadable and ultimately required.</p>
</li>
<li data-list-item-id="e3627b721809f07b3dd69ea33eb427541">
<p>Check for a .PEM file.</p>
<p>If your email or download link contains a file identifying itself as a <em>certificate bundle</em> and the file has a <strong>.PEM</strong> file extension, you're in luck. You only need this single file.</p>
<p>Download the .PEM file and skip to <a href="#step3">Step 3: Getting a key file for upload</a> below.</p>
</li>
<li data-list-item-id="e246ac54e6f6130ac1f4df29afb39100d">
<p>If you don't have a .PEM file, download the primary server certificate.</p>
<p>By default, the certificate authority should always provide you with a <em>primary server certificate</em>. This is the SSL certificate that you purchased. It's also the only certificate file that is unique to your subdomain or domain. Typically, this file has a <strong>.CRT</strong> file extension and is named something like "yourdomain.crt" or contains your unique subdomain in the file name.</p>
</li>
<li data-list-item-id="e61b2ec43132fd5bfb15abce3f6d67b4e">
<p>Determine if you also need an intermediate certificate.</p>
<p>In some cases, the instructions or documentation from the certificate authority explicitly state that you need to download and install an <em>intermediate certificate</em> or certificates along with your primary server certificate.</p>
<p>If your instructions don't mention an intermediate certificate, skip to <a href="#step3">Step 3: Getting a key file for upload</a> below.</p>
<p>Otherwise, find out where the certificate authority is serving the intermediate certificate and download the file or files. An intermediate certificate is normally a .CRT file and contains either the word "Intermediate" or the name of the certificate authority in the file name.</p>
</li>
<li data-list-item-id="e591691f2b905d37960a6fdac13eda091">
<p>Determine if you also need a root certificate.</p>
<p>Your instructions or documentation may explicitly state that you must download and install a <em>root certificate</em> with your SSL certificate.</p>
<p>If your instructions don't mention a root certificate, go to <a href="#step2">Step 2: Creating a certificate bundle for upload</a> below.</p>
<p>Otherwise, find out where the certificate authority is serving the root certificate and download the file. A root certificate is normally a .CRT file and contains the name of the certificate authority in the file name.</p>
</li>
</ol><h2 id="h_01HJ6X7D61V4A3VMWMG7PE2DMF"><span id="step2">Step 2: Creating a certificate bundle for upload</span></h2><p>In the previous step, you downloaded an intermediate certificate and possibly a root certificate with your primary server certificate. This section describes how to prepare the files for upload to Zendesk. The process involves combining the files into a single file, which is often referred to as a <em>certificate bundle</em>.  </p><div class="note">
<span class="notetitle">Note:</span> If your certificate authority provided you with a .PEM file, or if you didn't have to download an intermediate or root certificate, skip to <a href="#step3">Step 3: Getting a key file for upload</a>.</div><div class="note important">
<span class="notetitle">Important:</span> If you have more than three certificates in your bundle, continue with the steps in this article to create and upload the PEM file, then <a href="https://support.zendesk.com/hc/en-us/articles/4408843597850" target="_self">contact Zendesk Customer Support</a> so we can finish the upload process for you. You can also contact Zendesk Customer Support if the upload status remains in pending for an hour or more. When submitting the ticket to Zendesk, don't include any attachments other than the PEM file. Confirm with your issuer if you aren't sure about the correct certificate position in the PEM bundle.</div><p><strong>To create a certificate bundle for upload</strong></p><ol>
<li data-list-item-id="e1694f35babb565e8153c2e6481de505d">
<p>Open each downloaded certificate file in a text editor.</p>
<p>The contents of each file should contain a block of encoded text that begins with <kbd>-----BEGIN CERTIFICATE-----</kbd> and ends with <kbd>-----END CERTIFICATE-----</kbd>.</p>
</li>
<li data-list-item-id="ee72bd2bd759f7cb3631ff1dff3acbeb4">Create a blank text file in the editor.</li>
<li data-list-item-id="e63c686d5b2339bbf3483e5d2a3716d24">
<p>Add the contents of each certificate into the new file in the following order:</p>
<ol>
<li data-list-item-id="ed286e6d597b8cd4d3d327d2c68fb0d5e">Primary server certificate</li>
<li data-list-item-id="e203d1771ec1ad886e4a44ad6db36d059">Intermediate certificate(s)</li>
<li data-list-item-id="ed27c1f19b58fdfa7f099aea7db05d7f7">Root certificate</li>
</ol>
<p>If you only have the primary and intermediate, don't worry about the root certificate.</p>
<p>Don't leave any spaces between the certificate blocks, as shown below:</p>
<pre class="wysiwyg-code-block"><code class="language-auto"> -----BEGIN CERTIFICATE-----
(Your primary SSL certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your intermediate certificate)
-----END CERTIFICATE-----
-----BEGIN CERTIFICATE-----
(Your root certificate)
-----END CERTIFICATE-----
</code></pre>
</li>
<li data-list-item-id="e136b4b4fded3e0398ca2872a03f71773">Remove any leading or trailing spaces in the formatting.</li>
<li data-list-item-id="e9a88302727ae27394b620b347bd17969">
<p>Save the file with a .PEM file extension.</p>
<p>If necessary, select "All File Types" from the Save options of your editor, then save the file using the .PEM file extension. Example: <kbd>mycertificatebundle.pem</kbd>.</p>
<p>If the editor won't let you save the file with a .PEM extension, don't worry. Simply save the file, locate it in your drive, and change the extension to .PEM.</p>
</li>
</ol><p>After creating your certificate file, go to <a href="#step3">Step 3: Getting a key file for upload</a> below.</p><h2 id="h_01HJ6X7D61WE7F9RHV9KQEA0ST"><span id="step3">Step 3: Getting a key file for upload</span></h2><p>Before uploading your certificate file to Zendesk, find out if you also need to upload a private key (.key file), with the certificate.</p><p>To determine if you need a key file, ask yourself the following question: When I went through the process of generating a <em>certificate signing request</em> (CSR), did I generate it in Zendesk, or did I generate it somewhere else?</p><ul>
<li data-list-item-id="e9034fa6ee514f0bfd9c6cda37ed98acb">If you generated the CSR in Zendesk, you don't need a .key file. The certificate file is all you need to upload.</li>
<li data-list-item-id="ea4b173e12a73231cc58e497ecbca3e74">If you generated the CSR somewhere else, you'll need to upload your private key with the certificate. The .key file is always generated at the same time as your CSR. It should be located where you generated your CSR.</li>
</ul><p>After you've assembled the necessary files - the certificate file and, if applicable, a .key file - you can upload them to Zendesk. For instructions, see <a href="https://support.zendesk.com/hc/en-us/articles/4408838571930#topic_wtp_kqk_j4b" target="_self" rel="undefined">Uploading the certificate</a>.</p>