Custom domain names allow you to set a more familiar or organization-specific URL for your Samanage instance self-service portal, for example, support.yourcompany.com. By default, when you use Samanage we will create a personalized domain name for you at yourcompany.samanage.com. In order to use one or more custom domain names, it is important to create the proper CNAME record in your DNS **before** adding the domain in the Setup.
If you enter a custom domain name, you MUST also enable SSL. if you use a custom domain and do not have an SSL certificate uploaded into the app, you will NOT be able to access your account via that non-secure URL. SSL stands for Secure Sockets Layer and is a standard security layer to encrypt traffic between the server and the client. You get to host your custom domain name on a secure connection and can use https access to your support.yourcompany.com site.
In this article, we will cover all steps that need/can be taken to use a custom domain name for Samanage. We will start with adding a CNAME to your DNS record, then we will add the domain in Samanage and finally, we will enable SSL.
The CNAME should point from your service desk URL (i.e. support.yourcompany.com) to your URL in Samanage (i.e. yourcompany.samanage.com).
You MUST create the proper CNAME record in your DNS **before** adding the domain. This will be a guide focusing on providing a general idea on how to create a CNAME for domain mapping. This can deffer per use case and vendor.
In this example, we will take a look at GoDaddy's steps on creating a CNAME.
1.1 In the DNS Zone File, click Add Record.
1.2 From the Record type list, select A (Host).
1.3 Complete the following fields:
- Enter an Alias Name - The address you want the record to link to (Ex: support.yourcompany.com)
- Points to Host Name - The destination address which would your original Samanage address (Ex: yourcompany.samanage.com)
- TTL - Designate how long the server should cache the information
1.4 Click the Save button and the Save Changes button.
Please keep in mind that your hosting provider's DNS Manager layout may look a bit different than GoDaddy's but should essentially work in a similar manner. .
Note: If you choose to enter a custom domain name, you MUST also enable SSL for it. If you use a custom domain and do not have an SSL certificate uploaded into the app, you will NOT be able to access your account via that non-secure URL.
2. Domain mapping
To enable SSL encryption on your custom domain name, we have to host your SSL certificate for you on our system. An SSL certificate must be bought from an SSL vendor. You can get some comparison on leading SSL vendors from WhichSSL. When asked to choose the SSL vendor which Apache server version, it is recommended to choose ModSSL. ModSSL mostly provides a superset of the functionality of all the other solutions.
Samanage allows to upload SSL certificates directly in the application (See: 3.1 SSL Certificate) in Setup > Domain Mapping after a CNAME is added and the domain is added. Samanage does not support uploading wildcard certificates through the application, please see the steps at 3.2 Wildcard SSL Certificate on how to upload your wildcard certificate. We recommend using a certificate with an SHA-2 signature.
A deployed SSL can be checked by using a tool like this.
3.1 SSL Certificate
Should you choose to enable SSL on your custom domain, you will be required to follow a five-step process:
3.1.1 Setting up a custom domain is under the setup menu, see the following screenshot:
3.1.2 You will need to create a Certificate Request by filling the form with the required fields and submit the form.
See the following screenshots of the filled form an generated certificate request.
3.1.3. Copy the Certificate Request that was just generated and paste it into your chosen Certificate Authority vendors form (like GoDaddy or vendors from WhichSSL).
On their website, you will receive, after due process and payment, the actual Certificate.
3.1.4 Once you obtain the new Certificate from the Certificate Authority, come back to this page and paste the Certificate into the form and submit it for processing.
3.1.5 In the final step our Engineering team will deploy the new Certificate on our servers.
You will be notified via email once the process is completed. You will then also notice the updated status on this page.
3.2 Wildcard SSL Certificate
We do not support uploading wildcard certificates through the application, but they can be uploaded manually by our Engineering team. This is because giving out your wildcard certificate reveals your private key as well, which could potentially compromise your security. It is a general recommendation that wildcard certificates not be given outside of your corporate environment. If you wish to use a wildcard certificate please follow these steps:
Our Engineering team would need the following information:
The certificate to be uploaded (.crt file)
The private key associated with the certificate
The domain name the certificate is being uploaded for
The preferred format for the certificate and key is PEM. If you send the data in an encrypted file (e.g. pfx) make sure that you also provide the password.
To speed up the process make sure the certificate and the private key match, you can check this here.
You can send this directly to Samanage Support at firstname.lastname@example.org and we would immediately forward this information over to our Engineering team so that your Wildcard SSL certificate is uploaded in a timely fashion and send out an update once the upload is completed.
Why upload a Wildcard SSL Certificate?
- Using the Wildcard certificate of your site helps you avoid having to purchase a subdomain certificate for the Samanage app.
- You may possess a special type of certificate that our user interface currently doesn't support generating a Certificate Signing Request for meaning Engineering's assistance is needed.
Using your site Wildcard SSL Certificate under Samanage is not recommended. It is remanded to have separate subdomain certificate for Samanage.
When sending us an encrypted certificate/key it is recommended to separate the password from the files (e.g. put the password on the ticket and send the files to the email).
ANY certificate format should work, with the caveat that if it's a wildcard certificate we will also need the private key (as mentioned above), as well as the actual certificate. Some formats combine these, others don't. Some formats auto-encrypt the data with a passkey, others don't. That's really the only difference.
Please contact email@example.com when you have any questions regarding Domain mapping or SSL.