This article only applies to hosted partners and customers. As a customer, contact your Workspace 365 partner to request a custom URL on your behalf. Self-hosted partners can configure custom URLs themselves.
Introduction
As a hosted partner, you can request a custom URL for your instance or a specific customer environment. If you want to change an environment name, refer to Change Workspace environment name (CR-01).
A custom URL is an additional URL that exists besides the original URL. You can request any URL as a custom URL, as long as the URL itself is available. Custom URLs are a paid service.
Refer to the image below on how custom URLs work. Please note:
An instance URL cannot redirect to a specific environment, as it's designed to be the instance's landing page
With a custom environment URL, that environment can be accessed directly via the custom URL, but the /environmentname will still be added in the browser's URL bar when a user logs in
Request custom URL process
The prerequisites and steps to request a custom URL are described below. Read these carefully and ensure you've done everything you need before submitting the request.
Step 1. Check affected services
When you request a custom URL, several other changes may also be required. Please read the list below to see which apply to you, to make sure everything keeps working as expected. For the Redirect URI in Azure, an additional URI containing the new URL can be added prior to the change as described in step 3. All other changes must be done afterwards.
Azure SSO app registration:
The Redirect URI must be changed to match the new environment name.
The Front-channel logout URL must be changed to match the new environment name.
Liquit: the Content Security Policy (CSP) must be updated.
Workspace 365 Teams integration: the manifest.json file must be updated.
SharePoint intranet: if you have added a SharePoint intranet to the workspace, the portal site connection must be updated.
Step 2. Records
To request a custom URL, certain DNS records must be created for us to be able to configure the URL and request the SSL certificate. We do not manage the domain name and are not in control of any changes concerning DNS. The required changes must be done by you, or your DNS hosting provider.
2.1. CNAME record (always required)
In the customer’s DNS, you need to create a CNAME record for the custom URL that directs to the partner record.
Usually, the partner record is "partnername.partner.workspace365.net".
If you’re not sure what your partner record is, you can mention this when submitting the change request. Our support team can help you further with this.
2.2. CAA records (only if already present)
If there are currently no CAA records on the domain, proceed to the next step. With no CAA records present, we can directly request the SSL certificate.
If the domain already has CAA records, you need to configure the required CAA records as described in Automatic provisioning of SSL certificates so we can request the SSL certificate.
Step 3. Add Redirect URI in Azure
Fill in the Redirect URI, this must be changed to match the new environment name.
Go to portal.azure.com.
Navigate to the Workspace SSO application.
Go to Authentication.
Click Add URL and add the custom URL. For example: 'https://customname.domainname.net/environmentname/OAuth2/HandleAuthorityResponse'
Step 4. Request custom URL
To request a custom URL, you can submit a change request through the following proces:
Submit a request – CR-03 - Custom URL
You will need to provide us with the following information:
New URL
Enter the desired new URL for your instance/environment here.
Do note that the URL needs to be available for us to request it. The original URL will always work, this will be an 'extra' URL.
Redirect
Indicate whether the new URL has to redirect to a specific environment.
If requesting a custom URL for an environment, check the redirect checkbox and enter the environment's current URL.
For example "Portal.workspace365.net/examplecustomer".
If requesting a custom URL for your instance/hostname, leave this checkbox unchecked.
Step 5. Update welcome email URL (OPTIONAL)
The welcome email displays a workspace URL. After the custom URL is configured, it's possible to update this URL to the new custom URL:
Log in as admin via the new custom URL
Go to Settings > Single sign-on
Click Verify, you should see a green screen stating verification was successful
Check the "I have seen the GREEN screen telling the verification was successful" checkbox
Click Done
The welcome email will now be updated to display the new custom URL.