Skip to main content

Use your own domain

Goal​

Serve your portal at an address your organisation owns — portal.acme.com — instead of, or as well as, the address your Parsware installation gave it.

Before you start​

You need two things, and neither of them is in Parsware:

  1. A domain you control, and somebody who can add records to its DNS. In a lot of organisations that is not the person building the portal, so it is worth asking early: the gap between requesting a DNS record and getting one is usually measured in days.
  2. A CNAME record pointing your chosen name at your Parsware installation. Ask whoever runs your installation what the target should be — it is the same address your portal already answers at, the one shown in the Web address box.

Steps​

  1. Open your solution, choose Portals, and open the portal.

  2. Under Your own domains, press Add a domain and type the whole name a visitor would type — portal.acme.com, not acme.com and not https://portal.acme.com.

  3. Press Save. This is the step that matters: the record you have to publish does not exist until the domain is saved, because it contains a code created for this portal and this domain.

  4. Open the portal again. Under the domain you will now see a TXT record — a name and a value.

  5. Ask your DNS administrator to publish exactly that record. It looks like this:

    TypeTXT
    Name_parsware-verification.portal.acme.com
    Valueparsware-domain-verification= followed by your code

  6. Press Check now. If the record has travelled, the domain turns to Verified and the address starts answering. If it has not, the screen says so and remembers that we looked — this is not an error, it is the answer, and it is the usual one for the first few minutes. Press it again later; a DNS change can take a while to reach us, and checking as often as you like costs nothing.

Why you have to prove it​

Anyone with permission to edit a portal can type any domain into that box. If typing were enough, one person could point a colleague's portal — or a completely different customer's — at a name they had no right to, and the platform would obtain a certificate for it and start serving.

So a domain is a claim until it is proved, and a claim does nothing at all:

  • It does not answer. Visiting it reaches nothing, whatever your DNS says.
  • No certificate is obtained for it, so a browser sent there shows a security warning rather than your portal.
  • It does not appear as an address anywhere, and a portal with no other address cannot be Published.

Only somebody who can publish a record inside a domain can prove they control it, which is exactly the question that needs answering.

Two people can claim the same domain. Only one can prove it.

Unlike the Web address box — where a name is taken the moment somebody saves it, because the installation owns those names — a domain you own is arbitrated by DNS. Two portals may both list portal.acme.com, and whichever one's code is actually published is the one that gets it. That is deliberate: refusing the second claim would let whoever typed a name first lock its real owner out of their own domain.

Once a domain is verified for one portal, no other portal can verify it. To move a domain, remove it from the portal that holds it, save, and then verify it on the other one.

What can go wrong​

"No proof was found." The record is not there yet, or it does not match. Check three things, in this order: that the name starts with _parsware-verification. (the underscore matters — a plain TXT record on portal.acme.com cannot exist alongside the CNAME), that the value is the whole string including the parsware-domain-verification= part, and that enough time has passed.

"We could not look up…" That one is ours, not yours. Your DNS is fine; our lookup did not get an answer. Try again in a few minutes.

The domain is verified but the page will not load. Verification proves the name is yours; it does not point it at us. Check the CNAME.

It stopped working after somebody edited the portal. Removing a domain from the list removes its proof with it. Adding it back is a fresh claim with a fresh code, so the old TXT record will no longer match — publish the new one.

Where the platform has to build a link itself — a sign-up confirmation e-mail, an invitation — it uses the Web address your installation issued, in preference to a domain of your own. That address always works. Your own domain is used for those links only when the portal has no platform address at all, and then only once it is verified.